AAperture
Back/harness engineering

Harness Optimization Guide

Updated 2026-04-19
2 min read
252 words

Harness Optimization Guide

来自 @thealexker（Roo Code、DeepAgent CLI、HumanLayer 贡献者）的实战指南：三个简单操作即可让 harness 输出质量与 slop 正交分离。

核心原则

Harness 的主要工作是作为脚手架：

  1. 通过会话和压缩管理本质上无状态的 LLM 的上下文
  2. 使工具调用、I/O 处理和 guardrails 围绕模型工作

1. 保持 .md 文件精简且由人类编写

"Instruction budget" 问题：前沿 LLM 只能遵循几百条指令，之后就会进入"dumb zone"，开始遗漏相关指令。

  • ETH 研究发现：LLM 生成的系统提示词会降低性能，同时增加约 20% 的推理成本
  • 人类编写的全局系统提示词（CLAUDE.md / AGENTS.md）优于 LLM 生成的
  • 每个 token 都应该争取自己的位置，因为它会在每次会话中全局注入

Progressive Disclosure（渐进式披露）：只在需要时让 agent 拉取上下文，通过描述性文件名让它知道存在什么。

CLI 场景

像 --help 一样工作：先运行 mycli --help 发现子命令，再运行 mycli deploy --help 获取具体 flags。模型像你一样按需发现命令。

Skills 场景

Claude Code、Codex、OpenCode 的实现方式相同：启动时只加载每个 skill 的名称和描述，完整 SKILL.md 仅在 agent 判断相关时才读取。

MCP Tools 场景

Claude Code 内置 MCP 工具搜索：会话开始时加载轻量级工具名称索引，按需搜索并拉取完整 schema —— Anthropic 报告这减少 85% 以上的上下文使用。Codex 和 OpenCode 则在会话开始时加载所有配置的工具定义。

2. R.P.I 框架：在更高抽象层工作

来自 HumanLayer 的 R.P.I 框架：每次与 harness 交互时，提示词应只做以下三件事之一：

  1. Research（研究）：给 agent 问题陈述，让它探索代码库结构、先前实现、文件关系。此步骤不采取行动。
  2. Plan（规划）：agent 写逐步执行计划。人类应主动 review 和验证计划。在此步骤偷懒会在后续付出高昂代价。
  3. Implement（实现）：在可称为"主窗口"的新上下文窗口中执行已批准的计划。

如果计划很长，建议使用子 agent 各在自己的会话中执行，避免无关的中间状态污染主上下文。

3. 使用子 Agent 保持上下文清洁

核心启发式：当工作的摘要足以满足主 agent 需求时，使用子 agent。

并行扇出（Parallel Fan-out）

适合调查和研发。当告警触发时：

  1. 主 agent 研究问题，生成三个候选根因理论
  2. 为每个理论启动子 agent 同时调查
  3. 每个子 agent 独立查看日志、跟踪和指标
  4. 主 agent 获得三个摘要并综合结论，无需将数百行日志放入自己的上下文

流水线（Pipelines）

强制执行深度而非广度。将功能推过顺序角色：

  1. UX 设计师评估用户体验
  2. 架构师评估技术可行性
  3. 魔鬼代言人压力测试假设

每个阶段接收前一阶段的输出并添加分析。主 agent 获得分层、多视角的评估，无需同时在上下文中持有所有三个视角。

关键结论：Commit to One Harness

不断切换 harness 的代价：

  • 不同 harness 有不同的约束、上下文窗口策略和工具路由逻辑
  • 不断切换意味着失去编码在配置文件中的制度知识
  • 每次失败都是从零开始的 failure-case log

建议：选择覆盖团队大部分用例的 harness，将每次失败视为数据点（什么 broke、在哪一步、在什么条件下），添加到 .md 文件中并调整提示策略。

最好的 harness 是你经过定制和迭代、融入了人类工程判断的 harness。

Counterpoints & Gaps

  • 该指南偏重 Claude Code / OpenCode 生态，对其他 harness（Cursor、Cline 等）的适用性需验证
  • "只使用一个 harness" 的建议与 Jean 的多 harness 实验策略可能有张力
  • R.P.I 框架增加了规划开销，对于低风险、熟悉的代码库可能过度

Sources

Linked from