AI编程交付不达标源于结构轨与过程轨缺失:技术图谱明确系统入口与影响面,过程轨通过任务单、签收和合并前检查规范协作。基于SDD三支柱(Inform、Constrain、Verify)与Epic三要素(意图、成果、验收),实现可迁移的工程闭环,确保交付可对齐、可追溯。
AI编程闭环协作:从更会写到敢合并
时间:2026-06-03
浏览:442
文章目录
先说一个核心判断:当前很多团队使用AI编写代码,交付质量不达标,根本原因往往并非模型不够聪明,而是两个关键环节没有落实到位——一是“改哪里、会波及谁”说不清楚;二是“什么时候算完成、凭什么合并”缺乏明确标准。
我们这套方法论围绕两条主线构建。一条称为结构轨,描绘系统结构、接入入口、改动影响范围,核心载体是技术图谱;另一条称为过程轨,管理协作方式、人工审查节点、以及交付是否可合并。两条轨道正交叠放,各司其职。
后续将详细展开。先记住几个关键词:SDD(规格驱动开发),ICV三支柱(Inform · Constrain · Verify),以及 Epic(有边界的一包交付)。我们不发明新概念,只是将这套思路落到工程协作实处。Harness则可理解为实践SDD的一组工具和纪律。
整个系列共五卷,本篇为总览,为你提供一张可迁移的原则地图。
1. 问题陈述:失败常不在模型
你一定经历过这种场景:自然语言描述需求 → Agent修改文件 → 人工查看diff → 合并。操作看似顺畅,但问题接踵而至。
- 修改A遗漏B,联调时才爆发:因为Agent不了解系统结构,不清楚依赖关系。
- 同一需求反复交流:缺少可复用的规格与任务依据,每次都要重新开始。
- PR能合并,但心里没底:缺乏书面的签收标准和自动化的验收门禁,全凭感觉。
- 对话越来越长,账单越来越高:将整仓或整段文档直接灌给模型,效率低下。
这些问题和“会不会写代码”有关,但远不止于此。单靠优化Prompt或事后提炼Skill无法解决根本。Skill记住的多是习惯和教训,如果一次任务中既没有技术图谱指路,也没有验收门禁把关,该遗漏的还是会遗漏,该不敢合并的仍不敢合并。
关键在于,这套方法的逻辑与模型能力是解耦的。同一份任务单、同一张技术子图、同一套合并前检查,换用不同档次的模型执行,交付口径仍可对齐。工具会变,但意图、成果、验收这三件事不应随模型脾气而漂移。
2. 双主轴:过程轨与结构轨
为什么需要两条轨道?因为它们回答不同的问题。可以将整个协作想象成工地上的一辆运输车。技术图谱就是带方向的路网图,清楚标明从哪扇门进入、连接哪些工区。Agent被分派任务时,只看到自己所需的一小块局部地图,而非整座城市全貌。关卡(即过程轨上的验证点)则负责检查:是否通过?是否签收?检查通过才能上主干道。
经验卡片或Skill好比路口的警示牌,提示前方常有施工。但它们不能替代地图本身,也无法替代关卡。你的目的地永远在图上的某个入口节点,而不是在牌子上。
2.1 各答一问
| 轨道 | 回答的问题 | 典型载体 |
|---|---|---|
| 过程轨 | 怎么协作?何时需要人工审查?这趟活儿到底能不能合并? | 任务单、审查记录、合并前检查全绿 |
| 结构轨 | 系统长什么样?从哪儿进入?影响面在哪儿? | 技术图谱(主图、子图、契约/入口清单、图谱CI) |
这里需要特别说明表格中的“图谱CI”,它指的是结构文档与代码一致性的自动检查,比如检查入口清单、契约锚点等,而不是用来替代业务测试的流水线。
两条轨道是正交的。这意味着在同一个Epic里,可以既有“图谱入口:从登录子图进入”,又有“验收条件:单测、lint全绿、Tech Lead书面签字”。指标不能混用,不能因为对话写满了就认为任务完成。
2.2 只炼技能或只上CI,各缺什么
现实中,许多团队的方向有些偏颇。对照下表,看你们在哪个象限。
| 做法 | 补上了什么 | 仍然容易缺什么 |
|---|---|---|
| 只做Skill/Rules | 个人或团队的提问与编码习惯 | 改哪里、影响谁;当次任务的书面验收 |
| 只做CI/DevOps | 合并前的机器背压 | Agent开工前挂错了入口;任务中的非范围和失败路径没写清楚 |
| 只写Wiki/产品文档 | 业务规则与背景 | 与代码同步的工程入口和契约;签收纪律 |
因此,这套方法主张:结构层面的内容进图谱;过程层面的内容按SDD三支柱落实。合并完成后,才考虑将习惯和决策蒸馏成Skill或跨轮回顾摘要。
3. SDD三支柱:Inform · Constrain · Verify
先说明一下,规格驱动开发(SDD) 是整个方法论中的上层思想。它强调先定规格,再写代码。而我们经常提到的 Harness 协作流程,是将SDD落地到AI协作中的一种具体工程路径。
SDD语境下通过三个支柱组织协作:Inform(告知)、Constrain(约束)、Verify(验证)。它们分别回答:开工前对Agent的告知是否充分?执行中有无可供核对的约束?合并前的验证步骤能否重复?
这套方法论不发明第四个支柱。我们所说的双轨,只是将SDD三支柱落实到两类工程落点上。
SDD(规格驱动 · 上层方法论)
└── ICV 三支柱(Inform / Constrain / Verify)
├── 结构轨 · 技术图谱
└── 过程轨 · 任务单、签收、合并前检查
(过程轨常通过Harness协作流程等工具来落实)
图1 · SDD、ICV、双轨与Harness的归属

| 支柱(SDD / ICV) | 含义(读者向) | 过程轨落点 | 结构轨(图谱)落点 |
|---|---|---|---|
| Inform | 开工前说清楚要读什么、范围在哪里、依据是什么 | 任务单:背景、非范围、依赖说明 | 图谱入口;查询子图,而非整仓灌文档 |
| Constrain | 边界和失败行为可以规则化 | 失败路径、测试策略、拒绝开工的清单 | 契约/入口清单;图谱与代码门牌号一致 |
| Verify | 合并前可以重复验证,出了问题可追溯责任 | 合并前检查全绿、书面签收落盘 | export/入口/叙述层CI;读法对照带上题集边界 |
3.1 易混:SDD与Harness Engineering
这是新手最容易混淆的地方。SDD和Harness Engineering是协同关系,但不是同一回事。用下表理清:
| 维度 | SDD(规格驱动开发) | Harness Engineering(驾驭工程) |
|---|---|---|
| 起源 | 传统软件工程;用契约与规格管理复杂性 | 近年围绕LLM的外部工程化讨论(如业界Mitchell Hashimoto提出的概念) |
| 核心 | 先写清Spec,再实现,保证实现与规格对齐 | 围绕LLM建外部工程系统,引导、约束、验证AI,把不稳定产出变成可合并交付 |
| 典型口号 | 先想后做,规格即契约 | 模型能力趋同时,工程系统(Harness)决定能否稳定交付 |
| 与本套方法的关系 | Epic三要素、任务单、验收的方法论父层;ICV三支柱归属此处 | 协作流程、CI、书面签收等实践层之一 |
| 关系 | 定义了“要交付什么,如何验收” | 是实践SDD的工具之一;可与SDD并行叠加,而非替代 |
为什么容易混?原因有三:一是SDD本身讨论时也会出现“约束”、“验证”等词,但它们通常指规格本身应具备的特征,而非Harness里的工程组件名。二是Harness是实践SDD的路径之一,尤其是将Verify落到CI和签收上,但它不是ICV的定义来源。三是Harness Engineering更像一个独立的工程话语体系,可与多种开发流程结合。
一个类比帮你秒懂:SDD ≈ 合同 + 验收标准;Harness ≈ 工地上的闸机、巡检、签字本。前者定交付和如何验收,后者把纪律落到协作现场。
特别提一下,对于做评测和Mentor的团队,Verify可以再加厚一层。你们关心的是验收证据——验收项能否被测试或检查证伪?协作过程是否留下可复盘轨迹?谁、在什么时间、基于什么材料做了签收?这与单纯堆对话日志完全是两码事。日志中如果没有对齐“意图/成果/验收”,很难还原当初“什么叫做完”。
过程轨要求:开工前有任务依据;合并前有检查结论;关键节点有书面记录,并且可检索,而不仅仅在聊天窗口里。合并率、单次token账单,或“感觉差不多”的说法,都不能当作Epic收尾的标准。
关于粒度,对于Mentor角色来说:你用一套题集或作业做评测时,每一题都应有可测的意图和可验收的成果;一个Epic在工程上是一包有边界的交付,必须填写验收条件,里面可能包含多个PR;而单次工单是Epic内的实现单元,继承Epic的验收标准,可再加局部检查清单。
4. Epic:意图 · 成果 · 验收
我们说的Epic,是指有边界的一包工程交付。再小的单次改动,也建议具备三要素。哪怕这三个要素写在同一张任务单里,也比没有强。
| 要素 | 是什么 | 缺了会怎样 |
|---|---|---|
| 意图 | 要达成什么?明确不做什么? | Agent与人都容易范围漂移 |
| 成果 | 可合并的代码、配置、文档、规则变更 | “聊过了”,但无可合并物 |
| 验收 | 测试/检查通过、审查签收、关键结论可追溯 | 不敢合,或者合了无法复盘 |
任务单是Epic内更小工单的常见载体。验收环节绝不能省。任务单+签收,就是我们所说的“本轮交付依据”——这是本轮唯一可信的“做完”依据,以书面记录和检查为准,而不是聊天窗口里的口头结论。
专题收尾(合并后的归档、可选摘要编译)属于合并之后的纪律,合完不代表能自动生成什么跨轮回顾摘要。
图2 · 一轮Epic的简化交付链

4.1 迷你题集示例
下面举一个泛化的虚构例子,展示“题集/作业”应如何写清楚三要素。这是个可迁移的写法,不是某个仓库的真题,不能整包照抄。
题目:为公开HTTP API增加基于IP的速率限制
| 要素 | 内容 |
|---|---|
| 意图 | 降低滥用风险;对内部批处理通道不适用限流;非范围:不改鉴权模型、不改计费 |
| 成果 | 限流中间件 + 可配置的阈值;统一错误响应形状;更新对外接口说明 |
| 验收 | 超限时返回约定的状态码;单测覆盖边界情况与过期配置;配置缺失时默认使用默认值并记录告警;合并前检查全绿;审查后书面签收 |
评测的读者可以对照这个例子,检查你们的题面是否可测,预期结果是否可验收,失败路径是否可记录——而不是只停留在“模型改得像样”这个层面。
5. 记忆轨与Skill的边界
Skill、编辑器Rules、经验卡片,在我们这个框架中属于习惯层或Constrain的延伸。它们的作用是减少重复性Prompt输入,统一命名和测试顺序。但它们不能替代以下两样东西:
- 结构轨:改架构时依然得改图谱,在提PR时顺手维护,不能只靠加Skill。
- 过程轨:合并前检查和书面签收一步都不能省。在平台上点一个“Approve”和我们定义的“交付”完全是两回事。
跨轮回顾摘要是从已收尾的材料里编译出来的Epic级决策页。它的作用是让半年后的你少翻冗长的留痕记录。但它不是产品Wiki全文,也不能替代图谱做影响分析。
最后提一句,文章里提到的“冷、温、热”,指的是协作记忆分层(结构地图、协作轨迹、远期运行时记忆),不是软件架构里的三层,不要混淆。
6. L3 → L2 → L1:什么能抄、什么不能
最常被问到的问题:“你们仓库的内容能直接复制过去吗?”答案是:原则可以抄,数字不能抄。
| 层级 | 是什么 | 能否迁移 |
|---|---|---|
| L3 原则 | SDD三支柱(ICV)、双轨叠放、Epic三要素、验收纪律 | 可讲可教到其他项目。SDD/ICV可迁移,但Harness的具体落盘和仓库路径、实验数字不能整包抄。 |
| L2 做法 | 任务单字段名、合并前命令集合、图谱目录习惯 | 需要按技术栈改写。前端、后端、单体应用各不相同。 |
| L1 实例 | 某个仓库的路径、某次对照实验的数字、gold题集的命中率 | 不可整包外推到全行业或其他仓库。 |
这些原则(L3)是个人对多个项目实践后的归纳。此前所在的团队并没有形成与本文等价的完整体系。因此,本文是一套可迁移的通用工程协作框架,不是某个公司内部制度说明。
7. 与TDD、Code Review、DevOps的关系
这套方法和现有实践是叠加关系,不是替换关系。
- TDD / 单测:它们仍然负责“行为对不对”。本方法论负责的是:这次改动有没有测试策略?失败路径有没有写?敢不敢合并?契约检查通过了,不代表行为逻辑就对了。门牌号对了,但屋里逻辑还要靠测试来保。
- Code Review:过程轨里的Verify和Inform,将“聊”变成了可检索的审查记录。图谱则能让Reviewer更快看清影响面。
- CI/CD:这是Verify的硬背压。Agent自己的自检不能替代正式的流水线。
- Jira / 飞书工单:它们是产品沟通层的工具。任务单则是工程交付的依据。这两者应该叠加使用,不要在流程上搞出第三套互相冲突的东西。
如果你连TDD或CI都没有,那就先补上“能验得动”这个基础——哪怕先弄个手动门禁写在任务单里也行。先把这事解决,再谈Agent规模化。
8. 阅读地图:五卷各答什么
读完全文,你可以根据自己当下的处境,选择从哪个卷开始。
| 读者处境 | 建议路径 |
|---|---|
| Mentor / 评测 / 教模型写代码 | 阅读本文全文 → 卷三 Harness(关于Verify) → 卷四 专题收尾与摘要。当你需要题集和轨迹细节时再下钻。 |
| 新项目 / 个人实验 | 本文 → 卷一 §6 最小起步 → 卷二 图谱。如果只需要原则,读完本文就可以停了;要动手,优先看卷一模板。 |
| 存量 / 老项目 | 本文 → 卷五 渐进路线 · 卷三(无CI降级版)。先别急着看卷二物化细节,先把“验得动”搞定,再铺图。 |
| 只想让Agent读架构 | 本文 §2~§3 → 卷二 技术图谱。可以跳过Harness细则,但仍建议了解§4的验收概念。 |
| 只想敢合并 | 本文 §3~§4 → 卷三 → 卷四 §17 摘要。可以跳过图谱实验数字;契约红了再看卷四的失败分支。 |
各卷的副标题和核心产出:
| 卷 | 副标题 | 你得到什么 |
|---|---|---|
| 卷一 | 怎样才算“做完” | 动机、双轨总览、最小起步 |
| 卷二 | 技术图谱 | 子图、读法对照、图谱CI |
| 卷三 | Harness与SDD | 实践SDD的Harness协作流程(任务单、签收、阶段流) |
| 卷四 | 闭环交付与经验沉淀 | 专题流水线、跨轮回顾摘要 |
| 卷五 | 存量怎么落地 | 案例机制、FAQ、阶段0~3、诚实边界 |
9. 诚实边界:本系列不承诺什么
所有方法论都有自己的试金石。为避免被不切实际地使用,我们把不能外推的边界说清楚。
| 请勿外推为… | 实际范围 |
|---|---|
| 有图谱就不会有幻觉/零Bug | 只能降低漏改和漂范围的风险;仍然需要单测、失败路径和签收 |
| 全自动无人值守交付 | 是有闸的协作;关键节点仍需人工审查 |
| 任意仓库、任意语言零配置 | 必须自建题集和试点链;存量需要渐进(阶段0~3) |
| 对照实验的降幅可以代表全行业 | 必须在声明的题集、单仓、场景内解读 |
| 维护图谱可以忽略不计 | 作者在小样本中将图谱维护时间控制在开发时间的约10%~15%的目标区间——这是非行业标准、非KPI、非承诺;如果维护成本过高,应减项或加强自动化 |
| 增量图谱CI已经成熟可以照搬 | 现阶段强调全量的export/入口与叙述层检查;增量图谱CI尚未承诺 |
最后再强调一次:这个方法论不绑定任何一个品牌Agent,也没有将OpenSpec或特定编排工具写进去。能力等价物是任务单 + 测试/lint + 契约或入口检查。
10. 结语
如果你只想花15分钟建立全局认知,读完本文就够了。你现在知道了SDD和ICV三支柱是什么,Harness在其中的位置,双轨如何叠放,Epic三要素,以及五卷的分工。
如果要动手干活:新读者从卷一最小起步开始;想要地图的读卷二;想要敢合并的读卷三;想要合并后沉淀经验的读卷四;老项目直接看卷五阶段0,但也建议浏览一下卷一、卷三的要点。
一句话记住核心:SDD定规格与验收,结构进图谱,过程经Harness等工具落实ICV,习惯与决策留到合后再沉淀。
先认路,再干活,过关放行,再可选挂牌。
实用工具推荐
绿化、压缩、噪点和虚拟水印,自由调节做旧程度。
选择画质和输出格式,预览压缩前后的大小。