AIPA 长文#7：spec-driven 多 coding agent 工作方式：架构师如何为 agent 团队写 ADR 和验收门禁
日期：2026-10-07
spec-driven 多 coding agent 工作方式：架构师如何为 agent 团队写 ADR 和验收门禁
日期：2026-10-07
AIPA 长文#7。coding agent 已经从"补全工具"变成"会写一整个 PR 的并行劳动力"，这把架构师的工作方式从"自己写代码"改写成"为一支 agent 团队写规范、写约束、写验收门禁"。本文以本项目 120 天构建实践（workflow 编排多 agent、ADR 链、CI eval gate）为一手素材，把 spec-driven development（SDD）落到一套可执行的"规范即合约、门禁即裁判"方法论。
引言：coding agent 改变的是架构师，而不只是程序员
2026 年关于 AI 编程的讨论已经过了"它会不会取代程序员"的幼稚阶段，进入了一个更尖锐的命题：当一行代码的边际成本趋近于零，瓶颈就从"写代码"移到了"说清楚要写什么、并证明写对了"。 这恰好是架构师的两项核心职责——定义约束、验收结果。
ThoughtWorks 在 Technology Radar Vol. 34（2026-04-15 发布）里把这一年的主题定为"用工程基本功对抗认知负债（cognitive debt）"：AI 生成的代码量越来越大，开发者与系统之间的理解鸿沟随之扩大，团队必须用纪律把 agent"拴在绳上（on a leash）"。Radar 给出的两类控制手段非常清晰（来源：ThoughtWorks Technology Radar Vol. 34, 2026-04）：
- 前馈控制（feedforward）：Agent Skills 与 spec-driven development——在生成之前就约束 agent 该做什么；
- 反馈控制（feedback）：mutation testing 等手段，在人类 review 之前触发 agent 自我纠错。
Radar 同时点名了一个真实风险——"语义扩散（semantic diffusion）"：spec-driven development、harness engineering 这些词在含义稳定前就被到处乱用。所以本文先把术语钉死，再讲方法，最后给本项目的一手实践数据。
本文的核心论点：架构师为 agent 团队工作的产物，不再主要是代码，而是三样东西——规范（spec）、决策记录（ADR）、验收门禁（gate）。 规范告诉 agent 做什么，ADR 锁死"为什么这样做、什么绝不能发生"，门禁在 agent 交付时充当不讲情面的裁判。下文依次展开。
⚠️ 时效性提示：本文主线为 2026 年上半年的 SOTA。GitHub Spec Kit 于 2025 年底开源、2026 年成为增长最快的 SDD 方法（来源：GitHub Blog / Microsoft for Developers, 2026-05）；ThoughtWorks Radar Vol. 34（2026-04）首次把 SDD 与 harness engineering 列为主题条目。旧的"prompt 一把梭"工作流仅作历史对照。
一、为什么"自己写"变成"编排一支 agent 团队"
1.1 一手观察：本计划 120 天构建实践的工作流形态
本项目（momoweb3）的产出——五大并行学习计划、300+ 笔记、十余篇长文、若干 React 组件与数据管线——几乎全程由一套 workflow 编排多个 coding agent 完成。真实的工作形态不是"我打开编辑器敲代码"，而是：
- 编排脚本 spawn 子 agent：一个 orchestrator 脚本按任务派发子 agent，每个子 agent 拿到独立 context window、跑一个聚焦任务、返回结果字符串（本文你正在读的这篇长文，就是这样一个被 spawn 出来的子 agent 的产物）。
- 并行 + 隔离：多个 agent 在各自 worktree 上跑独立 backlog card，互不污染工作树——这正是 2026-04 版 Claude Code 多 agent 工作流的标准形态（来源：DEV Community / CloudZero, 2026-04）。
- 门禁兜底：每个 agent 交付后，typecheck / test / size-budget 等 CI 门禁挡在合并之前（参见本仓库近期 commit：
test(阶2): size-budget gate on committed data artifacts (CI)）。
这套形态的代价也很真实：subagent 密集的工作流大约消耗单线程会话 7 倍的 token（来源：Nimbalyst / Shipyard, 2026）。所以"派 agent"不是免费的，它把成本从"人的时间"换成了"token + 编排复杂度 + 验收成本"——而验收成本，正是架构师要扛的部分。
1.2 数据：agent 把瓶颈从"产出"挪到了"验证"
2026 年多份研究给出了一个反直觉但一致的结论：agent 让初级开发者快、却让资深开发者慢，因为资深者承担了验证开销。
| 指标 | 初级开发者 | 资深开发者 | 来源（YYYY-MM） |
|---|---|---|---|
| 生产力提升 | +10%~30% | −19%（验证开销拖累） | State of AI Coding Efficiency, 2026-04 |
| PR 产出提升 | ~+40% | ~+7% | Larridin Benchmarks, 2026 |
| AI 代码引入的安全漏洞倍数 | — | 2.74×（vs 人写） | getPanto / 2026 治理报告, 2026 |
| 缺陷暴露窗口 | — | 部署后 30~90 天才浮现 | 同上 |
读这张表的 PM/架构师视角：agent 把代码"产出"这个环节压到近乎免费，于是系统的吞吐瓶颈整体移到了"验证"。如果验证还靠人肉逐行 review，资深工程师就成了新瓶颈（−19% 那一行）。解法不是少用 agent，而是把"验证"也工程化、自动化、前置化——这就是 spec-driven 的全部动机。
二、spec-driven development：把"说清楚"变成工序
2.1 SDD 的标准工序
spec-driven development 的核心是：不直接跳到代码，先把"要做什么"写成结构化规范，让它成为 agent 生成、测试、验证的唯一事实来源（source of truth）。 2026 年三个代表框架的工序高度收敛：
| 框架 | 工序 | 定位 | 来源（YYYY-MM） |
|---|---|---|---|
| GitHub Spec Kit | Spec → Plan → Tasks → Implement | 30+ agent 通用（含 Claude Code/Copilot/Gemini CLI），Specify CLI 脚手架 | GitHub Blog, 2026-05 |
| OpenSpec | Propose → Apply → Archive | 轻量规范层，人与 agent 在写码前对齐"建什么" | ThoughtWorks Radar Vol.34, 2026-04 |
| AWS Kiro / 其他 | requirements → design → tasks（EARS 句式） | IDE 内嵌，强调可测需求 | 2026 行业综述, 2026-05 |
三者的共同骨架是把一次模糊的"帮我做个 X"拆成四道工序：先把意图写成 spec（合约）→ 再让 agent 出 plan（怎么做）→ 拆成可验收的 tasks（颗粒度）→ 最后才 implement（写码）。 每一步都有人类审批点，避免 agent 在意图不清时"猜"。
2.2 为什么这对"金融/高风险系统"尤其重要
我做的是金融零售方向的 Web3/AI 系统。金融场景里 agent"猜错意图"的代价是不可逆的资金损失或合规违规。spec-driven 在这里的价值不是"提速"，而是把决策从 agent 手里收回到人手里：spec 与 ADR 是人审批的，agent 只负责在已批准的约束内实现。这与 EU AI Act Article 14"人类监督必须能真实否决"的精神同构——前置的 spec 审批就是一种结构化的人类监督。
三、为 agent 团队写 ADR：从"记录决策"到"可执行约束"
3.1 ADR 的角色变了
传统 ADR 回答"我们决定了什么、为什么"。在 agent 工作流里，ADR 多了一层职责。2026 年业界一个被反复引用的对照（来源：AI Advances / gopubby, 2026）：
传统 ADR 回答："我们决定了什么、为什么？" 面向 agent 的约束文件回答："基于这个决定，改这块代码时，什么绝不能发生、什么必须永远成立？"
也就是说，面向 agent 的 ADR 不再只是给人读的历史档案，而是 agent 写代码前必须吞进 context 的可执行约束。理想形态是："人批准决策、agent 实现决策，ADR 里包含 agent 写出正确代码所需的一切，让它不必再回头问。"（来源：DeepWiki / ceaksan.com, 2026）
3.2 PRD → ADR → SPEC 的决策链与门控
一个成熟的 agent 工作流会维护一条 PRD → ADR → SPEC 的治理链：PRD 定义产品意图，ADR 锁死架构决策与不可违反约束，SPEC 落到文件级的可实现颗粒。关键在于"门控（gate）"——把这些决策映射到具体文件，并在 agent 改动时对照决策做拦截（来源：DeepWiki rjmurillo/ai-agents, 2026）。常见做法是用 hook 把 ADR review 设为提交前的强制项，Architect agent 负责 ADR 撰写、设计 review、原则强制执行。
把它对到本项目：CLAUDE.md 顶部的"全局时效性硬规则"本质就是一条 ADR-as-constraint——它不是建议，是每个学习类 agent 在生成内容前"必须显式执行的操作清单"，并规定了"禁止引用已停服项目""版本号必须显式""文末必须有 SOTA 检查"等绝不能违反的约束。这就是面向 agent 的 ADR 的实物样本：人写一次，约束所有后续 agent。
3.3 架构师写 ADR 的新清单（面向 agent 版）
结合上述实践，给 agent 团队写一条 ADR 时，除了传统的"背景/决策/后果"，必须补三段：
- 不变量（invariants）：改这块代码时，什么必须永远成立（例：审计流必须 append-only、金额计算必须走幂等路径）。
- 禁区（never-do）：什么绝不能发生（例：禁止引用已死项目、禁止把密钥写进 client bundle）。
- 验收钩子（acceptance hooks）：这条约束如何被机器检查（例：typecheck 类型守卫、test 断言、size-budget gate、grep 规则）。没有第 3 段的 ADR，对 agent 等于没写——因为 agent 不会被"善意提醒"约束，只会被"会 fail 的门禁"约束。
四、验收门禁：agent 工作流里不讲情面的裁判
4.1 门禁 = 把"验证"从人肉搬到机器
第 1.2 节那张表的结论是"验证成了新瓶颈"。门禁就是解药：把人类 review 里能形式化的部分前置成自动检查，让 agent 在交付前自己撞墙、自己纠错，人类只 review 机器查不了的那部分。 ThoughtWorks 把这归为"反馈控制"，AI 研究里把它叫 Planner-Worker-Judge 模式——judge/validator agent 充当质量检查点，迭代精炼直到达标（来源：ThoughtWorks Radar Vol.34, 2026-04；Inngest ADR-0005, 2026）。
4.2 本项目的门禁分层（一手实践）
本仓库实际运行的门禁，可以分成四层，从硬到软：
| 层 | 门禁 | 检查什么 | 失败后果 | 自动化程度 |
|---|---|---|---|---|
| L1 类型 | typecheck（tsc） | 类型契约、接口形状 | 阻断合并 | 全自动（CI） |
| L2 测试 | test（含 size-budget gate） | 行为正确性、产物体积预算 | 阻断合并 | 全自动（CI） |
| L3 构建 | build 绿 | 可打包、可部署（→ Pages 自动部署） | 阻断上线 | 全自动（CI） |
| L4 纪律 | 诚实标注 / SOTA 检查 / 引用带日期 | 内容时效性、不虚构、不引死项目 | 人审 + 规则 grep | 半自动 |
L1–L3 是机器裁判：agent 交付的 PR 跑不过 typecheck/test/build 就根本进不来。这把"代码能不能跑"这类验证彻底从人身上卸掉。本仓库 commit 历史里那条 test(阶2): size-budget gate on committed data artifacts (CI) 就是 L2 的实物——它防的是 agent"顺手"把大文件提交进来撑爆产物体积。
L4 是最有意思也最难的一层：诚实标注纪律。AI 生成内容最大的隐性风险不是语法错，而是"自信地编造"（2.74× 漏洞、30–90 天后才暴露）。本项目用三条可检查的纪律对冲：
- 每条参考资料必须带 (YYYY-MM) 日期——可以用 grep 规则近似检查"有没有不带日期的引用"；
- 文末必须有 SOTA 检查段落——结构化要求，缺了就是不合格；
- 禁止引用已停服项目——这条目前仍需人审，但它被写成了硬约束而非建议。
把诚实做成"纪律 + 可检查规则"，而不是寄希望于模型"自觉"，是 agent 内容工作流能不能信任的分水岭。
4.3 CI eval gate：把"质量"也变成门禁
代码可以 typecheck，但"这篇长文写得对不对""这个 RAG 答得准不准"没法用 tsc 查。这就需要 eval gate——把评测当成 CI 的一道门。本项目 AIPA 长文#1 专门讲过"从 recall@k 到生产级 evals"，思路一致：为内容/模型输出建回归评测集，把"通过率低于阈值就 fail"接进 CI。对 agent 团队，eval gate 的意义是把第 4.1 节的"judge agent"固化成可重复、可回归的自动门，而不是每次靠一个临时 reviewer 拍脑袋。
五、把它缝起来：架构师在 agent 团队里的一天
综合前四节，给出架构师为 agent 团队工作的闭环工序（也是本项目实际跑的形态）：
- 写 spec：把意图写成结构化规范（Spec→Plan→Tasks），人审批，作为 source of truth。
- 写 ADR：锁死架构决策，补"不变量 / 禁区 / 验收钩子"三段，让约束可被机器检查。
- 编排 agent：orchestrator spawn 子 agent，各自 worktree 并行跑 task，互相隔离。
- 门禁裁判：L1 typecheck → L2 test/size-budget → L3 build → L4 诚实纪律/SOTA/eval gate，层层拦截。
- 人审残差：人类只 review 机器查不了的部分（意图对不对、约束该不该改、ADR 要不要演进）。
这套闭环把架构师的角色从"最强的那个程序员"重定义为"规范与门禁的设计者"。agent 负责量产，门禁负责把关，人类负责定义"对"。
结语：从写代码到写"对的定义"
2026 年 coding agent 的真正冲击，不是让架构师失业，而是把架构师的产出从"代码"上移到"约束"。当生成代码近乎免费，稀缺的能力变成两件事：能不能把意图写成 agent 不会误解的 spec，能不能把"对"写成机器能裁判的门禁。 spec-driven development 把第一件事工序化，ADR-as-constraint 与分层门禁把第二件事工程化。
ThoughtWorks 用"认知负债"提醒我们：放任 agent 量产而不建门禁，债迟早要还（30–90 天后那批缺陷）。本项目 120 天的一手经验印证了反面——只要 spec 清晰、ADR 可执行、门禁不讲情面，一支 agent 团队就能稳定产出可信的代码与内容。架构师的工作没变少，只是变了形状：不再亲手砌每一块砖，而是画出墙的样子、并造好那把检查每块砖是否合规的尺子。
SOTA 检查（2026-06-11 更新）
- 当前主流方案：spec-driven development（SDD）在 2026 年已是 AI 编程的主流方法。GitHub Spec Kit（Spec→Plan→Tasks→Implement，支持 30+ agent）、OpenSpec（Propose→Apply→Archive，ThoughtWorks Radar Vol.34 收录）、AWS Kiro、Claude Code/Cursor/Google Antigravity 各自的 SDD 变体并行存在。多 agent 编排（worktree 隔离 + hook 门禁 + Planner-Worker-Judge）是 2026-04 的标准形态。
- 是否仍是 SOTA：是。截至 2026-06，SDD + 门禁工程（harness engineering）是 ThoughtWorks Radar Vol.34（2026-04）确认的当季主线，无更新替代范式出现。
- 更新替代品 / 风险：(1) "语义扩散"——spec-driven development、harness engineering 等词含义尚未稳定，跨团队沟通需先对齐定义；(2) 多 agent 工作流 ~7× token 成本与资深开发者 −19% 生产力的"验证税"，意味着门禁自动化程度决定 ROI；(3) eval gate 标准化仍在早期，"内容质量门禁"目前多为团队自建而非现成工具。
- 本文时效边界：所有引用均标注 (YYYY-MM)；主线案例（Radar Vol.34 = 2026-04、Spec Kit 增长 = 2026-05、生产力研究 = 2026-04）均在近 6 个月内。若读到本文时已晚于 2026-12，请重新核验 Radar Vol.35 是否调整了 SDD/harness engineering 的雷达环位。
学习资源（按发布日期）
- ThoughtWorks Technology Radar Vol. 34（2026-04）：spec-driven development、harness engineering、Agent Skills、mutation testing、cognitive debt、securing agentic systems 等条目。
- GitHub Blog / Microsoft for Developers：Spec Kit 与 SDD 工具链介绍（2026-05）；MarkTechPost Spec-Kit 综述（2026-05）。
- AI Advances（gopubby）："AGENTS.md vs ADR"对照（2026）；DeepWiki rjmurillo/ai-agents Architect Agent & ADR System（2026）；Inngest 多 agent 持久编排 ADR-0005（2026）。
- State of AI Coding Efficiency 2026（2026-04）、Larridin Developer Productivity Benchmarks（2026）、getPanto AI Coding Productivity Statistics（2026）：生产力/验证开销/漏洞倍数数据。
- CloudZero / DEV Community / Nimbalyst / Shipyard：Claude Code 多 agent、subagent、worktree、token 成本实践（2026-04）。
- 本仓库一手素材：CLAUDE.md 全局时效性硬规则、commit 历史（size-budget gate、real Markdown pipeline、live invariant panel）、AIPA 长文#1（evals）。