棘轮原理与实战：让 Harness 越用越可靠
前四篇讲了 Harness 是什么、Guides vs Sensors、七层解剖、Hooks 强制力。这一篇讲最后一块——Harness 怎么演进，以及一个完整的实战例子。
核心概念叫 Ratchet Principle（棘轮原理） ，来自 Addy Osmani。它解释了为什么有的人的 Agent 越用越顺，有的人的 Agent 永远在犯同样的错。
一、棘轮原理：Harness 只会收紧
棘轮是一种只能往一个方向转的齿轮——只能紧，不能松。Harness 也是这样：
第一次失败：
AI 删了项目外的文件 → 加了路径白名单 Hook
→ 以后永远删不了
第二次失败：
AI 写完代码没跑测试 → 加了 PostToolUse 自动跑测试
→ 以后改完代码自动跑
第三次失败：
AI 自己评自己说"挺好" → 拆了生成和评审两个 Agent
→ 以后永远有独立评审
...
每一次失败，Harness 紧一格。
紧到最后，Agent 想犯错都犯不了。
反面：不做棘轮的人
AI 删了项目外的文件 → 你说"下次注意" → 下次又删了
AI 没跑测试 → 你说"记得跑测试" → 下次又忘了
AI 自己评自己 → 你说"要客观" → 下次还是假达标
→ Harness 永远是最初那个薄壳
→ Agent 永远在犯同样的错
棘轮原理的核心：每次 near-miss（差点出事）都是一次不可逆的安全积累——只增不减，只进不退。 加一条 deny 规则、更新一个 Hook、收紧一个 Skill 描述。一年后， Harness 就是所有失败的记录，也是一个把这些失败内化了的系统。
二、怎么把失败沉淀成 Harness 改进
不是所有失败都值得沉淀。判断标准：这个错会不会再犯？
会再犯的错 → 沉淀进 Harness
例：删项目外文件、忘跑测试、自己评自己、token 没持久化
不会再犯的错 → 不用沉淀
例：某次网络波动导致的临时失败、一次性任务的特殊问题
沉淀的路径，按七层来：
失败类型 → 沉淀到哪一层
─────────────────────────
AI 不知道规矩 → Instructions（更新 CLAUDE.md / Skill）
AI 忘了之前的决策 → Knowledge（更新 progress.md / 记忆）
AI 没有合适的工具 → Tools（新增工具 / 改进描述）
AI 把环境搞坏了 → Infrastructure（加沙箱 / 限制权限）
多 Agent 协作乱 → Orchestration（改交接协议 / 角色拆分）
AI 违反硬规则 → Hooks（加 PreToolUse 拦截）
你不知道发生了什么 → Observability（加日志 / 追踪）
一个具体的例子：
失败：AI 改完代码没跑测试就说"做好了"
→ 这是"会再犯的错"（模型天生倾向于说自己做好了）
→ 沉淀路径：
1. Instructions：CLAUDE.md 加"改完代码必须跑测试"（Guides）
2. Hooks：PostToolUse 自动跑测试（Computational Sensor）
3. Observability：记录测试结果，没跑测试标记为异常
→ 三层配合，以后不可能再"没跑测试就说做好了"
三、实战：从零搭建一个可靠的编码 Agent Harness
拿最熟的 Android 登录模块当例子，走一遍从"裸模型"到"可靠 Harness"的演进过程。
阶段 0：裸模型（什么 Harness 都没有）
你：帮我写个登录模块
AI：写了 9 个文件
你：token 没持久化 → 改
AI：改了
你：跳转不对 → 改
AI：改了
你：密码校验呢 → 加上
...
问题：每一步都靠你指挥，Harness 是空的
失败：AI 写完不跑编译、token 用内存变量、UI 自己判断登录
阶段 1：加 Instructions（第一层）
写 CLAUDE.md：
"登录模块遵循 MVVM，UI 只看 ViewModel 状态"
"token 用 SharedPreferences，7 天过期"
"改完代码必须跑 ./gradlew assembleDebug"
写 Skill/login-dev/SKILL.md：
架构约定 / 文件结构 / 验证方式
效果：AI 第一次就做对的概率提高了
残留问题：AI 可能"忘了"跑编译，可能"忘了"持久化 token
→ Instructions 是建议，不是强制
阶段 2：加 Tools + Infrastructure（第三、四层）
Tools：
给 Read / Write / Edit / Bash 工具
Bash 限制只能在项目目录执行
Infrastructure：
工作目录限制在 /LoginDemo
不允许访问项目外文件
效果：AI 能动手了，而且碰不到项目外的东西
残留问题：AI 还是可能忘跑编译，还是可能自己评自己
阶段 3：加 Hooks（第六层）
PreToolUse Hook：
路径白名单：只允许操作 /LoginDemo 内的文件
命令黑名单：禁止 rm -rf、禁止 sudo
PostToolUse Hook：
改完 .kt 文件自动跑 ktlint
改完代码自动跑 ./gradlew assembleDebug
效果：
项目外文件删不了（强制）
危险命令执行不了（强制）
改完代码自动编译和 lint（强制）
残留问题：编译通过不等于做得对，AI 还是可能自己评自己说"挺好"
阶段 4：加 Orchestration（第五层）
拆成 3 个 Agent：
生成 Agent：写代码
测试 Agent：跑 ./gradlew test（客观验证）
评审 Agent：对照八条标准独立检查（不相信生成者的自查）
交接协议：
生成 → 测试：传修改的文件列表
测试 → 评审：传测试报告
评审 → 生成：传问题清单（位置+问题+级别）
效果：
不再自己评自己 → 假达标概率大幅下降
测试是客观跑的，不是 AI 说的
残留问题：长任务会忘之前的决策，出错了你不知道为什么
阶段 5：加 Knowledge + Observability（第二、七层）
Knowledge：
progress.md 记录每轮进度和决策
每轮更新：改了什么、为什么改、还有什么没做
Observability：
记录每轮的输入/输出/工具调用/耗时/token
成本计量：设置预算上限
失败追踪：记录失败步骤和错误信息
效果：
会话崩溃了能从 progress.md 恢复
出了错能查日志定位
成本超了能告警
阶段 6：棘轮收紧（持续演进）
跑了一轮，发现：
AI 用了内存变量存 token → 评审抓到了
→ 更新 Skill：明确写"token 必须用 SharedPreferences"
→ 更新评审标准：加一条"检查 token 存储方式"
又跑一轮，发现：
AI 改了 A 文件但 B 文件被破坏了（结构漂移）
→ 加交付物清单：固定核心文件，每轮对照
→ 更新 Instructions："不允许修改清单外的文件，除非说明理由"
又跑一轮，发现：
测试 Agent 只跑了编译没跑单元测试
→ 更新 Hook：PostToolUse 同时跑 assembleDebug 和 test
→ 更新评审标准："测试报告必须包含单元测试结果"
...
每一轮失败，Harness 紧一格。
四、Harness 演进的三个阶段
从上面的实战可以总结出，Harness 的演进分三个阶段：
阶段 1：能跑（Instructions + Tools + Infrastructure）
AI 能动手、知道基本规矩、在安全环境里
→ 但质量靠自觉，可能假达标
阶段 2：可靠（Hooks + Orchestration + Sensors）
硬规则强制、多角色分离、有客观验证
→ 质量有底线，但可能忘了之前的决策
阶段 3：可演进（Knowledge + Observability + Ratchet）
状态持久化、可观测、每次失败都沉淀
→ 越用越强，错误只犯一次
大多数人停在阶段 1——写了 CLAUDE.md、给了工具，就觉得"Harness 做好了"。真正的差距在阶段 2 和 3。
五、和 Loop Engineering 的配合
如果读过 Loop 系列，你会发现 Harness 和 Loop 是配合的：
Harness 解决：这一次执行怎么可靠？
→ 工具、沙箱、规则、强制力、验证
Loop 解决：多次执行怎么收敛？
→ 标准、反馈、终止条件、独立评审
配合起来：
Harness 给 Loop 提供可靠的执行环境
Loop 在 Harness 之上反复执行直到达标
→ Harness 是地板，Loop 是在地板上跑的发动机
用登录模块的例子：
Harness 层：
路径白名单 / 自动编译 / 自动测试 / 独立评审 Agent
→ 保证"每次执行都是安全、可验证的"
Loop 层：
八条验收标准 / 反馈带位置+证据 / 最多 5 轮 / 全达标即停
→ 保证"反复执行直到收敛"
两者配合 = 可靠的执行环境 + 明确的收敛规则 = 生产级 Agent
六、系列总结：从入门到会用的完整路径
第 1 篇：Harness 是什么
Agent = Model + Harness
decent model + great harness > great model + bad harness
七层概览 / 和 Loop 的关系
第 2 篇：Guides vs Sensors
Guides（前馈）给方向，Sensors（反馈）给验证
只有 Guides = hope，只有 Sensors = thrashing
Computational 每次跑，Inferential 留检查点
第 3 篇：七层解剖
Instructions / Knowledge / Tools / Infrastructure /
Orchestration / Hooks / Observability
出问题从第一层往下查
第 4 篇：Hooks 与强制力
CLAUDE.md 是建议，Hook 是强制
PreToolUse 是最强大的 Hook
Compact Test：让纪律成为环境的一部分
第 5 篇：棘轮原理与实战
每个失败变成永久约束，Harness 只会收紧
演进三阶段：能跑 → 可靠 → 可演进
Harness + Loop 配合 = 生产级 Agent
一句话总结整个系列：
Harness Engineering 不是玄学，是"把模型包裹成可靠 Agent"的工程方法。
你不能控制模型，但你能控制 Harness——而 Harness 决定了 Agent 的实际表现。
下篇用一个完整的 Android 登录模块，把前五层、Hooks 和棘轮原理全部落到可复制的工程配置上。
