你唯一可以 100% 信任的文档，其实只有代码本身。

设计文档、变更日志、README、架构图、入职 Wiki —— 这些几乎在写完的那一刻就开始过时。

让一份书面材料与持续演进的系统保持同步，本身是一项持续性的成本。而工程师更擅长冲刺式工作：写完文档，上线功能，继续下一个任务。更新文档属于“隐形工作”，每天都在和各种紧急事项竞争，结果几乎总是输。

我们尝试过流程约束，尝试过工具改进，也尝试过把“维护文档”塑造成团队价值观。但都没奏效，因为我们一直在要求人类去做一件人类稳定不会坚持做的事情。

这正是规范驱动开发（spec-driven development）经常失败的地方。这个理念本身没有问题：在和编码 Agent 协作时，先把需求写清楚再放手让它们执行，显然比在聊天窗口里粘贴提示词然后听天由命要好得多。

但规范也是文档。而我们刚刚已经说过，文档的命运如何。

区别在于影响的后果不同。一份过期的设计文档可能会误导下一个阅读它的工程师。一份过期的规范，却会误导毫无判断力的 Agent。它们会自信地执行一个已经偏离现实的计划，而且不会提示任何异常。

因此，当我们开始构建 Intent 时，反复思考的一个问题是：如果规范不需要被“维护”呢？如果它可以自己维护呢？

我们最终的答案是——

规范既不是人类产物，也不是 Agent 产物。双方都从中读取，也都向其中写入。

你描述想要构建的内容。一个协调 Agent 会起草规范，将其拆分为任务。你审阅、编辑、批准之后，流程才会启动。Agent 开始工作后，也会把更新写回规范：它们发现了什么、发生了什么变化、遇到了哪些原计划里没有的约束。你可以在任何时刻暂停，修改规范的一部分，Agent 会从新的状态继续。

想象一下你把任务交给一位优秀的初级工程师。你给他一个 ticket，他开始执行。当他发现 API 并不支持 ticket 中假设的分页方式时，他会主动更新 ticket。他不会等你发现问题，也不会默默做出一个错误实现。他会回来告诉你：“这个假设不成立，这是我改用的方案，以及原因。”你审阅他的更新，决定接受还是调整。

我们希望开发者与规范之间建立的，正是这种关系。ticket 始终保持真实，因为双方都在维护它。

这个类比比你想象得更贴切。一个优秀的初级工程师不会逐行讲解代码。他只会报告那些改变方向的关键决策：“我发现代码库里已经有现成的认证上下文，所以直接复用，而不是新建一个。”这才是有效信号。对 Agent 来说也是如此。找到合适的更新粒度，是系统设计中真正有挑战的问题之一。太多，规范会变成噪音，最终被忽视。太少，你又回到只能猜测发生了什么的状态。

举个具体例子。

你写下：“在设置页面增加一个支持系统偏好的深色模式开关。”

协调 Agent 读取代码库，起草规范，拆分为三个子任务：添加开关组件、连接偏好存储、更新 CSS 变量。

你浏览后发现漏掉了“跨会话持久化用户选择”这一点，于是补充进去。

你批准。

Agent 开始执行。

十五分钟后，其中一个 Agent 更新了规范：“在代码库中发现已有主题上下文 provider，因此接入现有实现，而未创建新的存储。”

你审阅代码变更（按 Agent 与任务清晰分组）。

此时规范反映的是实际构建结果，而不是最初的计划。而且没有人需要特意去记得更新它。

软件世界里所有“文档优先”的尝试失败，原因都相同：它们要求开发者持续做一件看不见、也没有奖励的维护性工作。

如果规范驱动开发想成功，就必须让 Agent 承担一部分维护工作。

既然 Agent 能够写代码，它们也应该能够更新计划。让它们去做。

原文：https://x.com/augmentcode/status/2025993446633492725