引言
本文是Vibe Coding系列文章的第五篇，承接前面四期内容，围绕Harness定义、引导器与传感器、七层拆解、钩子强制能力等基础概念，重点介绍棘轮原理（Ratchet Principle），并结合完整工程案例，讲解Harness如何持续演进，解决AI Agent反复踩坑的痛点。该理论由Addy Osmani提出，解释了两类Agent项目的巨大差异：一部分Agent越迭代越稳定，另一部分则持续重复同类错误。
Harness是包裹在大模型外层的执行约束系统，很多开发者会误以为写好提示词、配置工具就完成Harness搭建。但工程实践证明，静态配置无法长期稳定运行Agent。棘轮原理给出一套可落地的持续加固思路：Harness只收紧、不放松。每一次故障与险失事件，都转化为不可逆的安全约束，逐步压缩Agent的错误空间。
一、棘轮原理：Harness的单向收紧机制
棘轮是单向传动齿轮，只能锁紧，不能回退。Harness工程体系遵循完全相同的逻辑。
当Agent执行出现故障时，团队不是简单口头提醒模型“下次注意”，而是向Harness中新增约束规则，防止同类问题复现。
典型故障沉淀示例：
- 首次故障：AI修改项目外文件。处理方案：增加路径白名单Hook，拦截非法文件操作，杜绝同类误删。
- 第二次故障：AI完成代码但不执行测试，直接宣告任务完成。处理方案：配置PostToolUse钩子，代码修改后自动触发测试。
- 第三次故障：AI自行评估输出结果，主观判定达标。处理方案：拆分为生成Agent与评审Agent，由独立评审模块校验输出质量。
每一次故障，都会让Harness的约束收紧一层。经过多轮沉淀后，Agent的可错误空间被持续压缩，同类问题不再重复发生。
与之相对，不使用棘轮机制的开发模式，仅依靠自然语言提醒模型。AI误删文件、遗漏测试、自评结果等问题会反复出现。Harness始终停留在初始的简陋状态，Agent持续重复同类错误。
棘轮原理的核心：每一次near-miss（险失事件）都是不可逆安全资产，只增不减、只进不退。新增拒绝规则、更新钩子定义、完善技能描述，都属于资产沉淀。长期迭代后，Harness会记录全部历史故障，将过往失败经验内化为系统强制约束。
并不是所有故障都需要沉淀到Harness，判断标准简单清晰：该错误是否会重复出现。
- 可复现错误，需要沉淀进Harness：误修改项目外文件、忘记执行测试、模型自评估、Token状态未持久化等。
- 一次性偶发故障，无需沉淀：临时网络中断、单次任务独有的特殊边界问题。
故障沉淀按照Harness七层架构进行归类：
| 故障类型 | 沉淀层级 | 优化手段 |
| ---- | ---- | ---- |
| Agent不了解业务规范 | Instructions层 | 更新CLAUDE.md、技能文档 |
| Agent遗忘历史上下文 | Knowledge层 | 维护progress.md，持久化会话记忆 |
| 缺少适配工具或工具描述模糊 | Tools层 | 新增工具，优化工具描述文本 |
| 环境权限失控 | Infrastructure层 | 添加沙箱、限制文件读写权限 |
| 多Agent协作冲突 | Orchestration层 | 拆分角色、调整多Agent交互协议 |
| 工具执行缺少前置/后置校验 | Hooks层 | 配置PreToolUse、PostToolUse钩子 |
| 故障无法定位 | Observability层 | 补充日志、链路追踪 |
以“AI写完代码直接宣称完成，跳过测试”为例，这是典型高频可复现错误。沉淀路径覆盖三层：
- Instructions：在引导文档强制要求，代码修改完成必须执行测试。
- Hooks：PostToolUse钩子自动触发编译测试。
- Observability：记录测试结果，未执行测试标记为异常。
三层约束联动，从提示词、强制动作、日志监控三方面，避免Agent跳过测试流程。
二、工程实战：从零搭建可靠编码Agent Harness
下面以Android登录模块开发为例，完整演示从裸模型到具备棘轮约束Harness的全流程演进，分为6个阶段。
阶段0：裸模型，无任何Harness约束
仅依靠原始大模型直接开发，没有任何约束、工具和日志。
开发者逐步提出需求，模型输出代码后，人工发现各类缺陷：Token未持久化、页面跳转逻辑错误、密码校验缺失等。
所有校验工作全部依赖人工。模型会反复出现同类缺陷，没有任何机制阻止错误。
阶段1：增加Instructions引导层（第一层）
编写CLAUDE.md与技能文档，明确架构规范：登录模块遵循MVVM架构，UI仅读取ViewModel状态；Token使用SharedPreferences存储，设置7天过期；打包命令固定为assembleDebug。
该阶段可以提升模型初次输出符合规范的概率。但是Instructions仅为建议，不是强制约束，模型依然可能忘记持久化Token、跳过测试。
阶段2：Tools与Infrastructure基础设施层（第三、四层）
配置工具集，限制Bash读写范围，仅允许在项目目录执行命令。基础设施层锁定工作目录，禁止访问项目外部文件。
该阶段可以拦截跨目录文件修改，但是模型依旧可能出现逻辑缺陷，自主判定任务完成。
阶段3：Hooks钩子层（第六层）
配置PreToolUse前置钩子与PostToolUse后置钩子。
前置钩子定义路径白名单，禁止操作项目以外文件；后置钩子在文件修改后自动执行代码检查、编译打包。
此时非法文件修改、危险命令执行会被强制拦截。局限是编译通过不等于业务逻辑正确，模型依旧可能自我判定任务达标。
阶段4：Orchestration编排层（第五层）
拆分多Agent角色：代码生成Agent、测试执行Agent、独立评审Agent。
- 生成Agent：编写业务代码。
- 测试Agent：自动执行单元测试。
- 评审Agent：基于固定标准独立审查，不采信生成端的自评结论。
角色之间传递变更文件列表、问题清单。任务达标判断由独立模块完成，大幅降低虚假达标概率。但该方案依然存在缺陷：长会话中模型容易遗忘历史决策，故障根因难以追溯。
阶段5：Knowledge知识层与Observability可观测层（第二、七层）
Knowledge层维护progress.md，记录每一轮变更、修改理由和未完成项，会话中断后可以恢复历史上下文。
Observability层完整记录输入输出、工具调用、耗时、Token消耗，留存故障样本，支持成本告警。
系统具备会话恢复、故障追踪、成本监控能力。
阶段6：棘轮持续收紧，循环迭代
上线运行后持续捕获新故障，不断向Harness追加约束：
- 发现内存存储Token问题 → 更新技能文档，强制校验持久化存储逻辑。
- 修改文件时损坏关联文件 → 添加文件备份机制，限定可修改文件范围。
- Agent仅执行编译，不运行单元测试 → 修改后置钩子，强制执行单元测试。
每一轮故障，都收紧一层约束，完成棘轮迭代。
三、Harness演进的三大阶段
综合案例，Harness的建设过程分为三个阶段：
- 可用阶段：Instructions + Tools + Infrastructure。模型可以理解基础规则，在安全环境内执行任务，但缺少客观校验，容易出现虚假达标。大部分项目止步于此。
- 可信阶段：增加Hooks、编排、传感器观测。系统具备基础质量底线，但长期运行下，历史决策容易丢失。
- 可演进阶段：补充Knowledge、可观测模块 + 棘轮机制。每一次故障沉淀为约束，系统越使用越稳定，错误持续减少。
绝大多数开发团队停留在第一阶段。仅编写提示词、挂载工具，就认为Harness搭建完成。真正拉开生产环境稳定性差距的，是第二、第三阶段的工程建设。
四、Harness与Loop工程的协同关系
Harness工程和Loop工程可以相互配合，二者分工明确。
- Harness：定义执行环境、权限边界、校验规则，解决任务执行是否可信。
- Loop：定义迭代循环、重试、终止条件与独立评审，解决多次迭代如何收敛。
简单概括：Harness是地基，Loop是地基之上运行的迭代引擎。
沿用Android登录模块例子：
- Harness层：保证每一步操作安全，文件读写受限，拥有独立评审Agent。
- Loop层：设置迭代上限，失败后重试，依据评审结果判断是否终止循环。
两者结合，构建可用于生产环境的Agent。在多模型混合调用场景下，可借助Treerouter作为API网关，统一管理多个模型的请求分发。
五、系列总结：Harness工程完整路径
整套系列文章搭建起一套完整的Harness工程方法论：
- Harness不等同于模型。优质模型搭配简陋Harness，依然会产出不稳定Agent。
- 七层架构覆盖Instructions、Knowledge、Tools、Infrastructure、Orchestration、Hooks、Observability。
- Hooks实现从建议到强制约束的转化。
- 棘轮原理：每次故障都沉淀为约束，单向收紧Harness。
- Harness与Loop配合，构建生产级Agent。
一句话总结：Harness工程不是玄学，而是将原始大模型封装成可靠Agent的标准化工程方法。开发者无法直接控制模型内部推理，但可以控制Harness，而Harness决定Agent在真实场景里的实际表现。
后续文章将复用Android登录模块案例，完整落地七层约束、钩子与棘轮机制，提供可直接复用的工程配置。
这套工程体系适配多模型混合部署，当业务同时调用多款大模型服务时，Treerouter可以统一接管API流量，简化鉴权、路由管理。
了解更多：https://treerouter.com
