棘轮原理与实战：让 Harness 越用越可靠

系列第 5 篇 · 前置：第 1 篇 → 第 2 篇→ 第 3 篇→ 第 4 篇

前四篇讲了 Harness 是什么、Guides vs Sensors、七层解剖、Hooks 强制力。这一篇讲最后一块------Harness 怎么演进，以及一个完整的实战例子。

核心概念叫 Ratchet Principle（棘轮原理） ，来自 Addy Osmani。它解释了为什么有的人的 Agent 越用越顺，有的人的 Agent 永远在犯同样的错。

一、棘轮原理：Harness 只会收紧

棘轮是一种只能往一个方向转的齿轮------只能紧，不能松。Harness 也是这样：

erlang 复制代码

第一次失败：
  AI 删了项目外的文件 → 加了路径白名单 Hook
  → 以后永远删不了

第二次失败：
  AI 写完代码没跑测试 → 加了 PostToolUse 自动跑测试
  → 以后改完代码自动跑

第三次失败：
  AI 自己评自己说"挺好" → 拆了生成和评审两个 Agent
  → 以后永远有独立评审

...

每一次失败，Harness 紧一格。
紧到最后，Agent 想犯错都犯不了。

反面：不做棘轮的人

arduino 复制代码

AI 删了项目外的文件 → 你说"下次注意" → 下次又删了
AI 没跑测试 → 你说"记得跑测试" → 下次又忘了
AI 自己评自己 → 你说"要客观" → 下次还是假达标

→ Harness 永远是最初那个薄壳
→ Agent 永远在犯同样的错

棘轮原理的核心：每次 near-miss（差点出事）都是一次不可逆的安全积累------只增不减，只进不退。 加一条 deny 规则、更新一个 Hook、收紧一个 Skill 描述。一年后， Harness 就是所有失败的记录，也是一个把这些失败内化了的系统。

二、怎么把失败沉淀成 Harness 改进

不是所有失败都值得沉淀。判断标准：这个错会不会再犯？

复制代码

会再犯的错 → 沉淀进 Harness
  例：删项目外文件、忘跑测试、自己评自己、token 没持久化

不会再犯的错 → 不用沉淀
  例：某次网络波动导致的临时失败、一次性任务的特殊问题

沉淀的路径，按七层来：

objectivec 复制代码

失败类型 → 沉淀到哪一层
─────────────────────────
AI 不知道规矩 → Instructions（更新 CLAUDE.md / Skill）
AI 忘了之前的决策 → Knowledge（更新 progress.md / 记忆）
AI 没有合适的工具 → Tools（新增工具 / 改进描述）
AI 把环境搞坏了 → Infrastructure（加沙箱 / 限制权限）
多 Agent 协作乱 → Orchestration（改交接协议 / 角色拆分）
AI 违反硬规则 → Hooks（加 PreToolUse 拦截）
你不知道发生了什么 → Observability（加日志 / 追踪）

一个具体的例子：

objectivec 复制代码

失败：AI 改完代码没跑测试就说"做好了"
  → 这是"会再犯的错"（模型天生倾向于说自己做好了）
  → 沉淀路径：
    1. Instructions：CLAUDE.md 加"改完代码必须跑测试"（Guides）
    2. Hooks：PostToolUse 自动跑测试（Computational Sensor）
    3. Observability：记录测试结果，没跑测试标记为异常
  → 三层配合，以后不可能再"没跑测试就说做好了"

三、实战：从零搭建一个可靠的编码 Agent Harness

拿最熟的 Android 登录模块当例子，走一遍从"裸模型"到"可靠 Harness"的演进过程。

阶段 0：裸模型（什么 Harness 都没有）

erlang 复制代码

你：帮我写个登录模块
AI：写了 9 个文件
你：token 没持久化 → 改
AI：改了
你：跳转不对 → 改
AI：改了
你：密码校验呢 → 加上
...

问题：每一步都靠你指挥，Harness 是空的
失败：AI 写完不跑编译、token 用内存变量、UI 自己判断登录

阶段 1：加 Instructions（第一层）

objectivec 复制代码

写 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（第六层）

bash 复制代码

PreToolUse Hook：
  路径白名单：只允许操作 /LoginDemo 内的文件
  命令黑名单：禁止 rm -rf、禁止 sudo

PostToolUse Hook：
  改完 .kt 文件自动跑 ktlint
  改完代码自动跑 ./gradlew assembleDebug

效果：
  项目外文件删不了（强制）
  危险命令执行不了（强制）
  改完代码自动编译和 lint（强制）
残留问题：编译通过不等于做得对，AI 还是可能自己评自己说"挺好"

阶段 4：加 Orchestration（第五层）

bash 复制代码

拆成 3 个 Agent：
  生成 Agent：写代码
  测试 Agent：跑 ./gradlew test（客观验证）
  评审 Agent：对照八条标准独立检查（不相信生成者的自查）

交接协议：
  生成 → 测试：传修改的文件列表
  测试 → 评审：传测试报告
  评审 → 生成：传问题清单（位置+问题+级别）

效果：
  不再自己评自己 → 假达标概率大幅下降
  测试是客观跑的，不是 AI 说的
残留问题：长任务会忘之前的决策，出错了你不知道为什么

阶段 5：加 Knowledge + Observability（第二、七层）

scss 复制代码

Knowledge：
  progress.md 记录每轮进度和决策
  每轮更新：改了什么、为什么改、还有什么没做

Observability：
  记录每轮的输入/输出/工具调用/耗时/token
  成本计量：设置预算上限
  失败追踪：记录失败步骤和错误信息

效果：
  会话崩溃了能从 progress.md 恢复
  出了错能查日志定位
  成本超了能告警

阶段 6：棘轮收紧（持续演进）

bash 复制代码

跑了一轮，发现：
  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 是配合的：

vbnet 复制代码

Harness 解决：这一次执行怎么可靠？
  → 工具、沙箱、规则、强制力、验证

Loop 解决：多次执行怎么收敛？
  → 标准、反馈、终止条件、独立评审

配合起来：
  Harness 给 Loop 提供可靠的执行环境
  Loop 在 Harness 之上反复执行直到达标
  → Harness 是地板，Loop 是在地板上跑的发动机

用登录模块的例子：

vbnet 复制代码

Harness 层：
  路径白名单 / 自动编译 / 自动测试 / 独立评审 Agent
  → 保证"每次执行都是安全、可验证的"

Loop 层：
  八条验收标准 / 反馈带位置+证据 / 最多 5 轮 / 全达标即停
  → 保证"反复执行直到收敛"

两者配合 = 可靠的执行环境 + 明确的收敛规则 = 生产级 Agent

六、系列总结：从入门到会用的完整路径

ini 复制代码

第 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 和棘轮原理全部落到可复制的工程配置上。