Harness Engineering 12条法则：Cassie Kozyrkov 的 AI Agent 监督与治理指南

人类：意图、优先级、验收标准、最终判断
  │
  ▼
Harness：上下文、边界、工具、计划、测试、观测与升级规则
  │
  ▼
Agent：代码、测试、文档、修复、审查响应与重复执行
  │
  ▼
机器反馈：测试结果、日志、指标、追踪、UI 状态与用户反馈

十二条法则的完整地图

从意图到上下文：谁负责什么

法则 1：人类掌舵，Agent 执行

人类负责决定做什么、为什么做、什么结果算完成，以及哪些风险不能接受。Agent 负责把这些要求拆成代码、测试、文档、CI 配置和修复动作。

当 Agent 卡住时，优先检查环境缺少什么能力：工具、文档、断言、权限还是可观测性。人类补足 Harness，Agent 继续完成代码层面的修复。失败应当推动环境变得更完整，而不是把人类重新拉回逐行编码。

法则 2：地图优先于手册

一份把所有规则、背景和例外塞在一起的超长说明，会挤占任务、代码和测试所需的上下文。入口文件的职责是提供地图：说明项目边界、列出事实来源，并指向领域文档、运行命令和验证脚本。

渐进式披露可以把上下文分成几层：短小稳定的 AGENTS.md 或项目入口、按领域拆分的文档、任务需要时才读取的参考资料。地图需要保持短、稳定、可验证；深层文档需要有清楚的路径和维护责任。

法则 3：上下文之外的知识等于不存在

架构共识如果只存在于 Slack、Google Docs 或资深工程师的记忆里，下一次 Agent 运行就无法稳定使用它。关键意图、数据 schema、目录约定、验收标准、已知限制和技术债应当进入仓库中的 Markdown、代码、配置或可执行计划，并纳入版本控制。

这条法则也适用于跨会话状态。把当前进度、已完成事项、失败原因和下一步写入文件，能让新的 Agent 在上下文重置后恢复工作，而不必猜测上一次会话发生了什么。

让代码和应用可读、可验收

法则 4：代码可读性

代码可读性面对的读者包括下一次 Agent 运行。清晰的模块边界、稳定的 API、显式的数据契约、可预测的命名和小范围变更，都比依赖隐含约定更容易被持续维护。

这不要求每一处实现都符合人类审美，但要求行为能被解释、测试能覆盖、失败能定位。复杂抽象、隐藏副作用和不透明依赖会扩大 Agent 的推理空间，增加它复用错误模式的概率。

法则 5：中央强化边界，局部允许自主

架构层、数据边界、权限、错误处理、日志格式和关键性能约束应当集中定义，并由 Lint、结构测试或 CI 机械执行。边界以内的函数拆分、局部算法和实现风格可以留给 Agent 自主选择。

这种分工把人类注意力放在少数不可妥协的不变式上，同时保留 Agent 的高吞吐量。微观管理每一行代码会变成人工瓶颈；完全放弃边界则会让代码库快速分叉。

法则 6：应用可读性

静态代码检查无法覆盖所有 UI 和运行时问题。Agent 需要能够启动隔离的应用实例，读取 DOM 或截图，查询结构化日志、指标和 traces，并通过测试或工具重现用户路径。

可读性因此是运行时属性：应用要明确告诉 Agent 发生了什么、哪个约束失败、失败发生在哪个请求或交互步骤。独立 worktree、临时观测环境和稳定的查询接口，可以把人类原本需要手动观察的 QA 工作转成机器可执行的反馈。

让长任务可恢复、可纠偏

法则 7：计划是一等公民

长任务不能只依赖对话历史。执行计划应当记录目标、范围、依赖、验收条件、当前状态、决策和已知技术债，并与代码放在同一仓库中。

计划可以驱动增量循环：Agent 每次选择一个未完成且优先级明确的功能，完成后运行验证，再更新计划状态。计划因此同时承担任务分解、跨会话交接和审计依据三种作用。

法则 8：纠偏成本低，等待成本高

当 Agent 生成速度远高于人工审阅速度时，所有改动都等待人工逐项确认，会把人变成系统的排队点。短分支、自动检查、快速重跑和小步修复通常比长时间等待一次性完美更有效。

这条法则依赖清晰的风险分层。低风险代码可以快速试错；涉及数据破坏、权限、支付、生产发布或合规的动作仍应保留硬门槛和人工确认。高吞吐不等于取消治理，而是把治理放到边界和反馈环节。

法则 9：持续垃圾回收

Agent 会复制仓库里已经存在的模式，其中也包括过时、重复或质量较差的模式。每周集中清理很容易让问题积累到难以处理；更稳定的做法是安排持续扫描，让小型重构、文档修正和规则升级尽快进入反馈循环。

垃圾回收可以检查死代码、重复工具、过期文档、架构漂移、失败重试模式和测试覆盖缺口。每次只处理可验证的小范围偏差，能降低审阅成本，也能避免新 Agent 继续学习坏模式。

把品味与技术选择写进系统

法则 10：把品味编码进系统

团队的品味通常藏在代码审查意见、重构习惯和口头约定里。只写一条“保持整洁”无法让 Agent 稳定执行；规则需要变成可检测的不变式，例如命名约束、文件大小限制、依赖方向、结构化日志或边界 schema。

Lint 的错误信息也属于 Harness。错误信息如果直接说明违反了什么、为什么不允许以及应该如何修复，Agent 就能把一次失败转成下一次执行的上下文。每次重复出现的评审意见，都值得判断是否应当提升为工具规则。

法则 11：偏好无聊且可组合的技术

这里的“无聊”指 API 稳定、文档充分、边界透明、生态成熟、容易组合的技术。它们通常拥有更丰富的训练数据和更多可参考的实现，Agent 更容易建立可靠的工作模型。

技术选型仍要服从真实约束，不能把流行度当成质量证明。选择小而透明的本地实现，有时比引入行为不可见、难以观测的第三方黑盒更容易验证；但这需要比较维护成本、安全更新和长期兼容性。

人工升级只留给判断力

法则 12：只在需要判断力时升级给人类

人工介入应集中在 Agent 无法替代的判断上：确定优先级，理解用户反馈和真实体验，定义验收标准，判断最终结果是否有价值，以及批准高风险动作。其余执行细节应尽量由 Agent 在 Harness 边界内完成。

这条法则改变了失败处理方式。发现 Bug 后，人类先判断缺少的是产品决策还是环境能力；如果只是缺少工具、测试或上下文，补齐 Harness 后仍由 Agent 编写并验证修复。

最小 Harness 的实施清单

1. 把目标写成验收标准

把一句产品愿望改写成可验证的行为、边界、输入、输出、性能和失败条件。对“做一个 dashboard”这类模糊任务，至少补充使用者、数据来源、时间范围、交互、空状态、权限和完成证据。

2. 建立短入口和深层事实来源

保留一个短小的项目入口，明确目录、启动方式、验证命令和文档索引。把架构、领域规则、设计标准和安全要求拆到可独立维护的文件中，并让入口链接到它们。

3. 把重要规则机械化

优先把依赖方向、schema、命名、文件边界、测试和安全限制放进 Lint、结构测试、CI 或运行时断言。能自动检查的规则，不要只留在评审习惯里。

4. 暴露应用状态

让 Agent 能在隔离环境中启动应用，取得日志、指标、追踪、DOM、截图和测试结果。每个反馈都应带有足够的对象、时间和失败位置，方便下一轮执行定位。

5. 外部化计划与进度

把任务清单、当前状态、决策记录、失败原因和已知技术债写入版本化文件。每次循环只推进一个可验收的小目标，并在验证后更新状态。

6. 建立持续纠偏循环

让 Agent 自检、请求独立评审、处理反馈并重复验证；同时安排周期性任务清理漂移和冗余。模型升级后重新检查 Harness，删除已经不再承担关键作用的脚手架，也补上新模型暴露出的能力缺口。

适用边界与判断标准

Harness 的价值会随着任务复杂度、持续时间、Agent 吞吐量和失败代价上升。简单的一次性脚本可能只需要明确 prompt 和基本测试；长期运行、多人协作、涉及生产数据或需要多步工具调用的系统，才更需要完整的上下文、计划、观测、权限和升级机制。

OpenAI 关于 Codex 的零人工编程实验、Anthropic 的长任务 Harness 实验，都说明环境设计会显著改变 Agent 的结果，但它们使用了特定模型、工具和仓库结构，实验数字不能直接外推到所有团队。Harness 也会带来调用成本、延迟和维护负担，必须通过真实任务和回归评测确认哪些组件仍然有用。

判断一套 Harness 是否有效，可以检查四个结果：Agent 是否能找到正确上下文，是否能在边界内执行，是否能用机器反馈发现错误，以及人类是否只在确实需要判断时被唤起。可靠性来自意图、约束、可观测性和持续纠偏的组合，而不是来自某一条更长的规则文件。