让 Claude Code 先写规格再动手

让 Claude Code 连写两天代码，最后整批丢掉，原因却是需求理解错了。作者由此开始使用 SDD（Spec-Driven Development，规格驱动开发）：先让代理写出准备做什么、如何验收，由人确认后再动代码。

这套方法值得看的地方，是把需求误解暴露在编码之前，同时让提需求的人看得见进度。不过，文中能证明的是作者的工作方式发生了变化，至于能减少多少返工，还没有对照数据。

代理写得越快，越需要提前确认什么

作者最初只用一句话描述需求，Claude Code 就开始实现。两天后，代码写得很好，却不是实际需要的东西。

问题出在需求到实现之间的空白。代理可以在几分钟内完成过去需要几天的工作，但它只能根据收到的信息推断目标。指令含糊时，实现仍然可能十分完整，直到审查上千行代码，人才发现方向错了。

SDD 把确认需求的时机，提前到了生成代码之前。

按作者的流程，代理先写方案，人读完后批准或要求修改。此时纠正误解，可能只需要补一句话。批准前，代理不能开始编程。

这里还有一个容易被开发者忽略的问题：业务、客服或客户通常不看代码。需求交出去后，他们只能在聊天里追问进度，再收到一句「快好了」。因此，作者想解决的既有实现偏差，也有需求状态不可见。

一份规格怎样变成可验收的工作

作者用「导出当月发票 CSV」举例。Marta 提出三个要求：管理人员能够下载，文件在 Excel 中正常打开，而且只能包含自己公司的发票。

看起来是一句话的功能，实际已经包含操作权限、文件兼容和数据范围。若只告诉代理「加个 CSV 导出」，这些细节就可能由它自行决定。

作者把协作内容分成几类：

• 需求描述用户最终能做什么，使用普通人能理解的语言。
• 方案说明代理准备修改什么、为什么修改，以及哪些内容不在范围内。
• 验收标准说明如何判断做对了，每条需求至少对应一条。例如，Excel 打开文件后重音字符能正确显示。
• 规格记录系统应有的行为，后续改动从这份记录继续。
• 任务把实现拆成代理可以执行的步骤。

方案经过人工批准后，代理才编码、测试，并逐条核对验收标准。Marta 则能看到每条需求从「未开始」走到「开发中」「已测试」和「已上线」。

作者说，自己通常花五分钟读方案。这是个人经验，并不是所有需求的审核耗时。复杂的权限或业务规则，显然还需要相关人员参与判断。

OpenSpec 管文件，Atalaya 补协作入口

作者建议先用 OpenSpec 尝试。它提供开放格式，让代理把方案和规格保存在仓库的文本文件里。

下面三条命令用于安装并在项目中初始化 OpenSpec：

npm install -g @fission-ai/openspec@latest
cd tu-proyecto
openspec init

需要看清第二行：tu-proyecto 是原文中的项目目录占位，实际操作要进入自己的仓库；第一行使用的是 @latest，原文没有固定版本号。

初始化之后，在 Claude Code 中要求「先提出改动方案，再实现」。代理会把方案、规格和任务放进 openspec/changes/，人读完、修正，再允许它继续。

作者认为，这样已经获得了「80 %」的效果。但原文没有解释计算方式，应把它理解为对基础流程价值的主观估计。

剩下的问题是，文件都在仓库里，提需求的人未必看得到。聊天里的「OK」也很难持续关联到某条需求的状态。

于是作者开发了 Atalaya：把任务、sprints、Kanban 和 SDD 放到一起。需求写在任务里，代理通过 MCP 提交方案，人也在任务里批准，代理不能自行批准。每条需求的状态持续展示到上线，规格仍然保存在仓库的 OpenSpec 文件中。

按原文描述，Atalaya 处于早期访问阶段且免费。文章没有展开 MCP 接口、审批约束的实现，也没有给出具体测试方法。文中的「无需付费工具」也不足以证明整个 Claude Code 使用过程免费。

我的判断

这套方法最有价值的部分，是让验收标准在实现前就出现。代码审查能检查实现质量，但仅靠代码，很难判断需求方是否真的想要这个功能。

不过，方案写出来，不等于需求已经正确。 如果审核者只是扫一眼就批准，代理对权限、数据边界的猜测仍然会进入实现。人的审核应集中在行为和边界，而不是只看任务拆得是否整齐。

OpenSpec 与 Atalaya 解决的是不同层面的问题。前者让约定随仓库保存，后者尝试让非开发人员参与审批和跟踪。如果团队已有工单系统，也可以先在现有任务里记录验收标准，并关联仓库方案，是否需要额外工具取决于协作成本。

作者说，普通 bug 或事故可以直接修复，SDD 用于改变行为的工作。这个分界适合快速理解，但执行时还要判断：有些名为修 bug 的任务，同样涉及权限或业务规则变化。

全文没有返工率、交付周期或团队规模的对照数据。它是一套有清晰因果解释的经验流程，还不能据此认定采用后一定更快。

能拿来做什么

• 下次让 Claude Code 实现 CSV 导出之类的功能时，先要求它提交方案，列清用户能做什么、数据范围和验收方式，读完再允许编码。
• 在 Node 项目里尝试 OpenSpec，把 openspec/changes/ 中的方案纳入改动审查，并在完成后逐条核对验收标准。
• 如果需求方不看仓库，就在现有工单中展示需求状态、记录批准结果，并关联规格文件，让对方能确认交付是否符合约定。
• 对明显改变系统行为的需求先试行这套流程，观察实际返工情况，再决定覆盖范围，不必直接照搬作者的「80 %」判断。