长文#7 — spec-driven 下的多 coding agent 工作方式

日期: 2026-10-07 阶段: Phase 4 - 自建 Agent 平台×求职冲刺 标签: #spec-driven #multi-agent-coding #adr-as-contract #architect-role-shift

核心问题

这是 P4 的第 7 篇长文。前 6 篇都在写「AML Copilot 这个系统怎么造」，今天换一个元层级的问题：这个系统是被怎么造出来的？ 答案恰好是 2026 软件工程最大的范式迁移——spec-driven development（规约驱动开发，SDD）：规约（spec）而非代码成为唯一真相源，代码是从规约再生的产物，多个 coding agent 并行地从同一份 spec 实现、验证、收口。

本计划本身就是一个天然的 SDD 实验场：120 天、每天若干篇笔记 + 代码组件，由 agent 团队（Claude Code 之类）执行，而我（架构师）的角色不是写每一行代码，而是写验收门禁、立项目宪法、审 spec 而非审 code。今天用这 120 天的真实构建实践为素材，回答三件事：

1. spec-driven 到底改了什么？ 从「代码是真相、文档会烂」翻转成「spec 是真相、代码可再生」，这一翻转如何重排了所有工程动作。
2. 多 agent 怎么靠一份 spec 协同而不漂移？ 并行标记、phase gate、项目宪法（constitution）如何把「意图漂移（intent drift）」这个 LLM 编码的头号杀手锁死。
3. 架构师的工作方式怎么变？ 从「code reviewer」变成「spec reviewer + constitution 作者」，这对求职定位意味着什么。

ThoughtWorks Technology Radar Vol 34（2026-04）把 spec-driven development 列为正在被采纳的实践——这不是边缘实验，是 2026 主流工程的既成事实。

关键内容

A. 范式翻转：spec 是真相源，代码是再生产物

传统开发的隐性公理是「代码是唯一真相，文档会烂（specs rot）」。架构师写设计文档，团队照着实现，三个月后文档和代码对不上，于是大家只信代码。SDD 把这条公理整个翻转——版本受控、可执行的规约才是唯一真相源（single source of truth），代码是从 spec 再生的输出（thebcms, 2026）。

翻转后的连锁反应：需求变更时，先改 spec，再让代码从新 spec 再生，而不是直接改代码事后补文档；PR 必须引用 spec（feat(auth): magic link, refs specs/004-magic-link/spec.md）；spec 与代码同仓库、同版本演进。SDD 的核心制品（GitHub Spec Kit 口径）：

  SDD 制品层级（spec-kit 标准）
  ──────────────────────────────────────────────
  .specify/memory/constitution.md   ← 项目宪法（最持久）
       · 跨 spec 的不可违反规则：语言、依赖政策、测试标准
       · 用 EARS Ubiquitous 句式写死："系统 SHALL 记录每次认证"
       ↓
  specs/NNN-feature/spec.md          ← 单特性规约
       · User story + EARS 验收准则 + 非功能需求 + 范围外边界
       ↓
  plan.md                            ← 技术方案
       · 架构选择 + 数据模型 + API 契约 + 库选型（附 ADR 链接）
       ↓
  tasks.md                           ← 任务分解（带 [P] 并行标记）
       · 原子、可独立交付的单元，每个挂验收检查
       ↓
  code + tests + docs                ← 从上面全部再生的产物

这个层级的关键是 EARS 记法（Easy Approach to Requirements Syntax）——五种句式让验收准则既精确又可被 AI 解析，比 BDD 的 Given-When-Then（Gherkin）更严格：

反直觉洞察①（specs rot 这条「常识」在 SDD 下不再成立——因为 spec 是被执行的，不是被参考的）：老工程师对「写详细文档」的本能抵触来自一条铁律——文档一定会烂。但这条律的前提是「文档只是被人参考、不被机器消费」。SDD 把这个前提打掉了：spec 是被 agent 直接消费来生成代码、被验证逻辑直接读取来打分的可执行制品。一份没人读的设计文档会烂，但一份每次 /implement 都要被 agent 解析、每个 PR 都要引用、与代码同仓版本化的 spec 不会烂——因为它一旦和代码漂移，下一次再生就会暴露。SDD 不是「逼你写更多文档」，而是「让文档变成不会烂的代码的一部分」。

B. 多 agent 协同：用一份 spec 锁死意图漂移

LLM 编码的头号失败模式是意图漂移（intent drift）——同一个含糊 prompt 喂给 agent 三次，得到三个互不兼容的实现。多 agent 并行时漂移成倍放大。SDD 用三层机制把漂移锁死：

① 共享 spec 作为契约。 多个 agent（Spec Kit 2026 支持 29+ 具名集成：Claude Code、Copilot、Gemini CLI、Cursor、Codex、Kiro CLI 等）读同一份 spec.md，各自抽取验收准则、生成独立实现方案、分解任务、再对照原始 EARS 句式自验。spec 充当「契约」，防止跨 agent 调用的意图漂移（thebcms / GitHub, 2026）。

② tasks.md 的 [P] 并行标记 + checkpoint。 /speckit.tasks 产出的 tasks.md 按 user story 组织、依赖排序、用 [P] 标记可并行任务；每个 user story 段末有一个 checkpoint，校验该阶段功能能独立跑通后才进下一段（GitHub spec-kit, 2026）。这把「多 agent 并行」从混沌变成有依赖图、有验收闸的流水线：

  多 agent 并行执行（tasks.md 调度）
  ─────────────────────────────────────────────
  Story A ──┬── T1 [P] agentX ──┐
            ├── T2 [P] agentY ──┤→ checkpoint A（独立跑通?）─┐
            └── T3     agentX ──┘   失败→停，不进 Story B    │
                                                              ▼
  Story B ──┬── T4 [P] agentZ ──┐                    （A 通过才解锁）
            └── T5 [P] agentX ──┴→ checkpoint B ──→ ...
  ─────────────────────────────────────────────
  [P]=无依赖可并行；无 [P]=须串行；checkpoint=阶段验收闸

③ constitution（项目宪法）作为不可重议的护栏。 没有宪法，每份 spec 都会重新争论同样的决定（用什么语言、能不能加新依赖、测试标准）。宪法把这些写死成 Ubiquitous EARS 规则，agent 受其约束、不再 re-litigate（thebcms, 2026）。SDD 的四阶段工作流，每阶段一个人类 checkpoint：

反直觉洞察②（多 agent 并行的瓶颈不是 agent 能力，是「依赖图 + 验收闸」的设计质量）：直觉以为多 agent 提速靠「换更强的模型」或「开更多并发」。但真正决定并行能不能跑通的是 tasks.md 里 [P] 标记和 checkpoint 划得对不对——如果两个标了 [P] 的任务其实有隐藏依赖（共享一个数据模型），并行只会产出两个冲突实现，比串行还慢。多 agent 工程的核心技能不是 prompt，是把工作正确分解成「真正无依赖的并行单元 + 卡得住的阶段验收闸」——这恰恰是架构师的传统看家本领（依赖分析、接口契约），只是换了个战场。所以 SDD 时代最稀缺的不是会用 agent 的人，是会给 agent 设计依赖图和门禁的人。

C. 本计划的 ADR 实例：把 120 天构建当 SDD 案例

把抽象的 SDD 套到本计划的真实构建上。这 120 天里，我对 agent 团队下的不是「帮我写个 AML 系统」这种漂移源，而是一份份带验收门禁的 spec + 跨笔记复用的 ADR。下表是本计划已沉淀的 ADR 与其充当「不可重议契约」的实例：

这张表说明：CLAUDE.md 就是本计划的 constitution，每篇笔记的「笔记硬规则 / 深度五条」就是该特性的 spec.md，分配给我的任务清单就是 tasks.md。我作为架构师，全程没写一行 src/aml/ 的实现代码，但我写了所有的验收准则（深度五条、κ 阈值、SOTA 检查日）和不可重议的宪法（时效性硬规则、单 agent ADR）。代码是 agent 从这些 spec 再生的产物——这本身就是一份活的 SDD 案例。

落到工具链，2026 的 SDD 工具谱系与本计划的对应：

效能锚点（一手数据）：GitHub 称 Spec Kit 比 ad-hoc prompting 「从头重来」周期少约 10×；AWS 称 40 小时的特性在 spec-driven 下人类时间 <8 小时搞定；DeepLearning.AI 2025 末上线专门 SDD 课程，标志主流化（thebcms / GitHub / AWS, 2025-2026）。单特性人类时间 2–6 小时，绝大部分花在 review 和 clarify，而非 implementation——这正是架构师角色迁移的量化证据。

设计要点/决策表

对本项目的落地

• 新建 .specify/memory/constitution.md（项目宪法，落地决策）：把散落在 CLAUDE.md 与各 ADR 的不可重议规则收口成一份机器可读宪法——全局时效性硬规则、单 agent ADR（Day 33）、judge κ≥0.6（Day 17）、eval gate 阻断 merge（Day 19）、私有化端点抽象（Day 113），全部用 Ubiquitous EARS 句式写死。这让未来任何 agent 在本仓库工作都受同一套护栏约束。
• 为 AML 核心特性补写 specs/ 目录（设计决策）：把已实现的关键模块反向补 spec.md——specs/001-sar-narrative/spec.md（指向 src/aml/sarNarrative.ts，EARS 写验收：faithfulness/coverage 维度 + HITL 签发约束）、specs/002-judge-calibration/spec.md（指向 judgeCalibration.ts，κ 闸门）。这把「代码先行、文档后补」的历史欠债转成 SDD 制品，使系统可被多 agent 安全演进。
• POC 验收契约与 spec 打通（接 Day 114）：Day 114 的 POC 里程碑 gate（κ≥0.6、单案省时≥1.5h、回收期<18月）用 EARS 写成机器可读验收准则，存进 specs/poc/kyc-acceptance.md——这把「承诺数字不承诺功能」从商务话术变成可被 agent 和 CI 共同消费的契约，呼应 Day 114 洞察②。
• tasks.md 并行调度（设计）：未来给 agent 团队下任务时，显式用 [P] 标记真正无依赖单元（如「AML 多屏组件」与「合规映射层」可并行，因二者无共享数据模型），并在每个 user story 末设 checkpoint，避免伪并行产出冲突实现——把 B 节洞察②的「依赖图+门禁」落到本仓库的实际派单。
• 诚实标注：.specify/memory/constitution.md 与 specs/ 反向补写为 P4 工程化动作；本计划过去 114 天的构建是「spec 化但未用 Spec Kit 工具链」的手工 SDD，本日决策是将其工具化、机器可读化。constitution 的 EARS 条款须执行当周与 CLAUDE.md 实际规则逐条核对，防止漂移。

参考资料

1. thebcms — Spec-Driven Development (SDD): The Definitive 2026 Guide：spec 为唯一真相源、constitution/spec/plan/tasks 四制品、EARS 五句式、四阶段工作流 + 人类 checkpoint、SDD subsumes BDD、架构师转为 spec reviewer（2026）
2. GitHub — spec-kit 仓库 + Spec-driven development with AI 博客：/specify /plan /tasks /implement、tasks.md 的 [P] 并行标记 + user story checkpoint、29+ agent 集成、Spec Kit 开源（2025-09 / 2026）
3. Martin Fowler（martinfowler.com）— Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl：三工具对比、Kiro hooks、Tessl 受监管行业审计轨模板（2026）
4. ThoughtWorks Technology Radar Vol 34（2026-04）：spec-driven development 列入采纳实践、AI 辅助开发主线、Langfuse v3 自托管（2026-04）
5. AWS / DeepLearning.AI 口径（经 thebcms 转引）：Spec Kit「从头重来」周期少约 10×、40h 特性 <8h 人类时间、DeepLearning.AI SDD 课程（2025 末）
6. 本仓库 CLAUDE.md（本计划宪法）、docs/aipa/day33-adr-no-multiagent.md、src/aml/judgeCalibration.ts / evalChecks.ts、src/agent/config/llmEndpoint.ts（ADR 实例）(2026-06)

SOTA 检查 (2026-06-11)

• spec-driven development 在 2026-06 是既成主流，非实验：ThoughtWorks Radar Vol 34（2026-04）列入采纳；GitHub Spec Kit（2025-09 开源）、AWS Kiro（2025-07）、Claude Code cc-sdd、Cursor Plan Mode、Tessl 等已覆盖 29+ agent；DeepLearning.AI 2025 末开课。本日 WebSearch×2 + WebFetch（thebcms 一手 + GitHub spec-kit）确认这是当周事实标准。
• EARS vs Gherkin 之争已收敛向 EARS：2026 SDD 工具普遍采用 EARS 五句式作验收记法，因其比 Gherkin 更严格、覆盖异常/可选/状态三类 Gherkin 不擅长的约束。本笔记 AML 验收准则用 EARS 表达，与工具链对齐。
• 效能数字（10×/40h→8h）须执行当周复核：引自 GitHub/AWS 厂商口径（经 thebcms 转引），属供应商宣传量级，实际增益随团队成熟度与任务类型波动。作品集引用时须标注来源与口径，不可当普适保证。
• Spec Kit 集成数在快速增长：本日记 29+ 具名集成（部分来源称 30+），该数字每月在变；执行当周以 github/spec-kit 仓库 README 实时数为准。
• 架构师角色迁移是 live 的求职信号：SDD 把架构师从 code reviewer 推向 spec reviewer + constitution 作者，与 AISA/SA 岗位「定义约束、主导验收」职责合流（呼应 Day 114）。这对求职定位是正向信号——本计划「写规约与门禁、不写实现」的构建方式恰是该角色的活体证明。
• 待跟踪：① ThoughtWorks Radar Vol 35 发布后 SDD 象限是否从 Trial 进 Adopt；② Spec Kit / cc-sdd 是否新增「多 agent 跨 spec 冲突检测」能力（当前 checkpoint 仅校验阶段内）；③ Tessl 受监管行业模板是否覆盖 AML/SR 11-7，若是则为本项目 SDD 工具链首选。以上执行当周重新确认。