Axiom 的 SDD 工作流：AI Agent 如何把规范驱动开发真正跑起来

如果 sdd-methodology.md 回答的是「SDD 是什么、团队为什么要用」，那这篇文章回答的是另一件事：当一个 AI 编程 Agent 真正下场执行 SDD 时，它靠什么机制不跑偏。这里的经验来自 Axiom——一个本地优先、谨慎且可审计的桌面端编程 Agent，它的每次任务都运行在「规范、门禁、审批、证据」四重约束之下。

先说结论：Axiom 的 SDD 不是「多写几份 Markdown」，而是一条可回退的闭环——先用 Skill 把需求翻译成规范，再用只读审查子 Agent 做门禁，中间每一步写入都要经过用户批准，最后用构建与 smoke 证据收口。任何一环不通过，就退回上一阶段重做。

一、工作流骨架：一条闭环，两条路径

Axiom 的核心决策原则是按复杂度自主选择路径，不强制套用流程。同样是任务，简单修复和复杂重构走的是完全不同的通道：

路径选择的判断标准不是「用户有没有提 SDD」，而是任务本身的复杂度信号：是否跨多文件、是否触及长期业务边界、是否有行为变化需要验收。复杂度不够就套全流程，是比不套流程更常见的失败——文档膨胀、审查空转、产出与约束脱节。

两条路径共享同一个闭环逻辑：上游产出必须先被门禁审查，审查不通过就回到上一阶段继续完善，通过才允许进入下一阶段。这条回退规则是整个工作流不会「带病前进」的保障。

二、内置 Skill 链：每个阶段只做一件事

Axiom 把 SDD 拆成六个内置 Skill，每个 Skill 有明确的输入输出，互不越权：

这套分工的隐藏经验是：规范生成与实现被刻意隔离在两个技能里。brainstorm/diagnose 只允许产出规范，不允许顺手改代码；implement 只允许按 Plan 落地，不允许中途发明领域规则。AI 最容易犯的错是「边猜边写」，Skill 链把「先定义约束」变成了不可跳过的动作。

另一个值得注意的细节：diagnose 和 brainstorm 是同一层的两个入口，区别只在入口信号——前者从「复现问题」进入，后者从「澄清需求」进入。说明 SDD 不只服务新功能，Bug 修复同样要过规范，否则修出来的只是补丁，不是对约束的维护。

三、产物体系：五个文件类型的职责边界

Axiom 工作流里的文件不是摆设，每个类型的生命周期和所有权都不同：

• .specs/domain/*.md：长期约束空间，只写必须满足的行为、不变量、状态和错误语义，不写实现方案。维护方式是人工长期维护；AI 首次接入时可生成骨架，之后不得越权改写。
• .specs/tasks/<task-id>.md：单次任务规范，描述目标、范围、排除项、验收标准与证据清单。随需求产生和归档。
• .plans/<task-id>.md：实施计划，只描述拆解步骤、顺序、风险、防护栏与回滚方案，受 Task Spec 约束，不能反向覆盖 Domain Spec。
• .specs/status/*.json：状态机，用 SDD slash commands 维护，不手工编辑——状态文件是机器读的，手工改会破坏流程可追溯性。
• .docs/ 与入口文档（AGENTS.md / CLAUDE.md）：实现事实层，记录当前系统怎么运行，是 finish 阶段要对齐的对象。

以项目里真实的 nuxt-major-migration 为例，Task Spec 里同时写着 Scope、Out Of Scope、Acceptance、Progress、Evidence、Risks——「不做什么」和「做什么」一样重要，这是 Task Spec 与普通需求文档最大的区别。Plan 里则写着 Sequencing、Guardrails、Review Checklist、Rollback，四段结构保证了实施过程可复盘、可回滚。

四、审查子 Agent：把「检查」从主流程里剥离出来

Axiom 工作流最有特色的一环，是只读审查子 Agent。它不能写文件、不能执行命令、不能请求审批，唯一职责是对照规范做门禁判定，返回「通过 / 不通过 + 问题清单」。

三个阶段对应三个审查者：

从中沉淀出四条可复用的操作经验：

1. 审查前必须把证据喂给它。review_subagent 没有 git 能力，它判断「改了什么」的权威依据是主 Agent 采集的 git diff 全文。不传 diff 只给意图描述，审查就会漏看实际改动；diff 超过参数上限时按文件分批委派。
2. 审查规模用档位匹配。单文件小审用 light，大规模 Spec 或跨文件高风险用 thorough——预算决定审查深度，小任务过度消耗和大审查半途收口同样是失败。
3. 子 Agent 有固定预算，要学会收口。预算用尽会返回 partial，此时基于已有证据收口，或把 scope 收窄到未覆盖部分后重新委派；不要以同等规模重复委派，配额按父 run 累计。
4. 审查与自查是替代关系，不是叠加关系。小改动由主 Agent 重读改动、对照验收标准自查收口；跨文件或高风险改动才委派独立审查。二者择一，避免重复消耗。

五、与审批和 Git 规则的耦合：SDD 不是悬空的

Axiom 的 SDD 工作流和它的安全边界是同一套系统，这是它区别于纯方法论文档的关键：规范管约束，审批管边界，分支管提交。

• 写入必须逐文件展示并获批。创建、编辑或批量变更前，向用户展示逐文件变更；批量 Patch 使用读取结果中的完整文件 SHA-256 做冲突检测。这与 SDD 的「验收必须客观」是同一个原则在文件层的体现。
• 审批被拒是流程的一部分。被拒后改方案或询问，不原样重试已拒绝的操作——对应 SDD 里「审查不通过就回上一阶段」的语义。
• 提交有分支硬规则。严禁在 main / master 上 commit 或 push，必须先建 ci- 前缀分支再提交推送。finish 阶段的「任务分支提交推送」不是可选项，是工作流出口。
• 命令执行要申报网络与副作用。需要出站网络的命令必须声明 network: true；不得 sudo；不得把输出重定向到工作区外。SDD 的验证动作因此永远是「可见、可审计」的。

六、验证证据链：完成不是一句话，是一串可复现的命令

Axiom 判断「任务完成」不靠自我感觉，靠的是证据链。项目里每个真实任务都沉淀了同一组证据：

npm ci
task check          # lint + typecheck + production build + static generate + smoke
npm audit --audit-level=moderate
git diff --check

task check 覆盖 lint、类型检查、生产构建、静态生成和生成产物 smoke check——这就是 Task Spec 里 Acceptance 的机器化表达。Domain Spec 里的每条不变量（如「公开页面必须输出绝对 canonical、og:url」）都对应一个 smoke 检查点，规则到验证一一映射。

经验是：验收标准必须在 Task Spec 阶段就写成可执行命令或可检查断言，而不是「看起来没问题」。证据链的尽头是 finish 阶段的汇总——说清楚依据哪份 Task Spec、受哪些 Domain Spec 约束、对应哪些验收、通过了哪些验证。

七、失败与收口经验：Agent 工作流里最容易被低估的部分

最后是 Axiom 在执行中反复验证的收口经验，它们共同决定一个 Agent 是「可靠交付」还是「无底洞探索」：

• 工具失败先读错误再调整，不要原样重试已失败的调用；oldText 不匹配就重新 read 后再定位唯一锚点。
• 信息足够即收口交付，不为验证而验证；接近预算上限时基于已有证据给出最终结论，停止扩展探索。
• 测试失败先读报错再定位根因，不臆测；确认修复后再继续，而不是盲目重跑。
• 探索要收敛：先按名称/内容收窄范围，互不依赖的检索并行调用，避免重复 ls / read；大范围探索拆成多个 scope 收窄的批次。
• 遗留项要显式记录：finish 阶段把未完成事项、已知风险和后续建议写进收尾，而不是藏进代码注释。

八、经验清单：把 Axiom 的工作流搬进自己的项目

如果你要在自己的 Agent 或团队流程里复刻这套做法，最值得先落地的六条：

1. 复杂度决定路径：简单改动走快路径，复杂任务才走全流程，别让流程比任务重。
2. 规范与实现隔离：需求澄清和代码实现分属不同阶段，AI 不得在实现时发明领域规则。
3. 每个上游产物都有门禁：Task Spec 被审、Plan 被审、代码被审，审查不通过就回退。
4. 审查者必须能看到证据：给审查子 Agent 传 diff 全文，而不是只传意图描述。
5. 验收写成命令：Acceptance 对应可执行检查，Domain 不变量对应 smoke 断言，完成以证据链为准。
6. 写入有边界，提交有规则：变更逐文件获批，SHA-256 防冲突，ci- 分支隔离提交。

结语

Axiom 的 SDD 工作流真正值得借鉴的，不是那套 Skill 和文件目录的名字，而是它回答了一个具体问题：当执行者是一个会主动探索、会犯错、会被预算和上下文约束的 Agent 时，如何让它的每一步都有规范依据、有门禁把关、有证据收口。Spec 管约束，Plan 管执行，审查管质量，审批管边界，证据管结论——这五件事对齐了，无论是人还是 AI 来执行，系统都不会失控。