Harness Engineering知识总结

文章目录

[Harness Engineering知识总结](#Harness Engineering知识总结)
[1-KIMI_Harness Engineering 十四讲核心要点](#1-KIMI_Harness Engineering 十四讲核心要点)
- 知识脉络总览
- [1. 模型能力强，不等于执行可靠](#1. 模型能力强，不等于执行可靠)
- [2. Harness 到底是什么](#2. Harness 到底是什么)
- [3. 让代码仓库成为唯一的事实来源](#3. 让代码仓库成为唯一的事实来源)
- [4. 把指令拆分到不同文件里](#4. 把指令拆分到不同文件里)
- [5. 让跨会话的任务保持上下文连续](#5. 让跨会话的任务保持上下文连续)
- [6. 让 agent 每次工作前先初始化](#6. 让 agent 每次工作前先初始化)
- [7. 给 agent 划清每次任务的边界](#7. 给 agent 划清每次任务的边界)
- [8. 用功能清单约束 agent 该做什么](#8. 用功能清单约束 agent 该做什么)
- [9. 防止 agent 提前宣告完成](#9. 防止 agent 提前宣告完成)
- [10. 跑通完整流程才算真正验证](#10. 跑通完整流程才算真正验证)
- [11. 让 agent 的运行过程可观测](#11. 让 agent 的运行过程可观测)
- [12. 每次会话结束前都做好交接](#12. 每次会话结束前都做好交接)
- [13. 从手动驱动到自动循环](#13. 从手动驱动到自动循环)
- [14. 从单循环到图工程](#14. 从单循环到图工程)
- 一张图记住全书
[2-GLM_Harness Engineering 十四讲核心要点](#2-GLM_Harness Engineering 十四讲核心要点)
- [〇、全课总脉络（一张图串起 14 讲）](#〇、全课总脉络（一张图串起 14 讲）)
- 第一讲｜模型能力强，不等于执行可靠
- [第二讲｜Harness 到底是什么](#第二讲｜Harness 到底是什么)
- 第三讲｜让代码仓库成为唯一的事实来源
- 第四讲｜把指令拆分到不同文件里
- 第五讲｜让跨会话的任务保持上下文连续
- [第六讲｜让 agent 每次工作前先初始化](#第六讲｜让 agent 每次工作前先初始化)
- [第七讲｜给 agent 划清每次任务的边界](#第七讲｜给 agent 划清每次任务的边界)
- [第八讲｜用功能清单约束 agent 该做什么](#第八讲｜用功能清单约束 agent 该做什么)
- [第九讲｜防止 agent 提前宣告完成](#第九讲｜防止 agent 提前宣告完成)
- 第十讲｜跑通完整流程才算真正验证
- [第十一讲｜让 agent 的运行过程可观测](#第十一讲｜让 agent 的运行过程可观测)
- 第十二讲｜每次会话结束前都做好交接
- [第十三讲｜从手动驱动到自动循环（Loop Engineering）](#第十三讲｜从手动驱动到自动循环（Loop Engineering）)
- [第十四讲｜从单循环到图工程（Graph Engineering）](#第十四讲｜从单循环到图工程（Graph Engineering）)
- 附：一页记忆卡

1-KIMI_Harness Engineering 十四讲核心要点

一句话主线：模型能力强 ≠ 执行可靠。Harness（模型之外的一切工程基础设施）决定了模型能力能被发挥多少。遇到失败，先修 harness，再考虑换模型。

知识脉络总览

阶段	讲次	解决什么问题
认知基础	1-2	为什么需要 harness；harness 是什么
指令与上下文	3-5	信息放哪、怎么放、怎么跨会话延续
工作方式	6-8	先初始化、划边界、用清单约束
验证与可观测	9-11	防谎报、跑全流程、可观测
收尾与自动化	12-14	交接、自动循环、图工程

1. 模型能力强，不等于执行可靠

AGENTS.md 文件告诉 agent 项目的技术栈、架构约定、验证命令，是投入产出比最高的第一步。
核心方法论是诊断循环：执行 → 观察失败 → 归因到 harness 的某一层 → 修补 → 重新执行。
归因五层：任务规范、上下文供给、执行环境、验证反馈、状态管理。哪层不足，加强哪层；不断修正，harness 不断变强。

2. Harness 到底是什么

Harness 五子系统模型：Harness = 指令 + 工具 + 环境 + 状态 + 反馈，五个子系统缺一不可。
一个 prompt 文件不是 harness；不是模型权重的部分，全是 harness。
其中反馈子系统（显式验证命令）通常是投入最少、回报最高的。
量化组件价值用"控制变量排除法"（逐个移除看性能下降）；harness 和代码一样会腐化，要定期审计。

3. 让代码仓库成为唯一的事实来源

仓库里不存在的信息，对 agent 来说等于不存在（仓库即规范）。Slack、Jira、脑子里的规则，agent 全都看不到。
检验标准"全新会话测试"：新会话只看仓库能否回答五个问题------是什么、怎么组织、怎么跑、怎么验证、做到哪了。
画地图四原则：知识靠近代码、标准化入口文件、最小但完备、和代码一起更新。
类比 ACID 管理 agent 状态：原子提交、一致性验证、隔离并发、持久化关键知识。
最大敌人是知识衰减：过时的文档比没有文档更危险。

4. 把指令拆分到不同文件里

典型陷阱：建一个 AGENTS.md，把能想到的所有规则、约束、历史教训都塞进去，文件越膨胀 agent 表现越差（上下文预算被吃掉、中间迷失、优先级冲突、矛盾累积）。
核心原则：入口文件是路由器，不是百科全书 。AGENTS.md 控制在 50-200 行：概览 + 运行命令 + 硬约束 + 指向专题文档的链接。
利用"中间迷失"效应：重要信息放文件顶部或底部，其余拆到专题文档按需加载。
"加条规则"是止痛药也是毒药：每条指令要有来源、适用条件、过期条件，定期审计删除。

5. 让跨会话的任务保持上下文连续

上下文窗口是有限的：agent 不只在生成代码，还要理解代码库、跟踪决策历史、处理工具输出、维护对话上下文。
信息不是均匀重要的：最终输出只有"是什么"，中间推理才有"为什么"。压缩通常保留前者、丢掉后者------新会话可能"优化"掉有意为之的设计决策。
上下文焦虑 （Anthropic）：agent 感觉上下文快满时会赶工收尾、跳过验证、选简单方案。
- 压缩（Compaction）：保留连续性，但"为什么"易丢失，且不能消除焦虑。
- 重置（Context Reset）：心理状态干净，但依赖交接工件的完备性。
解法：把 agent 当作每次会话清空短期记忆的工程师来管理------PROGRESS.md（进度）+ DECISIONS.md（为什么）+ git 检查点（状态快照），目标是把新会话重建成本压到 3 分钟。

6. 让 agent 每次工作前先初始化

直接做功能的代价：大量时间花在"搞清楚项目怎么运作"上，真正写功能的时间很少。
更隐蔽的代价是未验证的累积：测试框架配好之前写的代码，回头补测试时可能发现设计本身有问题，写得越多推翻越多。
正确做法：第一个会话只做初始化，产出四件套------可运行环境、可验证的测试框架（至少一个示例测试通过）、启动就绪清单文档、任务分解。
Git 提交作为检查点：初始化完成后提交一个干净的 checkpoint，后续所有工作从这里开始。
用"启动就绪清单"验收：能启动、能测试、能看进度、能接手下一步。热启动（用模板）优于冷启动。

7. 给 agent 划清每次任务的边界

Agent 天生有"多做一点"的冲动；提示太宽泛时，agent 倾向"同时启动多件事"而非"先做完一件事"。
本质是注意力数学问题：上下文容量 C 固定，同时做 k 件事，每件事只分到 C/k。写得越多，完成得越少。
核心约束：任何时刻只允许一个任务处于"进行中"状态（WIP=1）；当前任务端到端验证通过后才能开始下一个。
每个任务要有显式的完成证据（验证命令），harness 跟踪 VCR（验证完成率），VCR < 1.0 时阻止开新任务。

8. 用功能清单约束 agent 该做什么

Anthropic 和 OpenAI 都强调：工件必须外部化。功能状态必须是仓库里机器可读的文件，不能是对话里的非结构化描述。
功能清单是 harness 原语：调度器、验证器、交接器都依赖它；类比数据库 schema------任何 SQL 都无法跳过，而不是依赖应用代码的正确性、可能被绕过。
没有功能清单，理解鸿沟会持续存在和放大。
每个功能项必须有三元组：行为描述 + 验证命令 + 当前状态，缺一项就不完整。
状态转移由 harness 控制，agent 不能自己改状态；通过验证是唯一的升级路径。
功能清单是"该做什么"的单一权威来源，粒度控制在"一次会话能完成"的范围：太粗做不完，太细管不过来。

9. 防止 agent 提前宣告完成

Guo 等人 2017（ICML）：现代神经网络系统性地过度自信，自报置信度显著高于实际准确率。
Anthropic 2026 年研究：agent 被要求评估自己工作时，会系统性地过度正面评价，即使质量明显不达标。
结论：代码写完了不代表做对了；harness 必须用外部化的、基于执行的验证替代 agent 的"感觉"。
三层校验缺一不可：语法通过 → 行为通过 → 系统通过，层层递进。
陷阱：单元测试通过 ≠ 任务完成------单测的设计哲学是隔离被测单元、模拟依赖，恰好无法检测跨组件问题。
错误消息必须包含具体修复步骤（只说"错了"不够）；核心功能验证通过之前不许重构------完成优先级约束是防止过早优化的关键。

10. 跑通完整流程才算真正验证

Agent 倾向只跑最快的测试然后宣告完成；只有端到端测试能证明系统级缺陷不存在。
当 agent 知道工作要过端到端测试时，它的编码行为会改变（预防效应）。
OpenAI Codex 实践：给 agent 写的错误消息必须包含修复指导。
审查反馈提升：把重复出现的代码审查意见转化为自动化测试------每次发现重复问题就加一条规则，harness 会自动变强。

11. 让 agent 的运行过程可观测

没有可观测性：agent 在不确定状态中做决策，评估变成主观判断，重试变成盲目摸索。
OpenAI 和 Anthropic 都将可靠性定义为证据问题；harness 必须以可指导下一步决策的形式暴露运行时行为和评估信号。

12. 每次会话结束前都做好交接

熵增定律：持续变更的系统不主动管理，复杂性必然增加；agent 每次会话都引入变更，不清理则技术债务指数级累积。
清洁状态：会话退出必须满足五个条件------构建通过、测试通过、进度已记录、无过时工件、启动路径可用。这才是"做完"的真正定义。
会话完整性类比数据库事务：要么全部完成并留下清洁状态，要么回滚到上一个一致状态，不存在"做了一半但还行"。
清理循环 ：定期执行的维护会话，系统性清除积攒的问题------像汽车定期换机油，是常规保养不是紧急修复；且清理脚本要幂等，重跑安全。
Harness 简化：随模型能力提升，定期移除不再必要的 harness 组件------今天的必需约束，用更强模型可能就是多余开销。

13. 从手动驱动到自动循环

最好的入口不是复杂的架构图，而是一个具体命令------/goal "所有测试通过，lint 零告警，合并到 main"。
/goal 本质上就是一个 loop，结构只有三样：一个目标、一种验证方式、一条停止条件 。但就从循环里面移到了循环外面。
按触发方式和停止方式不同，loop 有多种形态；/goal 是最易理解的一种。

14. 从单循环到图工程

prompt → context → loop → graph：四个名字，一层叠一层。
单循环解决单一目标的自动执行；当工作流出现分支、依赖、多角色协作时，就要把 loop 组合成图（graph）------从"写一个循环"升级为"工程化一张流程图"。

一张图记住全书

复制代码

指令(AGENTS.md, 拆分到专题文档)
工具 + 环境(可复现)          ------ 第2、3、4讲：给 agent 一张好地图
状态(PROGRESS.md / DECISIONS.md / git) ------ 第5、6、12讲：跨会话不丢"为什么"
反馈(验证命令 / 三层校验 / 端到端)     ------ 第9、10、11讲：不信"感觉"，只信执行证据
循环(WIP=1 / 功能清单 / /goal / graph) ------ 第7、8、13、14讲：从人驱动到自动驱动

2-GLM_Harness Engineering 十四讲核心要点

整理自《Learn Harness Engineering》中文培训材料（14 讲讲义）。

用途：只保留核心知识要点，拿着这一份就能把整门课的知识脉络串起来。

〇、全课总脉络（一张图串起 14 讲）

整门课回答一个问题：模型能力强 ≠ 执行可靠，缺的那部分叫 Harness。

前十二讲把单次会话做可靠（Harness Engineering），后两讲把可靠的单次运行升级为自动运转的系统（Loop → Graph）。
#mermaid-svg-CCePQMPZHzfSQKAs{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-CCePQMPZHzfSQKAs .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-CCePQMPZHzfSQKAs .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-CCePQMPZHzfSQKAs .error-icon{fill:#552222;}#mermaid-svg-CCePQMPZHzfSQKAs .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-CCePQMPZHzfSQKAs .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-CCePQMPZHzfSQKAs .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-CCePQMPZHzfSQKAs .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-CCePQMPZHzfSQKAs .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-CCePQMPZHzfSQKAs .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-CCePQMPZHzfSQKAs .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-CCePQMPZHzfSQKAs .marker{fill:#333333;stroke:#333333;}#mermaid-svg-CCePQMPZHzfSQKAs .marker.cross{stroke:#333333;}#mermaid-svg-CCePQMPZHzfSQKAs svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-CCePQMPZHzfSQKAs p{margin:0;}#mermaid-svg-CCePQMPZHzfSQKAs .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-CCePQMPZHzfSQKAs .cluster-label text{fill:#333;}#mermaid-svg-CCePQMPZHzfSQKAs .cluster-label span{color:#333;}#mermaid-svg-CCePQMPZHzfSQKAs .cluster-label span p{background-color:transparent;}#mermaid-svg-CCePQMPZHzfSQKAs .label text,#mermaid-svg-CCePQMPZHzfSQKAs span{fill:#333;color:#333;}#mermaid-svg-CCePQMPZHzfSQKAs .node rect,#mermaid-svg-CCePQMPZHzfSQKAs .node circle,#mermaid-svg-CCePQMPZHzfSQKAs .node ellipse,#mermaid-svg-CCePQMPZHzfSQKAs .node polygon,#mermaid-svg-CCePQMPZHzfSQKAs .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-CCePQMPZHzfSQKAs .rough-node .label text,#mermaid-svg-CCePQMPZHzfSQKAs .node .label text,#mermaid-svg-CCePQMPZHzfSQKAs .image-shape .label,#mermaid-svg-CCePQMPZHzfSQKAs .icon-shape .label{text-anchor:middle;}#mermaid-svg-CCePQMPZHzfSQKAs .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-CCePQMPZHzfSQKAs .rough-node .label,#mermaid-svg-CCePQMPZHzfSQKAs .node .label,#mermaid-svg-CCePQMPZHzfSQKAs .image-shape .label,#mermaid-svg-CCePQMPZHzfSQKAs .icon-shape .label{text-align:center;}#mermaid-svg-CCePQMPZHzfSQKAs .node.clickable{cursor:pointer;}#mermaid-svg-CCePQMPZHzfSQKAs .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-CCePQMPZHzfSQKAs .arrowheadPath{fill:#333333;}#mermaid-svg-CCePQMPZHzfSQKAs .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-CCePQMPZHzfSQKAs .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-CCePQMPZHzfSQKAs .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-CCePQMPZHzfSQKAs .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-CCePQMPZHzfSQKAs .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-CCePQMPZHzfSQKAs .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-CCePQMPZHzfSQKAs .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-CCePQMPZHzfSQKAs .cluster text{fill:#333;}#mermaid-svg-CCePQMPZHzfSQKAs .cluster span{color:#333;}#mermaid-svg-CCePQMPZHzfSQKAs div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-CCePQMPZHzfSQKAs .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-CCePQMPZHzfSQKAs rect.text{fill:none;stroke-width:0;}#mermaid-svg-CCePQMPZHzfSQKAs .icon-shape,#mermaid-svg-CCePQMPZHzfSQKAs .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-CCePQMPZHzfSQKAs .icon-shape p,#mermaid-svg-CCePQMPZHzfSQKAs .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-CCePQMPZHzfSQKAs .icon-shape .label rect,#mermaid-svg-CCePQMPZHzfSQKAs .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-CCePQMPZHzfSQKAs .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-CCePQMPZHzfSQKAs .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-CCePQMPZHzfSQKAs :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} L1-2 为什么

模型强≠可靠

Harness五子系统
L3-6 打地基

指令层 + 状态层

仓库/拆分/连续/初始化
L7-12 管过程

范围+验证+观测+交接

WIP=1/清单/三层校验/E2E/可观测/清洁状态
L13-14 升维

Loop → Graph

人从循环里移到循环外

阶段	讲次	一句话
认知基础	L1-2	失败先修 harness 不换模型；Harness = 指令+工具+环境+状态+反馈
指令与状态	L3-6	仓库是唯一事实源 → 指令拆分 → 跨会话连续 → 先初始化再干活
范围与验证	L7-10	WIP=1 → 功能清单定范围 → 三层校验防提前完成 → 端到端才算真验证
观测与运维	L11-12	运行可观测 → 会话结束留清洁状态
自动化升维	L13-14	/goal 最简 loop（六原语）→ 图工程（节点/边/状态/路由）

第一讲｜模型能力强，不等于执行可靠

核心命题：失败时先怀疑 harness，不要先换模型。模型没变，变的是环境。

能力鸿沟：SWE-bench 通过率 50-60%，真实任务（需求模糊、无现成测试）只会更低。
经典对照：同一 Opus 4.5 跑同一 prompt，裸跑 20 分钟/ $9 不可用；配完整 harness（planner+generator+evaluator）6 小时/$ 200 可用------换的是"马具"，不是马。
五类典型失败：需求模糊、隐性约定没写下来、环境配置缺口、缺少验证手段、跨会话状态丢失。
核心方法论------诊断循环：执行 → 观察失败 → 归因到五层（任务规范/上下文/环境/验证/状态）→ 修补该层 → 重跑。不断修正，不断变强；哪层不足，加强哪层。
第一步也是投入产出比最高的一步：仓库根目录放 AGENTS.md（技术栈、架构约定、验证命令）+ 给每个任务写显式的完成定义。

第二讲｜Harness 到底是什么

核心命题：Harness = 模型权重之外的一切工程基础设施，五个子系统缺一不可。

Harness = 指令 + 工具 + 环境 + 状态 + 反馈 。
- 指令：AGENTS.md/CLAUDE.md（概览、技术栈版本、启动命令、硬约束、文档链接）
- 工具：够用且最小权限（禁了 shell，agent 啥也干不了）
- 环境：自描述、可复现（依赖锁定、版本文件、容器）
- 状态：PROGRESS.md 等进度跟踪，会话结束更新、开始读取
- 反馈：显式验证命令（test/lint/build）------通常投入最少、回报最高
案例：一个团队四个阶段（只加 README → 加 AGENTS.md → 加验证命令 → 加进度模板），成功率 20% → 80-100%，模型一个字没改。
量化方法：控制变量排除法，逐个移除子系统看性能降幅；但定位瓶颈要靠失败记录和归因，拆除实验只是辅助证据。
Harness 和代码一样会腐化，要定期审计、还 harness 债。

第三讲｜让代码仓库成为唯一的事实来源

核心命题：仓库里不存在的信息，对 agent 来说等于不存在。

Agent 的输入只有三样：系统提示和任务、仓库文件、工具输出。Slack/Jira/Confluence/脑子里的约定，它全看不到，也不能问人。
检验方法------全新会话测试：开全新会话只看仓库，能否回答五问：这是什么系统？怎么组织？怎么跑？怎么验证？现在做到哪了？
画图四原则：知识靠近代码（就近放，src/api/ARCHITECTURE.md > 500 页 Confluence）；标准化入口文件（50-100 行）；最小但完备；和代码一起更新。
知识衰减是最大敌人：过时的文档比没有文档更危险。
用 ACID 原则管 agent 状态：原子性（git commit 原子化）、一致性（验证谓词，不 commit 不一致状态）、隔离性（多 agent 别写同一文件）、持久性（跨会话知识必须落盘）。

第四讲｜把指令拆分到不同文件里

核心命题：入口文件是路由器，不是百科全书。"加条规则"是短期止痛药、长期毒药。

巨型指令文件的恶性循环：出错 → 加规则 → 文件膨胀（50→600 行）→ 表现反而下降。
四宗罪：吃掉上下文预算（占窗口 8-15%）；中间迷失（Liu et al. 2023：LLM 对长文本中间部分利用率显著低于两端，埋在第 300 行的安全约束必被忽略）；优先级冲突（硬约束/建议/历史教训混在一起分不清轻重）；维护衰减与矛盾累积（只增不减）。
拆分架构：入口 AGENTS.md 50-200 行 = 项目概览 + 快速开始 + 全局硬约束（≤15 条）+ 专题文档链接；专题文档 50-150 行放 docs/，按需加载。
利用位置效应：必须放入口文件的信息放顶部或底部。
像管理技术债一样管理指令：每条标来源、适用条件、过期条件，定期审计删除。

第五讲｜让跨会话的任务保持上下文连续

核心命题：把 agent 当成每次上班都失忆的工程师来管理------下班前必须写交接。

上下文窗口有限且增长快于扩容（还要装代码库理解、决策历史、工具输出）。更深层：信息不均匀重要------中间推理含"为什么"（为什么选 A 不选 B），最终输出只有"是什么"（代码）。压缩常保"是什么"丢"为什么"，新会话可能"优化"掉有意为之的设计。
上下文焦虑 （Anthropic）：agent 感觉上下文快满时会赶工收尾、跳过验证、选简单方案。两种对策：
- 压缩：同会话摘要化。保连续性，但丢"为什么"，且不消除焦虑。
- 重置：清空重开，从持久化工件重建。心理干净，但依赖交接工件的完备性。
- 结论：harness 设计要对目标模型具体理解（Opus 4.5 焦虑弱可只靠压缩，弱模型必须靠重置）。
四件持久化工具：PROGRESS.md（状态/已完成/进行中/已知问题/下一步）、DECISIONS.md（决策+原因+否决方案）、git 提交检查点、AGENTS.md 里的上下班流程。
关键指标是重建成本：好的 harness 让新会话 3 分钟恢复可执行状态（对比无持久化 15 分钟；功能完成率 58%→100%）。
混合策略：短任务会话内完成；任务上下文需求超窗口 60% 就开始准备交接。

第六讲｜让 agent 每次工作前先初始化

核心命题：初始化和实现是两种性质不同的工作，必须分成两个阶段。

混在一起的代价：基础设施搭不牢（80% 精力写功能）；未验证的累积（测试框架没配好之前写的代码，回头补测试时才发现设计有问题，写得越多推翻越多）；上下文预算两头空；隐式假设埋雷（会话 1 选 Vitest、会话 2 又引入 Jest）。
Anthropic 数据：独立初始化的项目，多会话功能完成率高 31%；初始化投入在后续 3-4 个会话收回。
初始化会话的产出（不写业务代码）：① 可运行的环境；② 至少一个通过的示例测试；③ 启动契约文档（启动/测试/验证命令、当前状态、项目结构）；④ 任务分解（每个任务带验收标准）；⑤ git 干净检查点------后续一切从此开始。
验收四条件（启动就绪清单）：能启动、能测试、能看进度、能接手下一步。
热启动优于冷启动：用项目模板预置基础设施。

第七讲｜给 agent 划清每次任务的边界

核心命题：WIP=1 是 agent harness 的默认安全设置------任何时刻只允许一个任务处于"进行中"。

Agent 天生"多做一点"；Anthropic 明确指出：提示太宽泛时，agent 倾向"同时启动多件事"而非"先做完一件事"。
简单数学：容量 C 分给 k 个任务，C/k 低于完成阈值时全部做不完。数据："小下一步"策略完成率高 37%；代码行数与功能完成数弱负相关------写得越多完成得越少。
两个共生问题：过度延伸 （overreach）↔ 不足完成（under-finish），互相加剧成恶性循环。
落地四招：强制 WIP=1 写进工作规则；每个任务定义可执行的完成证据（"curl 返回 201"才算，"代码看起来没问题"不算）；范围表面外部化为机器可读文件；监控 VCR（验证完成率 = 通过验证任务数/启动任务数），VCR<1 阻止开新任务。
一句话：少做但做完，永远优于多做但做半。

第八讲｜用功能清单约束 agent 该做什么

核心命题：功能清单不是备忘录，是 harness 原语------所有组件依赖的基础数据结构。

没有完成标准时，agent 用自己的隐式标准判断"做完"（通常是"代码没有明显语法错误"），理解鸿沟持续存在和放大。
工件必须外部化（Anthropic/OpenAI 共同强调）：功能状态必须是仓库里机器可读的文件，不能是对话里的非结构化描述。
为什么是原语：类比数据库触发器约束 vs 应用层检查------前者由引擎强制、任何 SQL 无法跳过；后者依赖应用代码、可能被绕过。功能清单承担数据库级约束角色。调度器（选任务）、验证器（判完成）、交接器（生成报告）、进度追踪器全靠读它。
每个功能项必须是三元组：行为描述 + 验证命令 + 当前状态 ，缺一不完整。状态机：not_started / active / blocked / passing。
状态转移由 harness 控制，agent 不能自己改状态；通过验证是唯一的升级路径。
功能清单是"该做什么"的单一权威来源。粒度 = 一次会话能完成（太粗做不完，太细管不过来）。
效果：完成率 +45%，零重复实现；好的进度记录减少 60-80% 的会话启动诊断时间。

第九讲｜防止 agent 提前宣告完成

核心命题：代码写完 ≠ 做对。完成判定必须外部化，用基于执行的验证替代 agent 的"感觉"。

理论依据：Guo et al. 2017（ICML）证明现代神经网络系统性过度自信，自报置信度显著高于实际准确率------agent 的置信度校准偏差是客观存在的。
最危险陷阱：单元测试通过 ≠ 任务完成。单测的设计哲学是隔离单元、模拟依赖，恰好无法检测跨组件问题（接口不匹配、状态传播错误、环境依赖性）。
三层终止校验，层层递进缺一不可：① 语法/静态分析 → ② 运行时行为验证（测试、启动检查）→ ③ 系统级端到端确认。下层没过不许进上层。
错误消息要包含具体修复步骤（OpenAI）：出了什么问题 + 为什么 + 怎么改。只说"错了"不够，好的报错让 agent 能自我修正。
更深层失败模式（Anthropic 2026）：agent 评估自己的工作时会系统性过度正面 。解法不是"更客观"，而是干活的和检查的分开（planner/generator/evaluator 三角色）。
完成优先级约束：核心功能验证通过之前，不许重构、不许优化。

第十讲｜跑通完整流程才算真正验证

核心命题 ：单元测试对组件边界缺陷系统性盲视，只有端到端测试能证明系统级缺陷不存在。

单测四大盲区：接口不匹配、状态传播错误、资源生命周期问题（句柄/连接泄漏）、环境依赖性。案例：5 个组件边界缺陷，单测一个没发现，端到端全部捕获（代价：2 秒 → 15 秒，可接受）。
反直觉的一点：知道要过端到端测试，agent 的编码行为会改变------更考虑组件交互、更尊重架构边界、更处理错误路径。
架构规则必须可执行：第一天就建立边界约束（agent 会复制仓库已有模式，包括坏模式），把"渲染进程不能直接访问文件系统"这类规则变成 lint/CI 检查。原则：执行不变量，不微管实现。
面向 agent 的错误消息三要素：ERROR（什么错）+ WHY（为什么）+ FIX（怎么修）。
审查反馈提升：把重复出现的审查意见转化为自动化测试------每次发现重复问题就加一条规则，harness 自动变强。

第十一讲｜让 agent 的运行过程可观测

核心命题：没有可观测性，agent 在不确定状态中做决策，评估变主观判断，重试变盲目摸索。可靠性是证据问题。

可观测性缺失的四类问题：无法区分"正确"和"看似正确"；评估变成玄学；重试变成盲猜；会话交接断崖（重复诊断可占会话时间 30-50%）。
双层可观测性，缺一不可 ：
- 运行时可观测：日志、追踪、健康检查------回答"系统做了什么"
- 过程可观测：计划、评分标准、验收条件------回答"为什么这个变更应该被接受"
两个核心工具：冲刺合同 （编码前协商：范围 + 验证标准 + 排除项，防止生成者做出评估者必然拒绝的东西）；评分标准（把"好不好"变成分维度可量化评分，评估可复现）。
Agent 自己打日志不够：它不知道自己不知道什么、格式不统一、过程可观测性不是日志能解决。
三 agent 架构（Anthropic 实验）：planner 扩展需求但不深入实现细节；generator 按 sprint 实现；evaluator 用 Playwright 像用户一样实测、按四维评分+硬阈值给具体证据反馈。Evaluator 需要调校------对照它和人类判断分叉的点，迭代它的 prompt。

第十二讲｜每次会话结束前都做好交接

核心命题：清洁状态是"做完"的必要条件------代码写完了但状态是脏的，就不算做完。

熵增（Lehman 软件演化定律）是默认方向：持续变更的系统无人管理，复杂性必然增加；agent 每次会话引入变更，不清理则技术债指数累积。"以后再清理" = 永远不清理。
清洁状态五条件（会话退出的真正定义）：构建通过、测试通过、进度已记录、无过时工件、启动路径可用。
会话完整性类比数据库事务：工作要么全部完成并留清洁状态，要么回滚到上一致状态，没有"做了一半但还行"。
实测数据（12 周）：无清洁策略构建通过率跌到 68%、新会话启动 60+ 分钟；有清洁策略保持 97%、9 分钟（启动时间差 85%）。
双模式清理：即时清理（每会话，谁产生谁清）+ 清理循环（每周，常规保养不是紧急修复）。
质量文档：给每个模块持续打健康分（A/B/C/D），是 harness 可观测性在代码库层面的体现。
Harness 简化：模型变强后，定期移除不再必要的组件（每月禁用一个跑基准，无退化就删）。能力边界在位移------旧问题被覆盖，新问题暴露出来。
幂等清理：清理脚本跑多少次结果都一样，失败重跑也安全。附：高吞吐下合并策略要变------修 bug 成本低于人工审查成本时，快速合并 + 快速修正更优。

第十三讲｜从手动驱动到自动循环（Loop Engineering）

核心命题 ：用系统取代你自己去 prompt agent------你的位置从循环里面移到循环外面。

/goal 是最简形态的 loop ，结构只有三样：一个目标 + 一种验证方式 + 一条停止条件。2026 年初 Claude Code 和 Codex 同时上线。对比传统 prompt：你给的是"最终状态"而不是"下一步"，判断做完的是"独立停止条件"而不是你。
演化四阶段：手动逐条输 → 长 prompt 多步骤 → agent 自省自己决定继续 → 独立的停止判断（不能让写代码的人自己批作业）。
Loop 分四种（按触发/停止方式）：回合制、目标驱动（/goal）、时间驱动（/loop）、事件驱动。区分口诀：这件事有终点吗？有 → /goal；没终点就是要一直盯 → /loop。
Loop 六大原语 ：Automations（自动触发）、Worktrees（并行隔离）、Skills（项目知识）、Connectors（连接外部工具）、Sub-agents（制作者/检查者）、External State（跨迭代持久记忆------其余五个零件都依赖的脊柱：记忆必须在磁盘上，不能在上下文里）。
Generator/Evaluator 分离是可靠性底线：模型是自己输出最好的辩护律师，给自己打分不可信。"你的人里必须有一个不信你的。"
最佳示范 Karpathy autoresearch：人只改 program.md（方向/方法论），agent 只改 train.py（代码）；九步棘轮循环只能前进不能后退；不给 agent 任务，给 agent 方法论，让方法论成为 loop。
四种沉默成本（跑越久越尖锐）：验证负债（"感觉通过"≠"机器确认"）、理解腐烂（你不读就跟不上）、认知投降（用 loop 逃避思考）、令牌爆炸（上下文随迭代膨胀，必须做压缩）。
从小开始：一个 /goal + 一个定时器 + 一个 markdown 记忆文件，看到回报再加。

第十四讲｜从单循环到图工程（Graph Engineering）

核心命题：图不是取代 loop，而是在它之上再建一层。loop 把问题藏在循环里，graph 把问题摆在纸上。

四层叠加，一层不取代一层：Prompt（指令）→ Context（信息）→ Loop（运行时）→ Graph（系统）。到了图，每个节点都带着自己的 prompt、context、工具、记忆、loop------图决定节点之间怎么连接。
图四零件：节点（工作单元：代码/模型调用/工具/完整 agent）、边（并行/条件/失败重试/回退）、共享状态（公共工作台，节点不互相喊话）、路由规则（测试过就交付、失败回实现、信息不足回研究）。
单 loop 什么时候不够：分工、并行、回退、交接四个问题冒出来时。本质区别：loop 是延期决策，graph 是提前决策（可读、可审计、可局部修复）。
单循环三种结构性 失败（检查点解决不了，因为判断者和被执行者共享同一个大脑）：Goodhart（指标涨了业务坏了）、向上失明（从不问"这个目标对吗"）、冲突（独立 loop 互相拆台）。另加 anchors（锚）：真实业务结果、ground truth、人工抽查------最容易被跳过、最不能省。
Graph ≠ Workflow ：节点装函数、边写死 = workflow；节点装完整 agent、边动态路由 = graph。图是 workflow 的泛化（图里可同时有 workflow 节点、agent 节点、人类审批节点）。唯一的新东西：节点从函数变成了 agent------节点变便宜了，图才值得画。
关键设计：verify 节点必须带全新上下文（fresh context，不继承实现者的记忆）------上下文隔离不是副作用，是设计。
建图六步：定义共享状态 → 列节点（每个节点自带私有 loop）→ 连边 → 写路由规则 → 挂 checkpoint（可中断恢复/人工审批）→ 跑。
三盆冷水：网传提升数字多为假数据（查原始出处）；形状不是承重墙（可重放、可观测、可恢复才是）；编排税------启动 agent 便宜、审阅结果昂贵，"你是你的 agent 们的 GIL"，你的判断力是串行资源。
什么时候真该用图（五判据至少满足三）：可独立拆分、有分支或回退路径、中间状态值得保存、结果可明确验收、协作收益 > 协调成本。"复杂"不等于"步骤多"------20 步线性流水线不需要图。

附：一页记忆卡

十四讲串成一句话 ：

给模型配一套 harness（指令+工具+环境+状态+反馈），以仓库为唯一事实源、指令按需拆分、状态落盘跨会话、先初始化后实现；用 WIP=1 和功能清单（行为+验证+状态三元组）划清范围；用三层校验和端到端测试替代 agent 的"感觉"，让它无法提前宣告完成；全程可观测（运行时信号 + 过程工件），每次退出留清洁状态；最后把触发权交给 loop（目标+验证+停止条件，六原语），复杂到有分支回退时升级为图（节点/边/状态/路由）------人自始至终只做判断，不做调度。

高频关键词：能力鸿沟 / 五子系统 / 仓库即规范 / 中间迷失 / 上下文焦虑 / 压缩 vs 重置 / 启动就绪清单 / WIP=1 / VCR / 功能清单原语 / 三元组 / 置信度校准偏差 / 三层终止校验 / 审查反馈提升 / 双层可观测性 / 冲刺合同 / 清洁状态五条件 / 会话完整性 / 幂等清理 / harness 简化 / /goal 三要素 / 六原语 / Generator-Evaluator 分离 / 四种沉默成本 / 四层叠加 / Goodhart / 编排税 / 锚（anchors）

配套材料（源文档后半部分，按需查阅）：8 个实战项目（每个对应 2 讲讲义）、4 篇前沿拆解（Pi / Claude Code / Codex / DeepSeek 的 harness 设计）、资料库（模板与方法对照表）、harness-creator 技能集。