Harness Engineering 精选版

来源：《Claude Code 设计指南》与《Claude Code 和 Codex 的 Harness 设计哲学》；整理：Master

AI Agent 的可靠性，不取决于模型有多聪明，而取决于 Harness 是否把模型的不稳定性预先纳入控制面、循环、工具、权限、上下文、恢复和验证机制。

0. 总纲

模型是生产力部件，但也是最不稳定部件。成熟系统不会问“模型能不能做好”，而会问：模型说错、做错、做一半、上下文爆掉、工具失败、用户中断、多代理互相污染时，系统由谁接管？

控制面
规则来源、优先级、作用域必须显式。

循环
Query loop 是 Agent 心跳，模型调用只是其中一段。

工具
工具是受管执行接口，不是能力菜单。

恢复
错误与恢复是主路径，不是异常分支。

1. 先有控制面，再谈智能

Prompt 不是台词，是控制面。 它要定义规则来源、优先级、工具边界、输出约束、恢复行为。
本地规则不是长 prompt。 CLAUDE.md / AGENTS.md 的价值在于分层、作用域和可追踪。
用户可覆盖局部策略，但不能绕过系统结构。 好的 Agent 允许临场变化，但底层控制框架必须稳定。
控制面的关键是每条指令可定位： source、type、precedence、scope。

实践项	精选原则
规则分层	系统规则、团队规则、项目规则、临时任务规则分开。
冲突处理	明确谁优先，不能靠模型临场猜。
入口治理	入口文件要短，长内容索引到正文。
控制范围	输出风格、工具纪律、权限边界、恢复策略都应进入控制面。

2. Query Loop 才是 Agent 的心跳

真正成熟的 Agent，不是“一次 prompt → 一次回答”，而是一个持续运行的循环。这个循环治理输入、调用模型、消费流式输出、维护状态、判断停止。

没有 loop 的 Agent 只是聊天壳。
状态属于主业务，不是 UI 附属品。
停止条件不能只有“模型说完了”。完成、失败、卡住、等待用户必须分清。
中断和恢复必须是一等语义。

Claude Code 更偏向把连续性压进主循环；Codex 更偏向把连续性拆成 thread、rollout、state。两种路线不同，但都承认：连续性必须由系统拥有，不能让模型凭记忆硬扛。

3. 工具不是能力，是受管执行接口

模型说错话最多浪费时间；模型跑错命令可能破坏文件、进程、仓库和生产环境。

主题	精选判断
工具调用	一旦模型开始调用工具，问题从语言生成变成有副作用的执行系统。
权限	权限先于能力；模型能调用工具，不代表它天然被授权。
Bash	Bash 是通用逃逸口，必须有更细规则。
结果闭账	执行失败、被拒绝、被中断，都要产生可回放语义结果。

两种路线

Claude Code：像“现场值班经理”，强调运行时审批、工具编排、并发安全、中断语义。
Codex：像“制度化执行平台”，强调 tool schema、approval policy、sandbox、workdir、network、策略解析。

4. 上下文是工作内存，不是垃圾桶

长期记忆要分入口和正文：入口低成本寻址，正文高密度承载。
Session memory 不是聊天记录备份，而是继续工作的操作说明书。
Compact 不是随便摘要，而是重建一个可继续工作的后压缩世界。
上下文治理首先是预算治理：要给 summary、恢复、失败重试留空间。

保留优先级	内容
最高	当前状态、踩过的坑、已改文件、下一步动作、验证结果。
中	关键设计约束、稳定结论、必要引用。
低	重复附件、长日志全文、已过期过程性细节。

5. 错误与恢复是主路径

工程世界最不值得相信的话是“正常情况下”。Agent 一定会遇到 prompt too long、max output、工具失败、权限拒绝、网络错误、用户中断、多代理超时。

错误不是边角，错误就是主路径。
恢复的目标不是解释失败，而是继续工作。
恢复系统自己也要受治理：重试、续写、compact 都必须有次数、预算和熔断。
中断不等于失败；中断是一种合法控制流。

6. 多代理不是并行炫技，而是不确定性分区

多代理第一目的：职责分离；并行只是副产品。
实现者和验证者必须分离。
子代理要减少污染，拿精确任务和局部上下文。
父代理的稀缺能力是 synthesis：整合、取舍、验证。

7. Claude Code 与 Codex 的核心差异

维度	Claude Code	Codex
核心气质	运行时纪律、现场调度	显式控制面、制度层设防
连续性	压进 query loop	拆成 thread / rollout / state
工具治理	运行时审批、编排、中断	schema、approval policy、sandbox
适合场景	复杂长任务、动态恢复、现场执行	组织治理、审计、策略迁移
主要风险	规则可能藏在 runtime	系统较重，策略需维护

总判断：Claude Code 更信运行时纪律；Codex 更信显式控制层；两者同归于一点：模型不能裸奔，Harness 必须拥有最终秩序。

8. 团队落地路线

团队类型	建议路线	目标
个人/小团队	优先学 Claude Code：query loop、工具权限、中断、compact、恢复。	先让 Agent 在复杂任务里不失控。
中型团队	混合路线：运行时韧性 + 显式规则/工具/审批/状态。	既能跑，也能复制。
组织级平台	优先学 Codex：instruction fragment、tool schema、approval policy、state。	让 Agent 成为可治理基础设施。

9. Harness 设计检查清单

控制面

规则是否有 source/type/precedence/scope？
本地规则是否可 diff？

连续性

连续性住在哪里？
是否有 compact/truncation/recovery？

工具与审批

工具是否 schema 化？
workdir/network/sandbox/approval 是否显式？

上下文

入口是否短小？
compact 是否保留工作语义？

多代理

是否职责分离？
verifier 是否独立？

追溯

能否追踪指令、工具、审批、状态变化？
恢复动作是否可停止、可审计？

10. 最精选的十条原则

模型是最不稳定部件，不是系统主权者。
Prompt 是控制面，不是人格装修。
Query loop 才是 Agent 的心跳。
工具是受管执行接口，不是能力菜单。
权限先于能力，审批先于执行。
上下文是工作内存，不是垃圾桶。
Compact 的目标是继续工作，不是写漂亮摘要。
错误与恢复是主路径，不是异常分支。
多代理的意义是职责分离和独立验证。
团队制度比个人技巧更重要。

最后一句话

好的 AI Agent，不是让模型看起来像一个聪明同事，而是把模型放进一套足够清醒的工程秩序里：它可以犯错，但不能无限扩散；它可以调用工具，但必须被授权；它可以忘记，但系统要知道如何压缩、恢复和验证。

先有 Harness，再谈 Agent。