我们没有“Align”——我们争论（并交付了更好的系统）

Source: Dev.to

背景

软件项目很少因为有人写不出代码而失败。
在这个项目中，我们使用了相当标准的技术栈：

• 前端： React + TypeScript
• 后端： REST API
• 多名工程师并行开发
• 紧迫的截止日期（那种有趣的）

一切看起来都很正常……直到出现问题。

问题

前端假设了后端尚未实现的字段。
虽然没有出现足以阻止开发的致命错误，但 bug 在周期后期不断出现。

转折点

有人提出了一个危险的问题：

“我们为什么不先定义 API？”

这个问题引发了争论：

• 后端工程师担心失去灵活性
• 前端工程师担心进度变慢
• 还有人说“我们以后再修”（经典）

我们没有假装达成一致，而是把争论摆出来。这就是转折点。

我们的做法

提前定义 OpenAPI 规范

• 根据规范为前端生成 TypeScript 类型
• 将破坏性的 API 变更视为真正的破坏性变更，而不是“哎呀”

强化纪律

• 必须审查规范 PR
• 接受前期变更会稍微耗时更长的事实

权衡

• 后端灵活性： 失去了一些“随意重命名”的自由
• 过程开销： 规范需要纪律和审查，使得某些 PR 的长度堪比小说
• 速度： 初始变更会稍微慢一点

收获

• 前端类型可预测
• 减少后期意外
• Pull Request 审核更为平静

人员影响

最大的收获不是技术层面的，而是人的层面。
我们不再问“为什么缺少这个字段？”而是开始问“这个字段是否应该存在？”

规范迫使我们：

• 清晰命名
• 为职责争论
• 让决策可见

设计评审变成了真正的设计评审，而不是事后检讨。

面临的挑战

• 过早地过度规范，后期需要放宽
• 有个规范 PR 的长度超过了某些小说
• 不小心破坏了 API，却忘记重新生成类型（是的，真的很痛）

协作并不能消除错误，但能让错误提前暴露。

教训

• 协作会提前暴露分歧。
• 沉默比冲突更危险。
• 工具并不能修复团队——它们会让团队的问题显现。
• 明确的契约能减少基于自我的决策。
• 高级工程师不会回避摩擦，他们会主动面对。

良好的协作不是要大家都很友好。当团队不再只追求今天的速度，而是开始为明天的信任进行优化时，代码库也会随之改善。是的——有时这正是从一次争论开始的。