我们提出的这套方法论，正是围绕上述两条主线构建的。一条称为结构轨，其作用是描绘系统的架构形态、入口位置以及修改所影响的模块范围，主要载体为技术图谱；另一条称为过程轨，负责规范协作流程、明确人工审查节点，以及判断本次交付是否达到合并标准。两条轨道相互正交叠加，各司其职，彼此独立又协同运作。
下文将进行详细展开。请先记住以下几个核心关键词：SDD（规格驱动开发）、ICV三支柱（Inform · Constrain · Verify），以及 Epic（有边界的一包交付）。我们并非在创造新概念，而是将这些原则切实落地到工程协作的日常实践中。至于Harness，可理解为践行SDD的一套具体工具与执行纪律。
本系列文章共分为五卷，本篇作为总览，旨在为您提供一张可跨项目迁移的原则性地图。
1. 问题陈述：失败常不在模型
您可能经历过以下典型场景：使用自然语言描述需求后，Agent开始修改文件，开发者肉眼检查变更，随后合并代码。整个过程看似顺畅，但各类问题却层出不穷。
- 修改A模块却遗漏了B模块，直到联调阶段才暴露问题：根本原因在于Agent不了解系统的整体结构，不清楚模块间的依赖关系。
- 同一需求需要反复向Agent描述：由于缺乏可复用的规格说明与任务依据，每次沟通都几乎是从零开始。
- PR虽然能够合并，但内心始终不踏实：缺少书面的验收标准和自动化的合并门禁，决策完全依赖个人直觉。
- 对话记录越来越长，token消耗越来越高：将整份代码库或文档直接灌入模型，处理效率极为低下。
这些问题与“是否会写代码”有一定关联，但远不止于此。单纯依靠优化提示词（Prompt）或事后提炼技能（Skill），无法从根本上解决。技能记住的更多是过往习惯与教训，若一次任务中既没有技术图谱作为指引，也没有验收门禁进行把关，该遗漏的模块依然会遗漏，该犹豫的合并决策照样无法果断执行。
关键在于，这套方法的逻辑与模型能力是解耦的。同一份任务单、同一张技术子图、同一套合并前检查清单，即便换用不同档次的模型来执行，最终的交付口径仍能保持对齐。工具会不断演变，但意图、成果、验收这三件事，不应随模型的表现波动而随意更改。
2. 双主轴：过程轨与结构轨
为什么需要两条独立的轨道？因为它们各自解决不同维度的问题。您可以将整个协作过程想象为工地上的运输车辆。技术图谱就像一张带有方向标识的路网图，清晰标注了从哪个入口进入、会接入哪些作业区域。当Agent被分派任务时，它只需查看自己当前任务所需的那一小片局部地图，而非整座城市的全貌。而关卡（即过程轨上的验证节点）负责检查：所有验证项是否已通过？是否已完成签收？只有确认无误，才能从辅路进入主干道。
经验卡片或技能，类似于路口的警示牌，提示此地常有施工项目。但它们不能替代路网地图本身，也无法替代关卡的检查功能。您的终极目标在地图上的某个入口节点，而非仅仅停留在警示牌上。
2.1 各答一问
| 轨道 | 回答的问题 | 典型载体 |
|---|---|---|
| 过程轨 | 如何进行协作？何时需要人工介入审查？本次交付是否能够合并？ | 任务单、审查记录、合并前检查清单全部通过 |
| 结构轨 | 系统架构是什么样的？从哪里进入？修改会影响哪些范围？ | 技术图谱（主图、子图、契约/入口清单、图谱CI） |
这里需要特别说明，表格中提到的“图谱CI”，指的是用于检测结构文档与代码一致性的自动化检查机制，例如验证入口清单、契约锚点等，它并非用来替代业务功能测试的流水线。
两条轨道是正交的关系。这意味着在同一个Epic中，既可以包含“图谱入口：从登录子图进入”的结构性描述，也可以包含“验收条件：单测、lint全部通过、技术负责人书面签字”的过程性要求。指标体系不能混用，不能因为对话记录写满了就认为任务已经完成。
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 | 开工前向团队和Agent明确说明需要阅读哪些内容、范围是什么、依据是什么 | 任务单：背景信息、非范围、依赖关系说明 | 图谱入口；查询子图，而非将整仓文档全部灌入 |
| Constrain | 将边界条件和失败情况规则化 | 失败路径、测试策略、触发任务拒绝的清单 | 契约/入口清单；确保图谱中的门牌号与代码保持一致 |
| Verify | 合并前能够进行重复验证，出现问题时可以追溯责任 | 合并前检查清单全部通过、书面签收结果落地 | export/入口/叙述层CI；读法对照时设定题集边界 |
3.1 易混：SDD与Harness Engineering
这是新手最容易混淆的地方。SDD和Harness Engineering之间存在协同关系，但并不等同。我们通过下表来理清二者的区别：
| 维度 | SDD（规格驱动开发） | Harness Engineering（驾驭工程） |
|---|---|---|
| 起源 | 传统软件工程；通过契约与规格来管理系统复杂性 | 近年来围绕LLM的外部工程化讨论（如业界Mitchell Hashimoto提出的概念） |
| 核心 | 先清晰定义规格，再进行实现，确保实现与规格保持一致 | 围绕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的速率限制
| 要素 | 内容 |
|---|---|
| 意图 | 降低API的滥用风险；对内部批处理通道不适用限流策略；非范围：不修改鉴权模型、不更改计费逻辑 |
| 成果 | 限流中间件 + 可配置的阈值参数；统一的错误响应格式；更新对外接口文档说明 |
| 验收 | 超出限制时返回约定的HTTP状态码；单元测试覆盖边界情况与过期配置处理；配置缺失时默认使用预设值并记录告警日志；合并前检查清单全部通过；审查后完成书面签收 |
从事评测工作的读者可以对照此示例，检查你们的题面是否可测试，预期结果是否可验收，失败路径是否可记录——而不是仅停留在“模型修改得看上去像样”这个表面层面。
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，习惯与决策经验留到合并后再进行沉淀。
先认路，再干活，通过关卡放行，再可选地挂牌。
