让 AI 改代码前先写清功能与验收标准

AI 写代码之后，人还靠什么判断功能有没有做对？作者给出的答案是：先审应用行为的文档，再让 Agent 改代码。/ddd 把这套顺序做成了 AI 编程技能，让需求、计划、验收条件和实现进度都有地方可查。

它最有价值的地方，是把代码 diff 里的业务规则提到人能直接讨论的层面。不过，原文提供的是工作流设计和示例，没有团队实测或对照数据。文档能否持续可信，仍要看执行和验证。

代码改对了，为什么人还是容易看漏

作者用一个聚餐报名应用说明问题：原来每张邀请只允许一人参加，现在允许已确认参加的客人携带一位同伴。示例中的实现涉及五个文件，决定是否进入候补名单的逻辑藏在这行代码里：

const status = taken + need <= dinner.seats ? 'going' : 'waitlist';

要注意 taken + need <= dinner.seats。它判断剩余座位能否容纳这次报名需要的人数，但读者还得追查 need 的来源，才能确认携伴规则，以及座位只够一人时怎么办。

同一个变更，放进文档就能直接审：

- Each invite is for one person.
+ Guests who are going can bring one plus-one.
+ A plus-one takes a seat. If there's room for the guest
+ but not the plus-one, both join the waitlist.

要注意最后两行：如果只够客人本人坐下，却容不下同伴，两人一起进入候补名单。这是需要产品方确认的行为，单看代码很容易漏掉。

业务规则本身就应该成为可以审阅的变更。

产品经理、设计师和提出需求的人，可以直接对某句话发表评论。文档历史也因此有机会记录应用如何演变，而不只是记录文件如何变化。

文档先行，靠什么避免变成补材料

/ddd 要求影响应用行为的改动先进入文档。Agent 展示文档变化，解释用户会受到什么影响，检查是否与其他文档冲突，并在修改代码前征求确认。

文档描述的是使用规则。框架、数据库表等技术选择单独放进 docs/.tech/，不要求所有参与者都理解实现。

原文把 docs/ 分成几个职责明确的位置：app.md 解释应用和用户，roadmap.md 记录后续建设顺序；data/、features/、pages/ 分别描述保存什么、能做什么、用户看到什么；components/ 存放跨页面复用部分，integrations/ 描述邮件、登录、支付等集成，plan/ 保存未完成工作。

功能文档还要记录参与者、规则、后续动作、验收条件和开放问题。例如报名功能规定：持邀请链接即可回复，无须账号；聚餐开始后停止回复；满员后的报名进入候补。

文件头部的 frontmatter，也就是文档元数据，用 type: feature 标明类型，用 uses 声明依赖，用 shown-on 标记出现的页面。示例依赖包括 data/rsvp、data/dinner、integrations/email，展示页面是 pages/dinner。正文还能通过 [[integrations/email#new-reply]] 引用通知规则。

这些关联帮助 Agent 在修改一条规则时，找到需要一起检查的文档。不过，作者没有解释依赖漏写时如何补救。

另一道约束是测试：Agent 将每条验收条件转成测试，目标是在实现偏离文档时让测试失败。每轮交互开始时，它还会检查自上次构建以来的文档变化，接住用户直接编辑、却忘记口头说明的内容。

计划和已上线规则，为什么要分开放

作者给文件位置赋予了状态含义：features/、pages/、data/ 表示已经构建并上线的内容；定稿计划放进 plan/，还在变化的想法放进 plan/ideas/。已有功能的修改也先写独立计划，避免把未来规则提前混入当前说明。

roadmap.md 再把计划分成阶段，其中 phase 1 应该是有人愿意实际使用的最小版本。

原文称它支持 Claude Code、Cursor、Codex 和大多数其他编程 Agent。在项目目录执行 npx skills add fabiogiolito/ddd 安装后，可以使用：

• /ddd 查看自上次构建以来的文档变化。
• /ddd plan <idea> 编写功能和阶段计划，不执行构建。
• /ddd next 按路线图取下一项，澄清未决问题，完成实现并运行测试，随后移动文档、勾选条目，停止并报告。
• /ddd <request> 创建应用或修改功能，先处理文档。

这里有个操作边界没交代清楚：原文既要求改代码前询问，又说 /ddd next 会构建下一项，但没有展示完整确认过程。团队采用前，需要检查技能实际怎样处理授权和中断。

我的判断

我认同把行为文档作为需求审阅入口。相较于只在聊天记录里描述需求，它更容易查找、修订，也更适合让非开发人员参与确认。与分散的需求文档相比，放在仓库里的 Markdown 还便于跟随代码一起审查。

但作者开头提出不再读代码，走得太远。行为文档无法充分说明权限校验是否可靠、并发时会不会超卖、失败后能否恢复。这些仍需要代码审查和有针对性的测试。

验收条件能生成测试，不等于测试已经覆盖了真实风险。

如果文档和测试都误解了同一条需求，两者完全可能一致通过。原文没有给出需求遗漏率、返工量或维护成本的对照数据，因此效率收益目前只能视为作者的经验判断。

另外，把文档移到 features/ 就代表上线，需要实际发布流程配合。代码合并、测试通过和生产发布可能发生在不同时间，目录位置本身无法证明用户已经用到新规则。

能拿来做什么

• 给下一次报名、预约或配额类功能修改补一份行为文档，明确容量不足、截止时间和候补规则，先让需求方审句子，再让 Agent 实现。
• 在日常 AI 编程中使用 /ddd plan <idea> 收拢计划，把未决问题保留下来，确认后再用 /ddd next 逐项推进。
• 从验收条件生成测试后，人工检查是否覆盖了边界情形。聚餐示例里，尤其要验证只剩一个座位、客人携带同伴时，两人是否一起进入候补。
• 将已上线说明与待办计划分开放，并约定何时移动文档。如果团队存在独立发布环节，就让文档状态跟随实际发布结果更新。