第16部分。团队协作与代码审查

在此之前，本教程带领单个开发者完成了SDD的完整周期。在团队中出现第二层复杂性：规范不仅是代理的提示，也是人与人之间的契约。如果这个契约不经审查，代理可能会根据薄弱或不完整的描述实现精确的代码。

团队协作SDD的主要规则：

在合并请求中，不仅审查代码。
审查的是组合：需求 -> 计划 -> 验证事实 -> 变更。

工作流程

flowchart TD
  A["功能分支"] --> B["规范<br/>requirements.md<br/>plan.md<br/>validation.md"]
  B --> C["首次审查<br/>边界和事实是否清晰"]
  C --> D{"可以开始实现吗？"}
  D -- "否" --> B
  D -- "是" --> E["实现"]
  E --> F["按照 validation.md 进行验证"]
  F --> G["拉取请求"]
  G --> H["代码和规范审查"]
  H --> I{"可以合并吗？"}
  I -- "否" --> B
  I -- "是" --> J["合并与重新规划"]

在小团队中，首次审查可以口头进行。在大团队中，最好在合并请求中留下简短评论："边界清晰，验证事实充分，可以开始实现"。这能节省最终审查的时间。

作者在提交合并请求前检查什么

在提交合并请求之前，作者必须回答四个问题。

1. 功能在 specs/ 中是否有单独的文件夹？
2. 代理是否更改了功能边界之外的文件？
3. validation.md 中的所有必填事实都已验证了吗？
4. 如果事实在工作过程中发生了变化，是否清楚说明变化原因？

最后一个问题尤其重要。不好的迹象：代理在测试失败后修改 validation.md，使验证变得更简单。好的迹象：作者在PR中明确说明某个事实不正确，解释原因并添加新的事实。

审查者检查什么

在SDD项目中，审查者查看四个层次。

需求。 是否清楚功能为谁而做，什么在边界内，什么不在边界内，哪些决策已经做出？

计划。 任务组是否符合需求？是否有没有与功能相关的隐藏大规模重构？

事实。 事实是否验证实际行为，而不仅仅是意图？是否至少有一部分机器可验证的事实？

代码。 实现是否符合计划和事实？是否有代理"顺便"做的更改？

如果审查者只看代码，SDD会退化为带有大量Markdown文件的普通审查。

合并请求模板

最小模板已移至附录：appendix-c-checklists.md。可以将其复制到 .github/pull_request_template.md。

模板的意义不在于官僚主义。它迫使作者展示规范与变更之间的联系：

• 哪个规范文件夹与该分支相关；
• 哪些验证事实已通过；
• 哪些事实被推迟及原因；

• 哪些文件在预期范围之外被更改；
• 审查者应特别注意什么。

如果模板比合并请求本身还长，请缩短它。对于大多数功能，6-8项就足够了。

何时在同一分支中修改规范

如果澄清与当前功能相关且不改变项目策略，可以在同一分支中修改规范。

正常修改的示例：

• 明确预期的HTTP状态码；

• 添加界面的人工验证事实；
• 修正路由名称错误；
• 将事实标记为推迟并说明原因；
• 添加实现期间做出的决策。

不好的修改：重写功能边界以匹配已经意外编写的代码。这不是澄清，而是隐藏的任务变更。

何时需要单独的重新规划分支

如果变更影响项目宪法，则需要单独的重新规划分支：

• 技术栈变更；
• 阶段顺序变更；
• 出现新的架构边界；
• MVP定义变更；
• 多个未来功能必须考虑新规则；
• 需要重写 QWEN.md 或团队技能。

这种方法减少冲突并使历史清晰：功能分支实现功能，重新规划分支更改流程或路线图。

roadmap.md 中的冲突

roadmap.md 经常成为瓶颈。两个人可能同时开始不同阶段并都更改路线图状态。

实用规则：

在功能分支中可以读取 roadmap.md 并引用阶段。
最好在合并前或在简短的重新规划分支中更改 roadmap.md 的状态。

如果团队很大，建立路线图负责人规则。这不是流程经理，而是确保阶段状态与现实一致的人。

如何在审查中使用 Qwen Code

Qwen Code 作为第二读者很有用，但不能替代审查者。

好的请求：

/clear
阅读 @QWEN.md、该分支的规范和 git diff。
将实现与 requirements.md、plan.md 和 validation.md 进行比较。
列出差异。
不要更改文件。

不好的请求：

检查合并请求并修复你发现的任何问题。

在第二种情况下，代理混合了审查、修复和决策。在团队协作中，这很危险：审查应首先创建清晰的差异列表，然后作者决定修复什么。

什么不能交给代理自动处理

不要在没有人类决策的情况下交给代理：

• 扩展功能边界；
• 更改技术栈；
• 从 validation.md 中删除事实；
• 更改安全策略；
• 更新多个阶段的路线图；
• 合并合并请求；
• 修改Git历史；
• 删除无法重复的数据或迁移。

代理可以建议更改。人类负责决策。

实践练习

选取任何已实现的 AgentClinic 功能，将其作为思维中的合并请求打开。

1. 找到规范文件夹。
2. 列出 validation.md 中的三个主要事实。
3. 将它们与更改的文件进行比较。
4. 找到至少一个审查者会问的问题。
5. 按照附录C的模板撰写简短的合并请求描述。

如果无法在不猜测的情况下撰写合并请求描述，说明规范的可移植性不足。

相关部分

• 第18部分分析审查中的安全风险：在diff中寻找什么以发现秘密泄露、新的MCP服务器、钩子变更。
• 第20部分（反模式）列出审查者应立即拒绝的情况：没有事实的规范、工作过程中削弱的事实、未来阶段的实现。
• 第17部分描述哪些钩子有助于将部分审查检查自动化。