《Claude Code工程化实践》第 29 讲 Harness 架构、模式与工程实践

📌本讲摘要

本文从三个层面系统讲清楚 Harness Engineering：

① Agent Harness 革命——三根缰绳、棘轮原则、Code as Harness 学术范式。

② Claude Code 的 Harness 设计——512K 行源码、五层洋葱架构、Anthropic 三大设计模式。

③ 实践路线图——25%→90% / 60%→80% 真实数据、10 步从零到生产 Checklist、8 种失败模式速查。

学完本讲，你应该能用 Harness 思维重新审视 Agent 产品的设计选择，而不是把它当高级 Prompt 工具。

一、Agent Harness 革命：从"调 Prompt"到"造 Harness"

1.1 模型是马，Harness 是缰绳

一个被反复验证的判断：

“一匹千里马，不管它多猛，你不给它套上马具，它只会四处乱跑。大语言模型就是这匹千里马。它可能已经足够聪明了，但如果没有一套好的 Harness 来引导，它的表现可能极其拉胯。”

所谓 Harness，直白点说就是模型之外、包裹模型的一切：系统提示、工具描述、工具调用格式、上下文窗口管理、记忆与文件、子代理编排、权限沙箱、错误恢复、循环终止条件……所有这些"非模型权重"的部分。

Harness 不是限制马的能力，而是把强大但可能失控的力量，转化为可靠、可预测、可管理的生产力。

研究发现 Transformer 内部真的存在"情绪向量"——Happy Vector和Desperate Vector。当你骂 AI"你这个笨蛋"时，会触发它内部的 Desperate 向量，它真的就会变笨。

⚠️坑 1 · 情绪化反馈会让模型真的变笨

这不是段子，是论文级别的发现。Harness 的反馈应该是建设性的 Verbalized Feedback，而不是情绪化的责备。

1.2 三代驾驭工程的演进：Prompt → Context → Harness

把视野放到 30 年软件工程演进的历史轴上，Harness 的出现就不是偶然，而是必然：

“工程师一直在跟系统的复杂度做斗争。技术架构演进二十几年不变的就是如何驾驭复杂性。”

“Harness 就是把大模型的大脑变成 Agent 的身体。”

Agent 工程本身也经历了三次跃迁：

包含关系：Prompt ⊂ Context ⊂ Harness——每一代都吸收前一代，然后向上攀升。

图 1 · Harness 的本质

Harness · 运行时与基础设施，包裹模型运行的外层工程系统。

1.3 起源与扩散：一个习惯，引爆了整个行业

2026 年 2 月，在构建 AI 编码代理时，一个资深工程师形成了这样一个核心习惯：

“Every time you discover an agent has made a mistake, you take the time to engineer a solution so that it can never make that mistake again.”

他把这个实践叫做“engineering the harness”。几周之内，OpenAI、Anthropic 等机构迅速采纳。

实测数据显示：同一个模型、仅换 Harness 架构，Terminal Bench 2.0 基准得分从 42% 跃升至 78%——36 个百分点的提升，没有换模型、没有换数据、没有换提示词。

还有一条"零容忍规则"：AGENTS.md 中的每一行都应追溯到一次真实的 Agent 失败。如果指不出具体是哪次错误催生了这行规则，就删掉它。零条理想化规则。

这就是“棘轮原则（Ratchet Principle）”——Harness 只收紧，不放松。

1.4 三根缰绳：Harness 三大支柱

Harness Engineering 的三根缰绳，是这一章最有价值的部分：

🧠 第一根缰绳：控制"认知框架"

• CLAUDE.md / AGENTS.md 这些自然语言写成的规则，就是最常见的认知框架 Harness
• 模型每次开始工作前都会先"复读"这些规则
• OpenAI 的教训：一个巨大的 AGENTS.md 反而会起反效果，当所有事情都"重要"时，实际上就没有真正重要的东西
• 解决方案：把 AGENTS.md 当成"目录"，~100 行左右，具体的知识放在结构化的 docs/ 目录里
• 这叫“渐进式揭露”——先给一张地图，需要的时候再展开看细节

🔒 第二根缰绳：控制"能力边界"

• 不要把整个系统都丢给模型，而是限制它能看什么、能做什么
• SWE-agent 提出ACI（Agent-Computer Interface）概念——跟人类用的 GUI 对应，Agent 需要自己专属的"操作界面"
• Stripe 的实践：400+ 工具通过 MCP 服务器暴露，但每个代理会话仅能访问其子集；高风险场景下，甚至从 schema 级别移除写操作工具——不是告诉代理"别删数据"，而是让删数据的工具根本不存在

🔄 第三根缰绳：控制"行为流程"

• 用标准工作流程来约束模型的行为
• 一个被广泛采用的反馈循环模式叫Ralph Loop：
  Init Prompt → Output v1 → Evaluation → Feedback → Output v2 → ...
• 不让模型一次性盲猜最终答案，每次产出版本，外部评估给反馈，再基于反馈修正
• 经验同样验证了这一点：Agent 最常见的两个失败模式是"试图一步到位"和"过早宣布完工"
• 解决方案：每次只做一个功能，做完提交 git，写好进度文件，把环境打扫干净再交班

隐喻：Harness 的反馈就像“语义上的梯度下降”。传统深度学习通过数值梯度优化参数，Harness 通过自然语言反馈优化模型的输出方向。

1.5 学术化：Harness 成为独立学科

2026 年下半年，两份资料把这件事彻底学术化：

• 学术界出现的 102 页系统综述，把 Harness 拆成三层架构
• 另一份深度综述：把 Harness 定义为"战略级资产"

综述提出了一个根本性范式转移：

代码不再是 Agent 的终点输出，而是 Agent 系统的运行基座（Harness）。

代码之所以适合成为 Harness 的核心载体，因为它有自然语言不具备的三个属性：

• 可执行（Executable）：模型的意图可以变成真实操作（shell command / patch / 测试脚本）
• 可检查（Inspectable）：编译错误、runtime error、测试结果、日志都能给出客观反馈
• 有状态（Stateful）：仓库、文件系统、commit history、skill library 都能持久保存任务进度

图 · 三层架构（论文提出）

论文把 Harness 拆成自下而上紧密耦合的三层：

过去，代码是模型的考题。现在，代码正在成为 Agent 的操作系统。

二、Claude Code 的 Harness Engineering：它到底怎么设计的

Claude Code 是当下 Harness Engineering 的"工业级样板间"。它没有花哨的 UI，但它把 Harness 拆成了一个非常干净的体系。下面我们一层一层剥开它的设计。

2.1 一张图看懂 Claude Code 的 Harness

2026 年 3 月 31 日，Claude Code 的源码因 npm 包中的 source map 文件意外泄露，约1,900 个文件 / 512,000+ 行 TypeScript 代码被公开。这是工业级 Agent Harness 的活体解剖样本。

架构可以用一个极简公式概括：

Claude Code = one agent loop + tools (bash, read, write, edit, glob, grep, browser...) + on-demand skill loading + context compression + subagent spawning + task system with dependency graph + team coordination with async mailboxes + worktree isolation for parallel execution + permission governance

核心哲学：“The model is the agent. The code is the harness.”
模型决定做什么，Harness 负责执行怎么做。

2.2 Harness 的精确定义

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

2.3 五层洋葱架构

从外到内的五层洋葱：每一层都是一个独立的可替换子系统。

30+ 顶层目录清晰对应每个 Harness 子系统：

2.4 核心组件一：工具系统的 Harness 分层

Claude Code 把工具按 Harness 层次精心分层（这是源码分析的最大亮点）：

工具设计的三大原则：

1. 原子性（Atomicity）：每个工具只做一件事，职责单一
2. 可组合性（Composability）：输出 = 下一步输入
3. 自我描述性（Self-Describing）：Zod v4 Schema +延迟工具发现（Deferred Tool Discovery）——Agent 在运行时动态发现工具，不在系统提示中预加载

2.5 核心组件二：上下文管理（Context Engineering）

这是 Harness 的"内存子系统"，也是 Claude Code 最隐蔽的部分。它做了三层压缩策略：

Lead Agent (messages[]) └─ spawn SubAgent → SubAgent (fresh messages[]) └─ return summary → Lead Agent

1. 子智能体隔离：独立 messages[] 数组，只回传摘要
2. 上下文压缩（src/services/compact/）：自动压缩早期对话
3. 任务持久化（src/tasks/ + src/memdir/）：状态落盘，跨会话恢复

渐进式披露（Progressive Disclosure）——技能内容分三层：

• Level 1：Metadata（触发描述，Agent 首先看到）
• Level 2：Body（主体内容，按需加载）
• Level 3：References（引用资料，深入时加载）

2.6 核心组件三：多智能体协调（Multi-Agent Harness）

Claude Code 支持六种多智能体架构模式：

异步通信机制：基于 JSONL 文件的异步邮箱（Mailbox）、Teammates 持久化、自主任务认领。

Git Worktree 隔离：

main branch: /project/ (shared) ├── worktree-task-1/ (agent A's sandbox) ├── worktree-task-2/ (agent B's sandbox) └── worktree-task-3/ (agent C's sandbox)

2.7 核心组件四：权限与 Harness 控制

权限模式：

• default：每次工具调用前提示用户审批
• plan：规划阶段只读，执行阶段需审批
• auto：自动批准低风险操作，高风险仍需审批
• bypassPermissions：跳过所有权限检查（沙箱环境）

Anthropic 提出的 Plan-Execute-Verify (PEV) 闭环：

• Plan as Contract：规划不仅是步骤分解，而是明确文件范围、预期不变量、验证命令、回滚点的契约
• Sandboxed Execution：在隔离的文件系统、运行时与权限边界中执行（Daytona、E2B、OpenHands）
• Permissioned State Transition：多层级权限模型（只读 → 沙箱编辑 → 完全访问），高风险操作需 HITL
• Deterministic Verification：通过 Linter、测试、静态分析、运行时监控等确定性传感器验证

2.8 Anthropic 官方 Harness：三个关键设计模式

2026 年初 Anthropic 发布的Claude Managed Agents，把 Harness 从概念变成产品。多家团队实测：开发速度提升 10 倍，从构思到交付只用了数周。

开发者定义任务 / 工具 / 护栏，Anthropic 基础设施负责运行，内置编排 Harness 统一调度四大核心能力。

Anthropic 在 Harness 设计上留下三个关键模式：

模式一：使用 Claude 已知的工具

• SWE-bench Verified：Claude 仅用2 个工具（bash + 文本编辑器）就达到 49%
• bash 虽非为 Agent 设计，但 Claude 深度理解并会随模型迭代改进使用能力
• 核心理念：提供 Claude 已精通的通用工具，让它自己组合出解决方案

模式二：让 Claude 自主决策

• 挑战假设：每个工具结果都必须通过上下文窗口
• 解法：给 Claude 一个代码执行工具，让 Claude 自己编写代码表达工具调用逻辑
• BrowseComp 基准（Opus 4.6）：让模型过滤自己工具输出，准确率45.3% → 61.6%
• 编排决策从 harness 转移到模型本身

模式三：谨慎设置边界

• 把命令字符串提升为专用工具，可以拦截、控制、渲染、审计
• 可逆性是好标准：难以逆转操作（外部 API）需用户确认
• 写入工具可包含过期检查（防止覆盖自上次读取以来已更改的文件）

2.9 技术栈（性能优化的工程细节）

并行预取启动：main.tsx 模块求值前并发启动 MDM / Keychain / GrowthBook / API 预连接。

三、Claude Code 的 Harness Engineering 实践：能照搬什么

理论讲完了，聊聊怎么用上。下面三个真实案例和一份路线图，覆盖从原型到生产的完整闭环。

3.1 Karpathy Autoresearch 复现：让模型自己调优 Harness

“我做了一个很好玩的事情，让模型给自己迭代一个上下文管理的 plugin 插件……任务通过率从 60% 飙到 80%。最后最佳的方案，仅仅是一行不到 50 个字符的 prompt hooks 注入。”

这个实验用MiniMax M3（全新 MSA 注意力机制，1M 上下文，推理速度比 Flash-Sparse-Attention、FlashMoBA 快4 倍以上）自迭代 20 个方案变体、跑 25 轮 10-case 串联评测。

关键发现：

• baseline：M3 在 swebench-lite 10 任务上通过率60%，641K tokens
• v1：直觉式压缩 → 通过率到 80%，但 token 反而涨 11.7%（架构上 PostToolUse hook 只能追加 systemMessage，不是真压缩）
• v19 突破：仅一行代码

ctx=f"Task #{n+1}. Memory:{mem_count}tool outputs saved."

通过率 80%，token 643K（基准 641K），额外开销0.3%

M3 自己的解释：“Agent 不缺记忆，缺的是知道自己有记忆。”

飞轮效应：“模型越强 → 越能理解 Harness 设计空间 → 自己找到更好的 Harness → 更好的 Harness 又让它表现更强。”

3.2 阿里集团实战：AI 代码率从 24.86% 到 90.54%

阿里集团工程师在真实企业级 Java 应用（10 万+ 行，Java 1.8 / Spring Boot / LiteFlow / HSF / Diamond / Tair）中落地 Harness：

核心数据（前后对比）：

四要素架构（.harness/ 目录作为物理载体）：

.harness/ ├── agents/ # Agent 角色定义（Application Owner） ├── rules/ # 规则体系（工程结构 / 开发流程 / 编码规范） ├── skills/ # 技能体系（9 个 Skill） │ ├── request-analysis/ # 需求分析 │ ├── coding-skill/ # 编码实现（含 8 份分层 Spec） │ ├── expert-reviewer/ # 专家评审 │ ├── unit-test-write/ # 单元测试编写 │ ├── unit-test-ci/ # CI 流水线验证 │ ├── deploy-verify/ # 部署验证 │ ├── code-review/ # 代码检查 │ ├── project-analysis/ # 项目分析 │ └── aone-ci-generate/ # CI 配置生成 ├── changes/ # 变更管理（每个需求独立目录） └── mcp/ # 外部工具集成配置

上下文三层架构：

• L1 会话常驻层：Agent 定义 + 3 Rules（总量严格控制，40% 以下填充）
• L2 阶段触发层：按阶段加载对应 Skill
• L3 按需查询层：Wiki 不主动加载，Agent 自主查阅

十阶段开发流程：

需求分析 → 需求评审 → 编码实现 → 编码评审 → 单元测试编写 → 单元测试评审 → 代码推送 → CI 验证 → 部署验证 → 用户确认

• 每阶段三要素：触发条件 / Skill 加载 / 质量门禁
• 精确回退路径：CI 0/0 → 回阶段 5；编译错 → 回阶段 3
• 评审循环上限：需求评审最多 3 轮，编码/测试最多 2 轮
• 5 个 Human-in-the-Loop 确认点

五条关键经验：

1. Harness 本身需要 Dry Run：用虚拟需求走完全流程，发现 4 个关键缺陷
2. 质量门禁必须可程序化验证：“If it can’t be mechanically enforced, the agent will drift”
   • 错误示例：“检查 CI 是否通过”（SUCCESS 但测试 0/0 也会通过）
   • 正确示例：status == SUCCESS && total_tests > 0 && passed == total
3. 分离执行与评判是关键杠杆：评审 Agent 发现编码 Agent 遗漏的渠道判断逻辑（潜在线上故障）
4. 流程一致性优先于流程效率：2 个文件 6 行代码的小需求也走完 10 阶段
5. 规范是活文档：每条规则对应一个历史失败案例

3.3 玩转 Harness 翻车清单：哪些是必须，哪里会翻车

一位工程师在阶跃星辰 Step Plan 上用多个模型做了对照实验，核心问题是：同一套 Harness 配上不同模型，效果差距有多大？哪些 Harness 组件是必须的？

实验用 hero-coding 框架（约 400 行 Go 代码）跑简单、中等、困难三类任务，测试了 step-3.5-flash 和 step-3.5-flash-2603（Agent 强化版）。

核心发现：

• 简单和中等任务两个模型都能过，但困难任务（从零实现多范围解析器，12 条验收标准）——裸跑都失败。flash 跑了 267 次工具调用撞墙放弃，实际上它已经写对了代码，但不知道自己写对了，继续改直到超时。
• 加了两个简单护栏后——**工具调用上限（80 次）**防止死循环，auto-rescue commit（worker 被 kill 前自动 commit）防止成果丢失——flash 直接151 秒通过。但 Agent 强化版的 2603 反而失败，因为它的"谨慎"让每步验证就把额度用完了。
• 把 2603 切到low 推理模式，输出更短更聚焦，反而一轮通过、全场最快。好的 feedback 替代了内部推理——代码有 bug 不需要模型自己推理，harness 直接告诉它。

⚠️坑 2 · “Scaffolding is coping, not scaling”

OpenAI 这句话原意是"脚手架只是应对，不是规模化的解"。但 2603 恰好反过来——内化了太多 scaffolding 行为，在有限 budget 下反而丧失效率。Harness 不需要什么高端 trick，观察模型行为，补充让轨迹正确的操作就够了。

另外，用路由模型做"脑手分工"——强模型负责思考统筹，小模型负责快速执行——耗时减半，token 消耗降到 1/3。Scale AI 的数据也印证：Harness 对 SWE-bench 贡献 5-15 个百分点，且越来越集中在"模型无法自己做到的事"——物理约束和确定性验证。

“Harness 不是模型的拐杖，是模型的杠杆。”

3.4 10 步从零构建 Harness 路线图

适合大多数 Agent 项目的构建顺序：

从原型到生产 · 阶段式渐进落地。分四阶段 10 步，第 10 步飞轮回到第 1 步。先跑通最小闭环，再规模化。

3.5 常见失败模式速查表（可贴墙上）

3.6 Harness 设计 Checklist（生产前必过）

□ 目标与边界 任务可验证 / 禁止操作已定义 / 成功标准可计算 □ 工具设计 覆盖核心场景 / Shell 后备 / 沙箱化 □ 上下文管理 渐进式披露 / 工具输出卸载 / Prompt 缓存 □ 状态管理 Progress File / Git 集成 □ 安全护栏 命令白名单 / 审批门禁 / 敏感路径限制 □ 验证循环 自动测试每次修改后运行 / 通过是下一步前提 □ 可观测性 Trace 接入 / 成本追踪 / 预算告警 □ 成本控制 模型路由 / 缓存 / 预算硬顶

3.7 工程师新三大技能

工程师面向 Agent 时代最需要的三项新能力：

1. 约束工程（Constraint Engineering）：不是告诉 Agent 做什么，而是设计它不能做什么
2. 评估设计（Evaluation Design）：定义"什么叫做对了"——可计算的成功标准、测试套件、LLM Judge 的评估维度
3. 反馈循环设计（Feedback Loop Design）：可观测性 + 评估 → 知道下一步改什么、怎么改、改了有没有用

“这三个技能和’写好代码’的能力是互补的，不是替代。Harness 设计越好，Agent 能做的事就越多；Agent 能力越强，Harness 设计者的杠杆就越大。”

写在最后

Harness 工程化记住三件事：模型之外的一切才真正决定 Agent 生产质量——一个 70 分的模型配上精心设计的 Harness，能稳定完成复杂生产任务，95 分的模型没有 Harness 在真实工作流里依然脆弱；评估是 Harness 改进的引擎，没有评估的改进是猜测；从可运行到可生产，核心是工程纪律——Harness Engineering 不是新魔法，是把测试、可观测性、故障隔离、持续改进这些软件工程基本原则应用到 AI Agent 这个新执行环境上。投资 Harness 基础设施是最高 ROI 的决策，模型在快速变化，Harness 的价值只会增加。

AI 编码的兴起没有取代软件工程的工艺——它抬高了工艺的门槛。未来的工程竞争力不再取决于谁的 Prompt 写得更好，而是谁的 Harness 设计得更精密、更可靠、更具可演化性。开发者的核心竞争力正在从"写代码"转向"设计 Agent 的工作环境"。

一句话备忘

Harness Engineering 之于 AI Agent，正如 DevOps 之于软件部署。

Agent 现在面临的问题——上下文腐烂、工具误用、成本失控、安全漏洞、跨会话失忆——不是模型的问题，是 Harness 的问题。把工程精力从"试图编程智能"转向"为智能构建世界"，是 2026 年每一个工程师最值得做的一次转身。