AI编程闭环协作:从更会写到敢合并

作者:技术拾光时间:2026-06-03 13:51:07浏览:443

AI编程交付不达标源于结构轨与过程轨缺失:技术图谱明确系统入口与影响面,过程轨通过任务单、签收和合并前检查规范协作。基于SDD三支柱(Inform、Constrain、Verify)与Epic三要素(意图、成果、验收),实现可迁移的工程闭环,确保交付可对齐、可追溯。

先说一个核心判断:当前很多团队使用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的归属

![方法论地图_3_SDD-ICV-双轨-Harness.png](https://developer.qcloudimg.com/http-sa ve/yehe-12403993/66a092d44f2e8608b01d2d9a8c42c97a.png)

支柱(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_Epic简化交付链.png](https://developer.qcloudimg.com/http-sa ve/yehe-12403993/8ed3aacf19854c1fced52cfaf823fa6d.png)

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,习惯与决策留到合后再沉淀。

先认路,再干活,过关放行,再可选挂牌。