CLI Agent 的 Harness 工程：当"马具"比"马"更重要

格帕文士 · 深度解读 核心结论：中等模型挂载硬性 Hook 后，工程完工度逼近最强模型无约束表现；Agent Team 的 5-10 倍 Token 冗余并非刚需。 工具栈：Claude 4.7 Opus / GLM 5.1 / DeepSeek V4 Pro | Claude Code / Cursor / Gemini CLI

一、从 Prompt 到 Harness：三代工程范式的跃迁

2023 年，所有人都在研究怎么写 Prompt。"少样本学习""思维链""角色扮演"——提示词工程是显学。

2025 年，焦点转向 Context Engineering。不是怎么说，而是喂什么。RAG、记忆系统、工具定义管理，成了核心问题。

2026 年，一个新词在工程圈迅速破圈：Harness Engineering。

这个词由 Mitchell Hashimoto 在 2026 年 2 月的博客中正式命名。Hashimoto 的核心工作习惯是：每次发现 Agent 犯错，就把永久性修复方案工程化到 Agent 的运行环境中，让该错误在结构上难以重复发生。

他把这套实践称为 "engineering the harness"。数周内，OpenAI、Anthropic 纷纷跟进扩展。

Harness 直译是"马具"——缰绳、马鞍、辔头构成的完整配件组。马凭自己的判断决定往哪里跑；马具不参与决策，它在外部管控力量如何传导、约束越界行为、防止脱轨。

核心公式由此而生：Agent = Model + Harness。

模型是那匹马，提供基础智能。Harness 是马具，把强大但可能不可控的智能转化为可靠、可预测、可管理的生产力量。

二、Harness 的四大骨架

Harness Engineering 的技术实现围绕四大机制展开，缺一不可：

约束（Constrain）：缩小可能性空间。API 边界定义、工具权限分级、架构规则强制。Stripe 的 Minion 工具通过 400 余个内部 MCP 服务器统一暴露，但每个 Agent 会话仅能访问其子集。

告知（Inform）：提供恰到好处的上下文。CLAUDE.md、AGENTS.md、SKILL.md、MCP 工具集成、RAG 文档检索。

验证（Verify）：建立确定性反馈循环。Hook 在 Agent 生命周期的特定事件中触发——文件写入后运行 linter、Agent 停止前跑测试套件。成功时静默，失败时报错。错误变成反馈信号，而非用通过测试的输出淹没上下文窗口。

纠正（Correct）：自动化修复。HumanLayer 验证过的最有效模式：每次 Agent 停止后运行类型检查，只把错误信息返回给 Agent，让其自动修复。"大概能用"和"可证明能用"之间的鸿沟，就是这样填平的。

三、实机横评：中等模型 + 硬性 Hook vs 最强模型

这是本期研究最反直觉的发现。

测试场景：真实项目的复杂长链路开发——涉及多文件重构、跨模块依赖、类型检查、测试覆盖、CI 集成。

对照组 A：Claude 4.7 Opus（最强模型），无约束单会话，无 Harness。

对照组 B：GLM 5.1 / DeepSeek V4 Pro（中等模型），挂载完整 Harness——MCP 协议 + 隔离 Subagent + 生命周期 Hook 兜底范式。

结果：

中等模型在挂载硬性 Hook 后的工程完工度，逼近甚至超过强模型在无约束单会话下的表现。

原因不在模型能力本身，而在确定性的边界约束：

• 类型检查 Hook：每次文件写入后自动运行 TypeScript 编译。Opus 单会话可能写出"大概对"的代码，中等模型 + Hook 写出"编译通过"的代码。
• 测试覆盖 Hook：Agent 停止前跑测试套件，覆盖率下降则阻塞完成。中等模型被迫在每一步都通过测试，而非事后补救。
• 循环检测 Hook：同一文件编辑 3 次以上自动告警，防止 Agent 在局部最优解中无限震荡。
• Subagent 隔离：复杂任务拆给独立子代理，父会话只接收压缩结果。中等模型在隔离的小上下文中表现稳定，避免了长上下文带来的性能衰减。

这一发现直接验证了一个工程直觉：智能不够，工程来凑。当模型能力存在差距时，Harness 的硬性约束可以把"大概能做"变成"确定能做"。差距不是无限可补的——对于需要深层推理的创造性任务，Opus 仍有不可替代的优势——但在工程交付的确定性上，Harness 的杠杆效应惊人。

四、MCP + Subagent + Hook：组合范式的工程实践

MCP：统一工具接口

MCP（Model Context Protocol）正在统一工具暴露的接口规范。Stripe 的 Toolshed 系统集成 400+ 内部工具，Codex CLI、Claude Code、Cursor、Gemini CLI 均兼容。

关键设计：选择性连接。仅连接必要系统，避免工具描述膨胀淹没上下文窗口。一个附带 6 个示例命令的自定义 CLI，在实践中比一个完整的 MCP 服务器表现更好。

Subagent：上下文的防火墙

Chroma 的研究表明：模型性能随上下文长度增长而下降，当问题与相关上下文之间的语义相似度低时，下降更为陡峭。

Subagent 从结构层面解决这一问题。每个 Subagent 获得一个全新的、小的、高相关性的上下文窗口。父 Agent 只接收压缩后的结果——中间的工具调用、grep 输出、文件读取全部隔离在 Subagent 内部。

成本结构随之调整：父会话使用高推理模型负责编排与规划，每个 Subagent 的隔离任务则用更便宜、更快的模型执行。

Hook：生命周期兜底

Hook 是 Harness 中最被低估的组件。它不是锦上添花，而是底线保险。

Claude Code 的 Hook 系统支持 session、prompt、tool-use、permission、compaction、stop、subagent 等生命周期事件。Codex CLI 支持 SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、Stop。

最有效的三类 Hook：

1. Pre-commit Hook：文件写入后运行 biome + typecheck。成功静默，失败报错，Agent 自动修复。
2. Coverage Hook：Agent 停止前检查测试覆盖率。低于阈值则阻塞完成，Agent 必须补齐。
3. Loop Detection：同一文件 3 次以上编辑触发告警，防止震荡。

这三类 Hook 的组合，构成了工程完工度的"硬性底线"。无论模型多聪明或多笨，通过这些 Hook 的代码至少是"编译通过、测试通过、不震荡"的。

五、Agent Team：5-10 倍 Token 冗余的陷阱

Claude Code 在 2026 年 2 月推出了 Agent Teams 实验性功能——多代理并行协作。16 个 Opus 实例花了两周、烧了 20 万美元 API 费用，写出一个能编译 Linux 6.9 内核的 C 编译器。Proof of concept impressive。

但本期研究的另一个核心发现是：Agent Team 在实际开发中存在极高的 Token 冗余，且并非刚需。

Token 成本：

• 单会话：1x 基线
• Subagent：1.5-2x
• Agent Team：3-7x（Plan 模式下最高 7 倍）

实测数据（基于 2026 年 3 月各工具基准）：

• 5 人 Agent Team 约 5 倍 token 消耗
• 复杂调试场景：单会话 50 万 token vs Agent Team 95 万 token（1.9x）
• 全栈功能开发：单会话 40-60 万 token vs Agent Team 135 万 token（2.5-3x）
• 实际项目中，包含 MCP 工具元数据开销后，总冗余可达 5-10 倍

为什么冗余这么高？

1. 每个 teammate 是独立实例：各自维护完整上下文窗口，token 消耗随人数线性增长。
2. 协调开销：Mailbox 消息、Task List 同步、依赖检查——这些 coordination 本身就在烧 token。
3. MCP 工具元数据膨胀：每个实例都加载工具 schema，40-50% 的上下文被工具描述占据。
4. Plan 模式：多轮规划对话进一步放大消耗。

什么时候该用 Agent Team？

只有在 teammates 真正需要 peer-to-peer 通信时才值得。前端开发者需要知道后端 API 的形状，测试需要知道两边的契约——这种跨层协调是 Agent Team 的 sweet spot。

如果只是独立并行任务——跑测试、搜代码、生成文档——Subagent 更优。1.5-2x 的成本，没有协调噪音。

本期研究的核心结论是：对于大多数工程任务，Subagent 隔离 + Hook 兜底的单会话模式，已经足够了。Agent Team 的 5-10 倍 token 冗余在多数场景下是过度工程。

六、选型矩阵：2026 年 CLI Agent 怎么选

基于本期横评和各工具 2026 年的最新能力：

一个经过验证的高效组合：

日常 IDE 编码      → Cursor（Tab 补全 + 视觉反馈）
复杂重构/深度任务  → Claude Code（最强质量 + Agent Teams 备选）
大仓库探索        → Gemini CLI（1M 上下文 + 免费）
CI/CD 自动化      → Codex CLI / Copilot CLI

2026 年平均每位开发者使用 2.3 个 AI 编码工具。不同工具的优势互补，远比单押一个更高效。

七、一个最小但非平凡的 Harness 配置

以下是一个 TypeScript monorepo 的最小 Harness 设置清单，可直接落地：

Prompt 层

• AGENTS.md 不超过 60 行，只保留对每个任务普遍适用的约束
• SKILL.md 按需加载，过早加载不适用的指令会产生负面效果
• 输出格式约束为结构化响应

Context 层

• MCP 服务器：同时只激活 2-3 个，关掉其余的
• 记忆：对话缓冲 + 结构化长期规则存储
• 把 git 当作 Agent 的原生记忆——小而语义明确的提交是 Harness 层面的卫生习惯

Harness 层

• Pre-commit hook：biome + typecheck，成功静默，失败报错
• PostToolUse hook：每次文件写入后 surface linter 错误
• Stop hook：运行变更的测试文件，返回错误
• Coverage hook：覆盖率下降则告警
• Loop detection：同一文件编辑 3+ 次触发告警
• Sub-agent 模式：研究、代码库追踪、QA 三种场景定义好
• Escalation rule：阻塞 3+ 个 tool call 则停止并询问

结语

本期研究的核心洞见可以浓缩为一句话：Harness 不是模型的补充，而是模型的翻译器——把强大但不可控的智能，翻译成可靠、可预测、可交付的工程产出。

"智能不够，工程来凑"听起来像退而求其次，实则是工程思维的胜利。OpenAI 用 Agent 写了 100 万行生产代码，零人工直接编写。3 人工程师团队的核心职责不是写代码，而是设计 Agent 工作的环境和结构——Harness。

Agent Team 的 5-10 倍 token 冗余是一个警示：多代理不是银弹，Subagent 隔离 + Hook 兜底在多数场景下更务实。

2026 年的 CLI Agent 格局，最让人兴奋的不是某一款工具有多强，而是 Harness 正在成为跨工具的通用语言——CLAUDE.md、AGENTS.md、SKILL.md、MCP 协议，这些基础设施让模型切换的成本趋近于零。

选工具的核心逻辑：不要追求"最好的"，要追求"最适合你当前任务的"。最佳实践是选 2-3 款工具组合使用，每款发挥它最擅长的维度——然后用 Harness 把它们串成可靠的工程流水线。

马跑得再快，没有马具就拉不了车。Agent 再聪明，没有 Harness 就进不了生产环境。

参考来源：

• Mitchell Hashimoto, "Engineering the Harness" (2026.02)
• OpenAI Codex: 1M lines of production code by agents (2026.02)
• Anthropic Claude Code Agent Teams Documentation
• AI Harness Engineering Compatibility Matrix (Cody Lindley, 2026.05)
• Prompt、Context、Harness：AI Agent 工程的三层架构解析 (QQ News, 2026.04)
• AI Agent 时代的系统约束、反馈回路与工程范式 (Flashcat, 2026.04)
• 2026年AI编码CLI工具终极对比 (掘金/segmentfault, 2026.04)
• Garden Skills: https://github.com/ConardLi/garden-skills/
• Claude Code: https://code.claude.com/docs/zh-CN/overview

#Agent #Harness #CLI #MCP #Hook #工程范式 #深度解读 #格帕文士