给 Coding Agent 一份设计文档，代码结构真的会改变

同一个需求，Coding Agent 给出两份都能通过测试的实现。一份沿着项目既有模块修改，复用已有的业务规则；另一份新建一个大文件，把接口调用、状态处理和业务判断全塞进去。今天看都能跑，半年后的维护成本却可能截然不同。

我们习惯用测试结果判断 AI Coding 是否完成任务。但测试检查的是它覆盖到的行为，通常很难单独回答另一个问题：Agent 有没有把代码放在合适的位置？

10 月 14 日公开的一项研究 The Code of Theseus: Can Agents Rebuild Software from Recovered Design Documents?，用一个很有意思的实验，试着把这两件事分开测量。

研究者先分析已有代码仓库的依赖关系和关键上下文文件，从中恢复三类材料：系统意图、需求和架构设计。随后，他们选取 29 个 Commit0 软件库，让 Coding Agent 在看不到原实现的情况下重建代码。

实验给 Agent 的共同基础是接口契约与部分可见测试，再比较两种输入：一种主要提供系统意图，另一种进一步提供恢复出来的需求和架构文档。目标是观察，设计信息能否影响最终代码，而不只是让 Agent 多通过几个测试。

这里有一个重要前提：研究使用的是从头重建软件库的任务。它与企业里基于存量仓库做增量需求、修 Bug、重构服务的条件并不相同。我们可以从中提炼机制，不能把结果直接照搬到日常研发效率上。

先看功能测试。加入需求和架构文档后，隐藏测试通过率从 33.7% 到 35.8%，提高 2.1 个百分点，但研究报告这个差异没有达到统计显著性。单靠这组数据，不能得出“设计文档显著提高 Agent 功能正确性”的结论。

再看代码结构。对于那些没有被接口契约直接写明的模块，生成结果相对原项目的模块结构 F1 指标从 0.54 提高到 0.63，而且差异具有统计显著性。简单理解，补充设计材料以后，Agent 生成的模块划分更接近原系统。

图：两项指标出现不同变化。功能测试的提升未达统计显著性；结构指标显示生成结果更接近原仓库，并不代表架构一定更好。

两项指标出现不同变化，正是这篇论文最有意思的地方。它提示我们：测试可以检查一部分外部行为，设计信息还能约束代码的内部组织。 两者覆盖的质量问题并不完全相同。

当然，“更接近原来的结构”也不自动等于“架构一定更好”。研究选用了原仓库作为参照，恰好适合验证能否恢复既有设计；真实项目还会涉及原设计本身是否合理、是否需要主动演进。

现在讨论 SDD（Specification-Driven Development，规格驱动开发），很容易把注意力放在流程：是否先出 Spec、是否生成 Plan、是否需要人工确认、哪些步骤可以跳过。

我觉得更值得追问的是，这些中间产物到底向 Agent 提供了哪些原本缺失的信息。

“列表页增加一个筛选项”，可能靠简短的需求说明、相关代码和验证用例就能完成；“统一一套包含多角色、多状态的业务办理流程”，则需要先摸清页面关系、规则复用、模块边界和存量约束。两种任务需要的信息深度不同，没必要强制生成同样厚的文档。

这篇论文能支持的判断，是需求和架构信息对代码组织可能具有独立价值。它还没有回答另一个工程上更难的问题：在不同复杂度的增量需求里，生成、审阅与维护这些设计信息的成本，什么时候能够换来足够的收益。

图：根据任务影响范围调整设计信息的深度，并分别检查功能、约定、模块结构与后续维护。这是本文提出的工程实践框架。

如果想验证 SDD 的工程收益，就应该把验收拆开：功能行为是否正确，工程约定是否遵守，模块职责与依赖是否合理，后续修改是否容易维护。尤其是后两项，不能简单用一个测试通过率替代。

设计信息要发挥作用，首先得可信。论文也坦率提到，自动恢复的文档虽然在清晰度和内部一致性上表现不错，但正确性与抽象层次仍然存在问题。让 Agent 依照一份错误的架构文档行动，可能只是把错误做得更加整齐。

所以在真实仓库里，至少有三件事值得尝试：

第一，区分输入中的业务意图、现有工程事实与待确认的设计决策。不要把模型推测的“现状”直接包装为仓库事实。

第二，按任务风险决定设计信息的深度。简单改动只暴露相关约束；跨模块、跨服务改动再引入更完整的关系与影响范围。

第三，把结构质量纳入回放验证。除了测试结果，还看变更落在哪些模块、是否新增了不必要的依赖、是否破坏原有职责边界。

这需要更好的工程上下文，也需要维护者参与判断；它不会因为换了一个文档模板就自动完成。

CodeTheseus 的启发并不是“写更多文档就能生成更好的代码”。实验支持的是一个更具体的判断：设计信息可能改变生成代码的组织方式，而这种变化不会完整反映在功能测试成绩里。

接下来真正值得做的是增量研发任务上的对照：为同一类需求分别提供不同深度的设计信息，比较最终代码质量、人工审阅成本和后续变更难度。只有算上这些成本，我们才知道哪些任务值得进入完整 SDD，哪些只需要轻量约束。