Harness Engineering（驾驭工程）

把「随缘的一次性提示」变成「可重复的 AI 工作系统」的方法论。本文件是主干：怎么用它、先查什么、去哪找诊断和处方。

0. 怎么用这个 skill

三步，顺序不要乱：

1. 体检：跑第 3 节的清单。命中哪几条，记下来。清单是可机检的，目的是把"感觉 agent 不太行"变成"第几条具体不成立"。
2. 诊断：拿命中的条目去 references/diagnoses.md 找对应病症，确认成因，拿到处方。一次只处理一两个最痛的，别一次性重构全部。
3. 施工：处方背后的通用做法在 references/playbook.md。改完回到第 1 步复检，确认没有引入新的坏味道（例如为治"虚假胜利"加了检查脚本，结果触发"反馈过载"）。

这套方法论素材会继续补充。素材新增或修订一讲时，按 references/course-map.md 的【增量补充约定】把增量补进来，并同步更新本文件第 3/4/5 节索引。

上面第 3 步说的"施工"，素材里叫知识固化（Knowledge Solidification）：把存在于对话中的、临时性的知识逐步写入文件，变成持久的、可复用的规则和工具（06:9–11）；它不只发生在构造阶段，每一次改进本质上都是一轮新的固化——试错找到有效做法，写入文件让它持久生效（06:329–331）。

1. 这套方法论解决什么问题

一句话本质：Harness 是给 agent 的"操控循环"（Steering Loop）——它决定 agent 在什么上下文里行动、行动后如何被检查、检查后如何调整。

本文件的其余部分，本质是一份坏味道 → 重构清单：所谓坏味道，是指在 Harness 中潜在的、可能影响 Agent 输出质量、造成输出不稳定的特征；重构就是有针对性地消除坏味道的过程（06:321、:323）。下面第 3 节的体检清单负责找坏味道，第 4 节的诊断给出判据，第 5 节的施工手册给出重构手法。

操控循环有四个环节，缺一不可（01 讲）：

前馈与反馈各有各的职责：前馈提高"做对的概率"，反馈提供"做对的证据"（12 讲）。只有反馈，agent 会重复犯同一个错；只有前馈，agent 会过于草率地结束任务（01 讲）。

在此之上还有一层循环：外层 PDCA 管任务分解与进度追踪，内层操控循环管单个子任务的执行质量（01 讲）。两层分工一旦模糊，skill 会去管计划、AGENTS.md 会去写执行细节，输出立刻开始漂（06 讲里"从 268 行精简到 122 行、把计划权收回 AGENTS.md"就是这个修正）。

被驾驭对象的内部结构：任何完整 Agent 的内部核心都是自我纠正循环——它是推理行动循环（ReAct：推理 → 行动 → 观察）的一个特殊形式：把"观察"换成"自我纠正"，每次迭代后检查输出是否满足质量标准（格式对不对、约束是否满足、数据是否完整），发现问题就修正、补充或询问用户，再回到推理-行动继续（02:9–19）。它本质上也是一个戴明环：推理-行动是 PD，"观察-自我纠正"是 CA，所以素材里称它为 Agent 的内置 Harness（Built-in Harness），是我们要驾驭的主要对象（02:19）。

还要区分内外两层 Harness：内部（内置）Harness 是 Agent 最核心的运行架构，围绕 Agent Loop 展开，各家正在高度趋同（直播回放:57–69）；外部 Harness 才是我们影响 Agent 行为的部分，也就是下面说的四个子系统（直播回放:71–73）。公式是 Agent = LLM + Harness，对应传统软件的 App = Runtime + Business Logic——大模型扮演通用运行时，应用里大量原本要写死的分支与流程改由它在运行时按语义和现场信息推断，Harness 则承担了原本属于业务逻辑与软件设计的职责（直播回放:19–27、:39–47）。因为内部架构已经趋同、重复手搓难以构成竞争力，真正值得投入的是外部 Harness：指令怎么写、状态怎么组织、工具与技能怎么设计、环境怎么搭建（直播回放:107–113）。这也是本 skill 只谈外部 Harness 的原因。

四个子系统承载这一切（02、直播回放）：

• 指令（Instructions）：前馈与反馈的载体，优先于单次对话输入，所以又叫 agent 的"宪法"。
• 工具与技能（Tools & Skills）：计算型控制的落点——把确定性的判断从提示词里搬进代码。
• 环境（Environment）：保证可复现。反馈信号只在一致的环境里才有意义（02 讲）。
• 状态（State）：连接内层与外层的桥梁。技能通过计划文件接收调度、通过进度文件回报结果，没有这条双向通道，技能就是孤岛（04 讲）。

一条贯穿全课的判断标准：确定性归代码，语义判断归模型（02、05 讲）。能用脚本判的别写成规则；需要理解语义的别硬编码成条件分支。理想分工大致是代码承担六到七成可形式化的检查，模型覆盖剩下三到四成需要语义理解的部分（05 讲）。

仓库即规范：仓库是 Agent 系统的唯一事实来源（Single Source of Truth）——Agent 需要的一切都以文件形式放在仓库里，不在仓库里的就等于不存在；状态子系统通常也以文件形式入库；仓库结构按 Agent 优先（Agent-first）设计，而不是迁就人的阅读习惯（05:15–27、03:40–42、09:5）。

最小干预：能用自动化反馈（Sensor）纠正的，就不要依赖人每轮介入——把人当成 Sensors 会让人沦为系统里最慢的瓶颈，而且次数多了大部分人都会放弃参与、盲目接受产出（05:69–77）。

被优化的对象常常就是 harness 本身：上下文如何压缩、状态如何跨会话延续、子任务如何委派与回收——这些机制决定了你能把哪些质量要求"内建"进去，而不是每轮靠人盯着（"被优化的对象就是 agent harness 本身"这一视角来自另一份关于 agent harness 内部机制的工程实践材料，仅参考 06、08、10 讲；本 skill 只借它说明优化对象，个别机制词汇按需借用并注明出处，见 playbook §6 的"失败关闭"）。

2. 什么时候用 / 不该用在哪儿

该用（命中任一条即可继续）：

• 你在写或改 AGENTS.md、SKILL.md、原则文档、规则登记表、验收脚本、checkpoint 协议、环境初始化脚本。
• 同一个 agent 任务今天好明天坏；同一个错误反复出现；你已经在往规则文件里加第 N 条补丁。
• 你要把一个每周/每天重复的工作流，从"每次贴一段提示词"升级成可复用系统。
• 你在为难自动化的任务设计验收（到底"什么算完成"），或者发现完成判断始终由生成者自己宣布。
• 你在设计外部 Harness——指令怎么写、状态怎么组织、工具与技能怎么设计、环境怎么搭建。这正是 Agent 系统的差异来源：内部 Harness（Agent Loop）已经趋同，重复手搓难以构成核心竞争力（直播回放:107–113）。

不该用（先说明理由再退出）：

• 单次、一次性的任务（写一封邮件、润色一段话、生成一张图）。这类任务打磨 harness 不划算，收益不累积；累积效应只出现在重复性工作上（开篇词）。
• 问题出在模型能力或任务粒度上（本 skill 的边界判断，不是素材主张）：素材明确说"并不是所有任务都可以通过拆分成更细小的任务来提高质量"（01:21），并提醒拆到一定程度后真正的瓶颈不再是计划颗粒度，而是具体工作的 Know-how（直播回放:125–127）；开篇词引用的对照实验里，模型和提示词都没换，只加了 Harness，同一个任务就从"核心功能完全不能用"变成"功能完全可用"（开篇词:68–73）。所以只有在四个环节都排查过、仍无改善时，才把问题归到模型或粒度上。
• 具体代码 bug 的定位与修复：那是调试流程，不是 harness 设计。
• 纯文本写作与排版规范：交给写作类 skill，本 skill 不替代它。

遇到不满意产出时的默认动作：先停一秒，问"问题落在哪一环节"——是没提前说清楚（前馈不够）、是没检查对（反馈不够）、还是上一轮结果没被记住（状态丢了）？然后动手改对应的那个环节，而不是改措辞（开篇词、01 讲）。

按症状选入口（不用通读整本手册）：

一次改造的推荐顺序（本 skill 补充，非素材主张；依据素材的"默认最佳实践"与依赖关系，素材并未给出跨讲的统一改造顺序）：

1. 需求与优先级先行（07、08）。上游没写清，后面所有检查都在验证一个错误的目标。
2. 补反馈（12、10、13）。反馈优先是默认最佳实践，成本最低、见效最快：先写检查形式、保证成功静默、按责任分级。
3. 再治状态（16、17、15）。状态是内外两层的桥梁，桥不稳，前面两步的成果会跨会话丢失。
4. 最后动环境与范例（18、19）。这两项一次投入、长期收益，但改动面较大（依赖、目录、架构约束）。
5. 指令文件治理（11）作为横切：任何阶段都可做，但重点是把"矛盾检测 + 定期清理"做成例行机制，而不是重写一遍结构。

3. 快速体检清单

每条都能在仓库里查。凡是"查不了"的，本身就是问题——说明它只存在于人脑里。命中越多，越该往下走诊断。

怎么读结果（本 skill 补充，非素材主张）：清单不追求全绿。经验上，第 9–14 条（反馈与完成判断）和第 15–18 条（状态）是最高频的失效点；第 1–8 条（指令与规则）负责解释"为什么规则越加越多却越来越不灵"；第 19–20 条（技能）只在你有多个技能、或技能反复不被触发时才需要查。

四环节快速自检

如果不想逐条查，先做一个 60 秒的四环节自检，它会指向大致方向：

指令与规则

1. 规则有没有写在可解析的记录里（编号、优先级、状态是字段，而不是散落在散文里）。 查：grep -cE '^编号[:：]|^\| *[A-Z]+-[0-9]+' docs/rules.md AGENTS.md；若只有成段散文，就是没登记。
2. 每条规则是否都有优先级。 查：条目总数 vs 含"优先级/红线/规则/建议"的条目数，不等即缺。没有优先级的规则列表，和散落的文字没区别（11 讲）。
3. 每条规则是否都有过期条件。 查：grep -c '过期条件' docs/rules.md 与条目数对比；没有过期条件的规则永远不会被清理。
4. 编号是否被重排或复用。 查：git log -p docs/rules.md | grep -E '^[-+].*\b[A-Z]+-[0-9]+'，看历史里是否有编号换过含义。编号是身份，不是排序位——本 skill 纪律（延伸自 11:103 的留痕与可审计要求）。
5. 有没有只存在于人脑里的约定。 查：让一位没参与过的人只读仓库做一次同类任务；他卡住的地方就是隐含约定（08 讲）。
6. 引用的文件与规则号是否还存在。 查：抽出正文里所有路径引用与 [A-Z]+-\d+ 引用，逐个 test -e / 在登记表里 grep；悬空引用就是腐烂点，必须修，不能靠"应该还在吧"。
7. 常驻文件是否在失控膨胀，或出现成片例外条款。 查：wc -l AGENTS.md docs/*.md；再 grep -nE '但是|除非|例外|特殊情况' AGENTS.md。重点不是行数（50–200 行都健康），而是规则是否在互相打补丁（11 讲）。
8. 是否同一条规则反复加例外。 查：同上，按主题归类例外条款；同一主题出现多条例外，需要的是裁决，不是再补一条。

反馈与完成判断

9. "完成"是否由生成者自己宣布。 查：在指令文件里 grep -niE '宣布完成|自行判断|看起来没问题|差不多就算'；再确认是否真的存在独立验证者（脚本、检查器、或另一个人）。生成者的"我感觉做完了"不算数（10 讲）。
10. 是否存在永远绿的检查。 查：故意注入一个必然错误，跑一遍验证，必须变红；红不了就是摆设。
11. 检查命令有没有吞掉退出码或错误。 查：grep -nE '\|\| *true|; *true|2>/dev/null|set \+e' <验证脚本>。
12. 反馈是否分级。 查：跑一次验证，看输出是不是一锅平铺；grep -nE '阻塞级|警告级|信息级' 是否有分级定义（13 讲）。
13. 成功是否静默。 查：跑一次全部通过的验证，输出应为一句话或空。通过项刷屏会把失败信号淹没（13 讲）。
14. 每条验收能不能用"是/否"判定。 查：逐条读验收标准，凡出现"写得好""足够清晰""语气合适"却没有判定方式的，要么改写为可观察项，要么显式交给人判断并标明（10、13 讲）。

状态与跨会话

15. 状态里有没有"这一次执行"的痕迹。 查：grep -rnE '"(date|last_run|this_session|temp|debug)"' state/，再判断它是不是跨会话事实。单次执行数据混进持久状态就是污染（17 讲）。
16. 同一事实是否在多处出现。 查：对同一指标在多处 grep；出现两份就可能对不上。状态应当有唯一主人（16、17 讲）。
17. 常驻文档里有没有会过期的数字。 查：grep -nE '[0-9]+ *(个|条|项|%|行)' docs/*.md AGENTS.md，把"当前有多少"改写成"去哪儿查"。形态来自 03:168–175 的"进度怎么查"表，并在 10:63–73 被当最佳实践复述；"常驻文档里不写会过期的数字"这一理由为本 skill 补充，非素材主张（对齐 09 讲信息散落、17 讲状态唯一主人）。具体写法见 playbook §5。
18. checkpoint 是否保留了四项。 查：读 checkpoint 文件，确认含进度、关键决策及理由、验证记录、未决事项；缺任何一项都可能要重做（15 讲）。

技能与触发

19. description 写的是"何时用"还是"能干什么"。 查：读每个 SKILL.md 的 frontmatter，看是否给出触发场景与"不要用于"。description 是唯一常驻上下文、也是唯一的竞争位（20 讲）。
20. 多个 skill 的 description 是否撞车；第三方 skill 是否本地化并 pin。 查：把所有 description 并列比对语义重叠；再确认第三方 skill 是否落在项目内并锁了版本（18、20 讲）。

一个走通的例子

假设"每周汇总用户反馈"这个重复任务，产出时好时坏。走一遍：

1. 体检：第 1 条不成立（要求散在一段散文里，没有编号与优先级）→ 命中 11；第 9 条不成立（完成由生成者自己宣布）→ 命中 10；第 17 条命中（文档里写着"本期共 137 条"，每周都过期）。
2. 诊断：读 10、11 的成因与判据。发现"只做了六成却宣布完成"更痛，先治 10。
3. 处方：
   • 把完成条件改成可验证的（"本期反馈全部处理，每条有分类；未处理的必须有原因"）。
   • 要求记录原始进度（已处理 82 / 137，跳过清单及原因），而不是"处理得很好"。
   • 把判断从生成者手里拿走：写一个 check_feedback.py，只读处理结果文件，输出 PASS/FAIL；在指令文件里写明"只有脚本输出 PASS 才算完成"。
4. 复检：重跑第 3 节。新增的风险是第 12/13 条——脚本若把全部通过项也打印出来，就会淹没失败信号。于是补上"成功静默 + 阻塞级/警告级/信息级"。
5. 留档：这轮改动落到 references/playbook.md 的第 2、7 组；若素材后续新增了讲次，按第 6 节的约定回链与记录。

这个例子的价值不在具体步骤，而在循环形态：体检 → 诊断 → 处方 → 复检，每次只处理最痛的一两处，改完立刻回查有没有引入新的坏味道。

4. 诊断与处方索引

按病症逐条查 → references/diagnoses.md

覆盖：需求模糊（07）、隐式约定（08）、信息散落（09）、虚假胜利（10）、指令文件腐化（11）、前馈痴迷（12）、反馈过载（13）、上下文倾倒（14）、上下文焦虑（15）、跨会话知识丢失（16）、状态污染（17）、环境漂移（18）、模式复制漂移（19）、技能触发与体积失控（20）。

每条固定给：症状 / 成因 / 判据（尽量可执行）/ 处方（注明讲次）/ 常见误判。

5. 施工原则索引

正面做法 → references/playbook.md

十一组：分层与渐进披露、前馈↔反馈配比、规则治理、skill 写法、状态与跨会话、环境锁定、反馈分级、范例优先于约定、仓库即规范、最小干预、知识固化。每条都注明讲次，并给"改造前 → 改造后"的形态对比。

6. 素材增量如何进入本 skill

• 触发：素材新增一讲、修订某讲，或直播回放提出了新主张。
• 判定：它属于"新诊断"还是"新处方"还是"改写既有主张"。
• 落位：诊断 → references/diagnoses.md；处方 → references/playbook.md；两者同时更新映射表。
• 回链：同步更新本文件第 3/4/5 节的索引，保持索引可解析（能被 grep 到、能顺着点下去）。
• 留痕：在 references/course-map.md 底部变更记录表追加一行。

纪律是"只增不改既有条目"：不重排既有段落以免引用腐烂；旧主张被新素材推翻时标 superseded 并保留，而不是删除（11 讲：删除要留痕）。

7. 来源与边界

• 方法来源：一套关于 agent 驾驭工程的内部方法论课程，含开篇词、01–20 讲、直播回放与索引，共 24 个文件。讲次编号（如"07 讲"）保留仅为可追溯，是溯源标签而非依赖：正文只做短引并标注讲次（便于回查来源），脱离原始素材也能独立使用。讲次 ↔ 章节的映射见 references/course-map.md。
• 补充视角：另一份关于 agent harness 内部机制的工程实践材料（仅参考 06、08、10 三讲），用于理解"被优化的对象是 agent harness 本身"；它只提供机制词汇，不覆盖本 skill 的方法论主张。
• 本文件是方法论提炼，不是任何课程原文的副本：正文不含整段搬运，示例与代码块均为自撰或抽象改写。
• 结论以你所在仓库的当前事实为准。本 skill 不携带任何具体项目的隐私数据（订单号、token、用户 ID、内部地址等），全部示例均为抽象形态。