Agent 工件契约：13 阶段生命周期的类型系统设计

系列：Idea-to-Production · 机理篇 同系列：《人不在环内：一个 AI 自主交付组织的概念契约》（概念背景）、《九个角色如何分掉一家公司》（组织图）、《无人值守调度的三件机件》（调度机件）

让九个 Agent 协作，最难的不是让它们干活，而是让它们交接。架构 Agent 写了一份方案，实现 Agent 只读了前三段，QA Agent 压根不知道有这份文档——如果你见过两个 Agent 互相”参考”对方输出的系统，这样的灾难大概率不陌生。本文给出的解法是把交接形式化：具名工件 + 显式依赖 + 两棒派发。本质上，这是在给 Agent 之间的协作写一套”类型系统”；模式与任何具体产品无关，可以直接搬进你自己的 Agent 管线。

你将从本文带走三点方法论：把阶段定义在工件上，而不是活动上（”做设计”无法验收，”tech_design.md 已产出并被下游消费”可以）；依赖图在认领时强制，不在执行后补救（前置未 Done 的任务对执行者根本不可见）；一份超长工作流要切成”每阶段一个文件”（加载单位决定上下文质量）。

骨架：13 个阶段 + 3 行派发 = 16 行

完整生命周期是 A–M 十三个阶段，加上两棒派发与发布前检查共 16 行编排。先记住主干的工件链：

idea ──► requirement.md ──┬─► solution.md ─► core_module_design.md
                          │        │
                          ├─► ui_design.md ─┐
                          │                 ▼
                          │            tech_design.md ─► ta_solution.md ─► ta_plan.md
                          │                 │                  │
                          └─► 仓库骨架 ─────┴──► plan.md ◄─────┘
                                                    ▼
                                        代码 + 单元/集成测试
                                                    ▼
                                     E2E 用例与报告 ──► 发布 ──► 报告回流

四个结构性决定

• B（架构）与 C（UI 设计）刻意并行：两者都只消费 requirement.md，互不等待；D（详细设计）才把两条线合流。
• 测试策略在实现规划之前（E→F），而不是之后：实现计划必须把 E2E 门禁的约定编进去，否则”先写完再想办法测”会系统性漏掉可测试性。
• D 与 F 同属全栈角色但绝不合并：一个产出 tech_design.md（接口契约、DDL、状态机），一个产出 plan.md（按特性的 2–4 小时任务粒度）。设计是”是什么”，计划是”怎么排”——两种认知产物混在一起，QA 和实现者会各自挑自己爱看的那半。
• H（仓库脚手架）依赖 B 而非 F：目录结构与 API 骨架从方案与模块契约里长出来，脚手架完成后才允许 F 开工——计划必须落在真实存在的仓库上。

机制一：依赖在认领时刻强制

任务图上每条边都是 Depends On，而强制点在认领锁的那一刻（《无人值守调度的三件机件》中的 P3 规则）：所有前置任务不全部 Done，这条任务就不可认领——引擎直接跳过它，执行者连看都看不到。

这个设计把”半成品开工”从流程问题降级成了不可能事件。对照一下反面模式：很多人类团队用”状态=进行中但先等着”来表达阻塞，于是看板上堆满僵尸卡片；在机器执行的依赖图里，阻塞的正确表达是根本不可派发。

机制二：两棒派发切在工件边界

人类只写阶段 A 那一条任务。之后 PM 角色跑两棒：

• 第一棒（requirement.md 产出后）：派发 B/C/D/E/F/H 设计线；
• 第二棒（plan.md 与仓库骨架就绪后）：按特性派发 I 实现任务、按 ta_plan.md 逐特性派发 J E2E 任务（每条 Depends On 对应特性的 I 任务），最后挂 K 发布任务。

为什么不能一棒打完？实现任务在 plan.md 存在之前无法有意义地撰写——而 plan.md 依赖整条设计线完成。切在工件边界上，保证每条任务出生即自足：领取它的人所需的全部上下文，都在它消费的文件里。

J 的妙处在于：任务定义在 E 阶段就写好了（只依赖 ta_plan.md），但执行被依赖门控推到对应特性的代码完成之后——E2E 永远针对真实 UI 编写，从不等整个应用构建完。

机制三：文档先行，漂移即 bug

生命周期里所有”合同”都是文档工件，因此阶段间的推进规则直接继承了方法论层的纪律：文档先于兑现它的实现而变化；文档与代码不一致，按 bug 处理（详见《文档即可执行资产：当 Agent 逐字消费你的规格》）。每个阶段还有自己的工作流文件（stage-x.md），Agent 认领后只加载”自己这一跳”——十三个阶段一份百科全书，不如十三份单页作业指导书。

两道关卡：让链条无人值守仍可信

• 逐交付物评审检查点：任何任务的 Done 必须以子代理评审 PASS 记录为前提；失败走”诊断 → 有限重试 → 新建升级任务”，绝不”等人来看”。
• 集成面发布门（I→J 转移）：所有 I 任务完成后，对聚合差异做一次聚焦评审——跨任务接口、共享模块、依赖与配置变更、安全敏感路径（不逐行重审任务内部代码）。BLOCK 判定直接阻断转移，发现项回流实现。这是实现通往测试与生产的唯一闸口。

测试职责也随之切清：全栈角色拥有单元+集成测试（E2E 仅本地辅助），QA 角色只跑真端到端——站在最终用户视角、对着真实 UI、模拟生产环境。两边都清楚自己不该跑什么，质量信号才不会被重复与真空同时填满。

总结

1. 给 Agent 管线设计交接，等于设计一套类型系统：具名工件是类型，Depends On 是编译期检查，认领门控是运行时强制——三件齐备，”它没看那份文档”这类故障就从事故变成了类型错误。
2. 把派发切在工件边界上（需求产出后一棒、计划产出后二棒），每条任务出生即自足，这是”人类只写一条任务”在机制上成立的原因。
3. 现在就可以做的最小一步：给你的下一阶段交接起一个文件名，把下游的开工条件写成”该文件存在且被评审通过”——一个工件契约就是一个阶段的起点。

本文是 Idea-to-Production 系列的机理篇；概念背景见《人不在环内：一个 AI 自主交付组织的概念契约》，组织图见《九个角色如何分掉一家公司》，调度机件见《无人值守调度的三件机件》。