AI编程闭环协作实践：Harness与SDD实现改动可签收可合并

2026年5月，系列《AI 编程可闭环协作》卷三 先说几句开篇。如果你还没读过本系列的卷一和卷二，建议回头翻一翻——卷一讲的是，图谱协作流程到底怎么“叠”起来；卷二的核心在于，让Agent“先看地图再动手”。这一卷，我们只聚焦一件事：过程。 说白了，就是一个任务从开工到合并，整个过程中：任务单里最少得写什么？为什么“书面审查”和“签收”这两个动作根本不能省？规格驱动（SDD）的阶段，是怎么从最初的需求澄清一步步走到最终合并的？以及，半自动协作的边界到底在哪里？ 卷二解决了“改哪里”的问题。而卷三要回答的，是“何时算做完、谁来签字、凭什么合并”。记住一句话：有地图，但没签收，照样不敢合并。 这卷还会正面回应一个行业里的老难题——用AI写代码，到底谁负责？如何证明你已经尽到了注意义务？出了问题从哪儿修？答案不是藏在更大的模型里，而是在“任务单 + 书面签收 + 合并前自动检查”这条可追责的轨迹上（详见§12.8）。 任务收尾后的经验沉淀，我们会放在卷四展开。另外，“冷/温/热”分层用语在本卷是首次引入的。本卷主要聚焦温层里的签收纪律，以及日常的默认操作（具体分层对照表，见§11.2.1）。 --- ### 11. 任务单最少写什么：验收、非范围、失败路径 #### 11.1 本节要回答什么 一轮需求开工之前，任务单里最少需要包含哪些内容，才能让人类和Agent对“什么叫做完”这件事达成一致？而不是在聊天框里各说各话，最后发现理解完全错位。 #### 11.2 Harness 是什么 所谓“Harness协作流程”，指的是用“可检索的任务单 + 书面审查 + 合并前自动检查”这套组合，把“聊过了”变成“交差了”。关键不在于多买一个工具，而在于字段设计和签收纪律的执行。 它和卷一提到的“三支柱”是这样对应的： - **告知**：任务单里体现为背景、范围、图谱入口、依赖说明。 - **约束**：体现在非范围、失败路径、测试策略。 - **验证**：体现在验收清单里，尤其是“合并前必绿”和自检命令。 #### 11.2.1 图谱入口与冷/温/热分层（本卷用语，衔接卷二） 分层用语是这一卷首次出现的。卷一、卷二已经分别讲了结构（技术图谱）和过程骨架，但正文里并没有用“冷层/温层/热层”来命名。下面这张表，是把前文的内容对应收拢起来的简称。 | 层 | 是什么 | 与已读前卷的关系 | 本卷落点 | | ---- | -------------------------- | -------------------------------------------------- | ---------------------------- | | 冷层 | 不常变的结构地图 | 对应卷二的技术图谱（卷二称“地图”“子图”“图谱入口”） | 任务单里的图谱入口 | | 温层 | 协作轨迹：任务单+书面签收+关账摘要 | 卷一过程轨，本卷主体 | §11–§14 | | 热层 | 运行时事件记忆（远期，非日常必做） | 前卷未展开 | §14.8划界；完整愿景另有单独篇章 | 如果你已经读过卷二，可以把那里的“技术图谱”理解为冷层的落点：它回答的是“改哪里、从哪进、会影响谁”。任务单里“图谱入口”这一行，就是让Agent开工之前先挂到地图上，而不是在全仓库里无头苍蝇一样乱搜。 有一点必须分清楚：冷层只管结构，不管“上次为什么定了这个阈值”——那是温层里关账摘要的事（§13.7、卷四）。这两个层次如果混在一起，就会出现有地图没签收，照样不敢合并的情况。 #### 11.3 与卷一的关系 卷一§3用“意图/成果/验收”来描述一轮交付；卷一§6给出了最小起步示例。而卷三，是把这三个要素落实到可执行的字段上： - **意图** -> 任务单里的背景与目标、非范围 - **成果** -> 范围清单、图谱入口（建议，参考卷二§8.3） - **验收** -> 可勾选清单、测试策略、合并前自动检查 #### 11.4 最少字段表 任务单开工之前，至少建议写清楚下面这几项（具体名称可以根据团队习惯调整）： - **验收清单**：可勾选的完成条件。例如：“PR上单测workflow全绿”“错误验证码返回401”。 - **非范围**：本轮明确不做的事。例如：“不改信息登录”。 - **失败路径**：出错时系统应该如何表现。例如：“库不可用 → 500 + 可重试提示”。 - **测试策略**：关键路径是否先写失败测试。 - **图谱入口（建议）**：先读哪张主图/子图。例如：“从登录子图进入”。 关于失败路径，建议用表格形式，每一行写明：**触发 → 行为（含状态码）→ 可否重试 → 用户可见类型**。还可以加一列“可测场景编号”（比如`auth-invalid-code`），让它能和单测或验收命令互相链接。缺了这一块，Agent很容易只写happy path。 #### 11.5 测试策略：写清档位，而非口号式TDD | 档位 | 含义 | 适用 | | -------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | **必须自动化** | 先写“可失败”的测试，再改实现；自检附命令与通过证明 | 鉴权、对外契约、流式背压、核心回归 | | **建议有测** | 鼓励补测；验收以命令+人工为主 | 一般功能 | | **不适用** | 写一行理由 | 纯文档、无行为变更 | 即便是一个人团队，普通功能选“建议有测”就行。但只要是鉴权、对外API这类关键点，仍然要走“必须自动化”。 整体上来讲，Harness是“SDD + 验证”，不是要求每个task都走严格的red-green。多数纯文档、无行为变更的任务，选“不适用”就行——底层的安全网仍然是合并前CI全量回归通过。只有在鉴权、对外契约等关键点上，才用“必须自动化”把行为钉住。 实际经验告诉我们，“必须自动化”只应该用在少数高风险路径上。日常更常见的情况是：把失败路径写清楚，实现时同一个PR里补上测试，CI回归通过，自检时贴上命令输出（也就是“建议有测”档）。只有纯函数、权限闸门、已知bug回归这些场景，才更值得先写失败测试再改实现。 #### 11.6 合并前必绿 验收清单里建议固定有一条跟CI对齐，比如： - 后端：`pytest`（或PR上等价的workflow）全绿 - 前端：`lint` + `test` + `build`全绿 关键是本地命令需要和PR上的workflow保持一致，避免出现“我机器上过了，流水线没过”的情况。 笔者在示例后端API项目中已经落地了这条规则：任务模板强制包含这一条，任务审核在开工前核对字段是否齐全（2026年5月，关账PR #90）。你的仓库可以从卷一§6的模板起步，先加上一行“合并前命令”。 #### 11.7 扩展示例：验证码登录（延续卷一§6） - **非范围**：不改信息登录；不调整会话TTL - **失败路径**：验证码错误 → 401；过期 → 401 + 提示刷新 - **测试策略**：必须自动化：`TestLoginWithCaptcha`等 - **验收**：单测绿 + CI绿 + 审查签收 #### 11.8 可复制任务单骨架（在卷一模板上增补） ```markdown ## 任务单：<动词+范围> ### 验收清单 - [ ] <功能验收1> - [ ] PR上单测/构建workflow全绿（本地等价：<你的命令>；尚无CI时改用手动命令，输出贴进签收记录，见§15） ### 非范围 - <明确不做的事> ### 失败路径 | 可测场景编号（可选） | 触发 | 行为 | 可重试 | 用户可见 | | --- | --- | --- | --- | --- | | auth-invalid-code | <例：验证码错误> | 401 | 否 | 提示刷新 | ### 测试策略 - 必须自动化 / 建议有测 / 不适用（理由一行） ### 图谱入口（可选） - 子图：<你的流程图文件名> ``` 常见疑问： - **和Jira/飞书工单有什么区别？** 工单管产品沟通，任务单管工程交付。两者叠加使用，不互相替代。 - **一人团队也要写吗？** 可以短一些，但“验收+非范围+失败路径”这三项不能省——否则你没法核对Agent是不是越界了。 - **是不是每个task都要TDD？** 不是。写清测试策略档位，加上合并前CI回归作为底网。只有鉴权、对外契约等关键点才用“必须自动化”，先写失败测例再改实现。 --- ### 12. 审查与签收：书面记录为什么不可省 #### 12.1 本节要回答什么 为什么“聊过了”“LGTM”不等于可以合并？这是很多团队容易忽略的。 #### 12.2 反模式 - **口头Review**：换个人、换个模型之后，就完全不可检索了。 - **聊天里“过了”**：没有对照验收条的证据，对不上号。 - **无记录合并**：出了事，没办法回答“谁批准的、依据是什么”。 #### 12.3 两类书面记录 | 记录类型 | 何时 | 产出 | | ------------ | ------------ | ---------------------------------- | | **任务审核** | 实现开始前 | 范围与字段是否齐全；缺项阻塞开工 | | **审查签收** | 自检后、合并前 | 对照diff、CI、任务单的“结束本轮”结论 | 这两类记录不替代Code Review看diff，而是把结论“落盘”。Agent不能代替你做终局签收，合并主干这件事必须由人来拍板。 #### 12.4 任务审核审什么（清单思路） 实现开始前，审核人建议逐项核对（可以写进半页审查记录）： - 验收清单是否“可观测”（能勾选、能跑命令） - 非范围是否非空 - 失败路径是否至少有一行、可操作 - 测试策略是否与变更风险匹配——**改对外API、路由或鉴权时，不得选“不适用”**（至少“建议有测”，高敏用“必须自动化”） - 是否包含“合并前必绿”条 缺项就阻塞，回到任务单补全后再审。即便是零阻塞，也要写记录：写明已核对哪些项、可以进入实现。 #### 12.5 高敏变更：建议“独立复检” 改动涉及对外API、流式协议、鉴权时，除了审查签收之外，建议再做一次“独立复检”。具体做法是：只看diff摘要、自检输出、验收表，逐项判定pass或fail。最好是新开一个对话来做，或者在同一对话里切换角色说明，但只贴三件套（见§14.5）。精神上来说，这和“审查者与实现者分开”的原则是一致的——不需要上一套封闭循环编排器，纪律写在任务单里就行。 #### 12.6 谁来做 - **个人项目**：交给“未来的你”（隔天冷读）或者同伴。 - **团队**：指定Reviewer。 #### 12.7 与Code Review的关系 Review看的是代码质量。而协作流程额外要求的是：对照任务单+CI+留签收。卷一§4的分工没有变，本卷强调的是“结论可检索”。 #### 12.8 更深一层：谁负责、如何负责、如何修复 用AI辅助研发之后，合并变快了，复盘却常常变难。很多团队卡在下面三个问题上： | 难题 | 核心问题 | 没有结构时会怎样 | | ------------ | ---------------------------------- | ---------------------------------------------------------- | | **谁负责** | 这行代码、这条决策算谁的？ | 只有聊天记录；Git作者是Agent；说不清谁批准 | | **如何负责** | 凭什么说“该做的都做了”？ | 说不清验收口径、测没测、有没有越界 | | **如何修复** | CI或线上红了，从哪切入？ | 不知道动过哪些模块、当时为什么那样改 | 这三件事，本质上是“归因→尽职→修复路径”。光靠模型变强解决不了，需要“外置、可读、可核对”的轨迹——笔者称之为“白盒轨迹”。也就是说，交付过程和依据应该尽量完全可读、可核对，不依赖模型内部状态。模型某一步怎么想的，可能仍然说不清，但“谁批准的、按什么规格的、测了什么”，这些必须留在白盒里。  | 三问 | 本卷+卷二怎么补 | | ------------ | ------------------------------------------------------------ | | **谁负责** | **人**在审查签收上拍板；Agent是工具，不是责任主体 | | **如何负责** | 任务单字段齐全 + 任务审核记录 + 合并前必绿 | | **如何修复** | **卷二结构地图**（本卷称冷层）定位模块与影响面；**温层**查上次关账摘要；**Git**看diff；**CI**看哪条测试红 | #### 12.9 可追责包：交付物不止是PR 理想情况下，一轮交付除了PR/代码/测试结果，还应该能“一键追到依据”： | 依据项 | 是什么 | | ---------- | -------------------------------------------- | | 任务单 | 验收、非范围、失败路径 | | 书面审查 | 开工前审核 + 合并前签收 | | 结构地图 | 本轮改动的入口与影响面（卷二技术图谱；本卷分层里称冷层） | | 版本记录 | 提交历史与合并记录 | | 机器验收 | CI/单测日志 |  卷二给结构地图，卷三给签字依据——两者叠在一起，才谈得上“敢用AI规模化改代码”。验收口径在任务单（温层），结构地图见卷二（本卷分层里称冷层）。热层（运行时事件网）面向长跑与在线系统，对于团队内部AI编程的现阶段，通常不必做（§14.8）。 常见疑问： - **Agent写的代码，出现事故谁负责谁解决？** 算签收合并的人与组织。Agent只是执行工具。所以书面签收不可省，也绝不是形式主义。 - **可追责包能消除模型黑盒吗？** 不能逐token解释模型，但能证明“按什么规格、谁批准、测了什么”——这在工程与合规上，通常才是“负责”的主战场。 --- ### 13. SDD 阶段流：从需求澄清到合并 #### 13.1 本节要回答什么 卷一§2.2提到的“阶段骨架”，如何变成一条可执行的流水线？ #### 13.2 阶段图  #### 13.3 阶段表 | 阶段 | 主要谁 | 产出 | 图谱/CI | | ------------ | ---------------- | ---------------- | --------------------------- | | 需求澄清 | 人 + Agent辅助 | 任务单初稿 | 可选：主图/子图入口 | | **任务审核** | 人 | 书面审核结论 | 核对§11字段 | | 实现 | 人 + Agent | 代码、文档 | 按§11.5：必须自动化时先有可失败测例再改实现；建议有测时同PR补测 | | 自检 | 执行者 | 命令输出+验收摘要 | 本地或CI预跑 | | 合并前CI | 机器 | workflow全绿 | 单测、lint、图谱门禁等 | | 审查签收 | 人 | 签收记录 | CI绿+任务单勾选 | | 合并 | 人 | 进主干 | — | | （可选）冷静复检 | 独立视角 | 隔日复核 | 高敏建议 | #### 13.4 SDD 一句 规格驱动的核心逻辑是：先写清验收与边界（任务单±SPEC），再让Agent去改实现。代码，是规格的可执行表达。 #### 13.5 机器与人 - **CI/单测**：管的是“行为不漂移”。 - **图谱门禁（若有）**：管的是流程图、入口清单与代码大致一致（卷二§9.5）。 - **人**：管的是“敢不敢合”。 CI通过了，仍然需要人来看范围和风险。 #### 13.6 与卷一阶段骨架的对照 卷一给出的文字版流程是： ``` 需求澄清 → 任务审核 → 实现 → 自检 → [CI全绿?] →（否，回实现）→ 审查签收 → 合并 ``` 本卷增补了两点：任务审核可以阻塞实现；独立复检为可选加强，但不替代签收。 #### 13.7 关账后与“温层”（指针） 任务归档/关账时留下的“任务单终稿、审查记录、关账摘要”，在分层愿景里属于温层——协作轨迹。它记的是“这次为什么这样改、谁签收”，不需要重画整张结构地图（结构地图属于冷层，也就是卷二的技术图谱；只有在模块连线真的变了的时候，才需要更新，具体见卷二）。  卷四会展开说明，如何把关账摘要蒸馏成“经验卡片/编译摘要”，让下一轮少翻全文——但它仍然不替代卷二地图回答“改哪里”。热层属于远期场景，本卷不展开。 --- ### 14. 半自动协作：何时链式、何时必须人工闸 #### 14.1 本节要回答什么 Agent能不能在一条对话里连续完成写任务、改代码、跑自检？什么时候必须停下来等人？ #### 14.2 半自动 ≠ 全自动 | 可以链式 | 仍须人做 | | ---------------------------------------- | ------------------------------ | | 小改动：实现 → 自检 → 整理审核材料 | **任务审核** 终局 | | 工具内切换“角色说明” | **审查签收** | | 自动跑测试、贴日志 | **合并主干** | 参考Ralph Loop一类的全自动编排系统，它们走的是“四步封闭循环”（规划→实现→审查→结束），机器可以连续跑完一轮。笔者这边选型的思路是“签收型流程”：省掉重复填表的功夫，但不省掉人的签收与合并责任。 #### 14.3 人工闸 任务单可以用“待批准/已批准”标签来标记关键决策。Agent在“待批准”状态时，应该停下来，不要进入实现。 | 闸（示例名） | 典型阻塞 | 谁改“已批准” | | ------------ | ------------------ | ---------------------------- | | 初稿任务单 | 任务审核、实现 | 负责人（**默认人**） | | 审核后 | 实现 | 读过审核记录的人（默认人） | | 复检后（可选） | 关账、合并 | Tech Lead | | 发布前（可选） | 合入主干 | 维护者 | 默认由人来把“待批准”改为“已批准”——未显式授权的Agent不得代填。初期建议坚持这个原则：人工闸还没走顺的时候，不要让实现Agent自行批准。 进阶玩法是：在OpenClaw等带“总调度权限”的模式里，理论上可以给某个Agent“书面授权”，让它代填“已批准”（但必须可审计：谁授权的、什么时候、依据哪份审核记录）。闸走顺之后，加上有权限的签收袋里通常很快；阶段顺序和任务单字段不变。笔者目前还没有在自己流程里完整落地这一层，不过整条SDD流水线不必因此改写。 §13阶段图里的“人”，文中均指“默认执行者”；如果用了已授权、留痕的签收袋里，仍然需要满足上面说的授权与审计要求。 常见疑问： - **以后能让总调度Agent代点“已批准”吗？** 可以作为进阶，但必须显式授权并留痕。默认仍然建议由人来点。流程不变，变的是“谁被授权点这一下”。 #### 14.4 何时开链式、何时关 - **小bug、文档、单文件**：可以半自动，但仍然需要终轮签收。 - **跨模块、契约、架构**：强制人工闸，需要多轮任务审核。 半自动省的是复制模板的功夫，但它不保证模型不会越界——纪律来自任务单和书面记录。 #### 14.5 换上下文（Fresh Context）纪律 任务审核、独立复检时，输入只保留：任务单、审查记录摘要、diff要点、自检输出。不要把整段实现过程长文贴进去。 交给审核或复检的“三件套”是：改了什么、跑了什么命令、验收表结论。这和“审查者不与实现者共用记忆”是同一个精神。 最稳的做法是新开一个对话。如果在同一对话里切换角色说明也可以：阶段之间切换“写任务单/审核/实现/自检/独立复检”等提示词，但到了审核或复检环节，只贴三件套，不贴实现长文——这就在单窗口里做到了逻辑上的Fresh Context（与§14.7的默认路径一致）。 一个极简示例：粘贴“任务单全文 + `git diff --stat`（或diff摘要） + 自检命令输出”这三件套，就可以开始审核或复检了。 #### 14.6 与Cursor / Claude Code的关系 工具可以连续对话，但流程来自任务单与签收习惯。换工具的时候，“意图/成果/验收”这些字段应该是可迁移的（卷一§0）。 #### 14.7 默认纪律：一个任务、一个对话、一个PR 在“任务单+地图+书面签收”的架构下，笔者推荐的默认路径是： ``` 一个进行中的任务 → 一个Agent对话窗口 → 一条审查与关账链 → 一个PR ``` 同一个对话可以串完整条链：从任务单到任务审核，到实现，到自检，到审查签收，再到（高敏可选）独立复检，最后归档。不需要为了每个阶段另开Agent或另开窗口——阶段之间“换帽/换角色说明”就行（§14.5）。独立复检可以在同一个窗口完成，前提是只审diff/日志/验收表，不共用实现过程的记忆；如果高敏或上下文对不齐，再另开对话。  - **同一个任务开多个对话分工？** 尽量避免——上下文会分裂，导致关账与可追责包对不齐。 - **两个无关任务同时要交？** 可以开两个对话，但必须用独立的Git分支与工作目录，不要共用同一份checkout。 - **多Agent自动派活长跑？** 这是远期场景，和本节的“一任务一PR”并不矛盾——那是编排器拆成多个任务。 这和“用AI盯同事谁改了哪个文件”没有关系：谁改了哪行，看Git；是否符合任务范围，看任务单与审查；改A会影响到谁，看卷二地图。 #### 14.8 现阶段：冷+温已够支撑研发 如果你的场景是“团队内部用AI协作写代码”，并且还没有大量真实用户流量，那么“卷二结构地图（本卷称冷层）+ 本卷签收与任务单（温层）+ Git/CI”这套组合通常已经够了。不必为了协作专门去上“运行时事件记忆”。  --- ### 15. 存量 / 无 CI：阶段流降级 #### 15.1 本节要回答什么 老项目，或者还没有CI的项目，如何在不降低质量的前提下“缩水”使用这套流程？ #### 15.2 与卷一§5衔接 先补“手动门禁”（把命令写进任务单），再逐步把CI搭起来。 #### 15.3 降级对照 | 有CI | 无CI降级 | | ------------------------------ | ------------------------------------------------------------ | | PR上pytest/lint全绿 | 合并前在**本地**跑同一命令，把输出要点贴进签收记录 | | 图谱check workflow | 合并前**手动**export/check（命令写进任务单） | | 任务审核书面记录 | **不可省**；模板可以缩短 | | 独立复检 | 一人团队：合并后通过issue/日记自检 | #### 15.4 与产品工单叠加 任务单是“工程交付”的真值，工单是“产品沟通”。建议先一轮手动闭环，再补CI。 #### 15.5 领域结构检查（进阶） 除了通用的单测和图谱契约门禁，还可以为“高频错误响应、流式事件名”等增加小脚本结构检查，和pytest并列放进CI。思路类似于“报告结构Linter”——专门检查最容易出现结构偏差的JSON/API形状，具体领域按你自己的业务来定。 笔者在示例后端API项目中已经落地了第一条：**结构化错误响应**的必填字段，由注册表+脚本校验（理论对齐P1，PR #92），关账复检PR #93。你的仓库可以从“一种最容易出现结构偏差的JSON形状”起步，不需要一次做全。 --- ### 16. 结语  卷二给了结构地图（本卷分层里称冷层），卷三给了签收纪律（温层）。两者叠在一起，才能在Auto模型、预算有限的日常里，做到稳定合并。 AI编程要规模化，关键不只是让模型多写几行代码，而是让每一次交付都能回答这几个问题：谁签的、依据什么、影响多大、怎么回滚（§12.8）。先建好白盒轨迹的地基，再谈把更多执行交给AI——顺序如果反了，只会更快地产出“不敢合并、也不敢背锅”的改动。 下一卷卷四，我们会展示一整轮专题从SPEC到归档的完整例子，以及关账后温层摘要如何压缩成经验卡片（仍然不替代图谱与任务单）。冷/温/热完整愿景见独立篇（可选读，发表版链接待补）。