第一时间捕获有价值的信号
本文译自 X（原 Twitter）上 Augment Code 的帖子 What spec-driven development gets wrong。这篇文章印证了一个重要观点：设计文档、架构图等几乎一写出来就过时了。正确的做法应该是描述需求，让代理起草规范，再拆分任务，进行实时反馈，并且代码文档本身应该作为一个渐进式的知识系统。
你唯一可以 100% 信任的文档是代码本身。
设计文档、变更日志、README、架构图、入门 Wiki。每一个几乎立即就过时了。
让书面产物与不断变化的系统保持同步是一项持续的成本，而工程师是为爆发式工作而生的。编写文档，发布功能，继续前进。更新部分是看不见的工作，它与某一天中的其他所有事情竞争，而且它几乎每次都会输掉那场竞争。我们尝试过流程。我们尝试过工具。我们尝试过让它成为团队价值观。没有一个奏效，因为我们一直在要求人类做人类可靠地不会做的事情。
这就是规范驱动开发通常失败的地方。这个想法是合理的：当你与编码代理一起工作时，在放开它们之前写下你想要什么。显然比将提示粘贴到聊天窗口并祈祷更好。
但规范是一个文档。而我们刚刚确定了文档会发生什么。
区别在于风险所在。一个过时的设计文档会误导恰好阅读它的下一个工程师。一个过时的规范会误导不知道更好的代理。它们会自信地执行一个不再与现实匹配的计划，而且它们不会标记任何事情出错了。
所以当我们开始构建时，我们一直绕圈子的问题是：如果规范不是你维护的东西会怎样？如果它自我维护会怎样？
这是我们最终得出的结论。
规范不是人类产物或代理产物。双方都从中读取并向其写入。
你描述你想要构建什么。一个协调代理起草规范，将其拆分为任务。你查看它，编辑它，在任何事情运行之前批准。一旦代理开始工作，它们会写回更新：它们发现了什么，什么改变了，它们遇到了哪些不在计划中的约束。你可以在任何点暂停，重写规范的一部分，代理从新状态继续。
想想当你把任务交给一个优秀的初级工程师时会发生什么。你给他们工单，他们去工作，当他们发现 API 不像工单假设的那样支持分页时，他们自己更新工单。他们不会等你注意到事情不对劲。他们不会只是构建错误的东西。他们回来说：“这个假设是错误的，这是我取而代之做的，这是为什么。“你审阅他们的更新，要么批准要么反驳。
这就是我们想要的开发者和规范之间的关系。工单保持诚实，因为双方都在维护它。
初级工程师的类比比你想象的更深入。一个好的初级不会叙述每一行代码。他们浮出改变方向的决策：“我在代码库中找到了一个现有的 auth 上下文，所以我连接到那个而不是创建一个新的。“这就是信号。这也是你想从代理那里得到的。正确把握这种粒度结果证明是系统中真正有趣的设计问题之一。太多，规范变成了你学会忽略的噪音。太少，你又回到猜测发生了什么。
这是一个任务实际上看起来的样子。你写道：“向设置页面添加一个深色模式切换，尊重系统偏好。“协调器读取你的代码库，起草一个包含三个子任务的规范：添加切换组件、将其连接到偏好存储、更新 CSS 变量。
你浏览它，注意到它错过了跨会话持久化选择的部分，并添加一行。
你批准。
代理开始工作。
十五分钟后，其中一个更新了规范：“在代码库中找到了一个现有的主题上下文提供者。连接到那个而不是创建一个新存储。”
你审阅代码更改（清楚地按代理和任务分组）。
规范现在反映了实际构建的内容，而不是最初计划的内容。而且没有人必须记得更新它。
软件中每个文档优先的倡议都因为同样的原因失败了：它要求开发者做没有人看到也没有人奖励的持续维护工作。
除非代理做它们那份维护工作，否则 SDD 会因为同样的原因失败。
如果代理可以编写代码，它们可以更新计划。