《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到造 Harness1.1 模型是马Harness 是缰绳一个被反复验证的判断“一匹千里马不管它多猛你不给它套上马具它只会四处乱跑。大语言模型就是这匹千里马。它可能已经足够聪明了但如果没有一套好的 Harness 来引导它的表现可能极其拉胯。”所谓 Harness直白点说就是模型之外、包裹模型的一切系统提示、工具描述、工具调用格式、上下文窗口管理、记忆与文件、子代理编排、权限沙箱、错误恢复、循环终止条件……所有这些非模型权重的部分。Harness 不是限制马的能力而是把强大但可能失控的力量转化为可靠、可预测、可管理的生产力。研究发现 Transformer 内部真的存在情绪向量——Happy Vector和Desperate Vector。当你骂 AI你这个笨蛋时会触发它内部的 Desperate 向量它真的就会变笨。⚠️坑 1 · 情绪化反馈会让模型真的变笨这不是段子是论文级别的发现。Harness 的反馈应该是建设性的 Verbalized Feedback而不是情绪化的责备。1.2 三代驾驭工程的演进Prompt → Context → Harness把视野放到 30 年软件工程演进的历史轴上Harness 的出现就不是偶然而是必然年份驾驭对象代表作1994对象复杂性23 种经典设计模式2002企业架构复杂性企业应用架构模式、领域驱动设计2010分布式系统微服务、消息队列、最终一致性2017数据系统数据密集型应用系统设计2026智能体不确定性系统Harness“工程师一直在跟系统的复杂度做斗争。技术架构演进二十几年不变的就是如何驾驭复杂性。”“Harness 就是把大模型的大脑变成 Agent 的身体。”Agent 工程本身也经历了三次跃迁代际时间核心隐喻局限Prompt Engineering2022-2024写好一封邮件模型一换就崩长任务会漂Context Engineering2025给邮件附上正确的附件完美上下文也防不住错误下周再犯Harness Engineering2026-设计 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 提出ACIAgent-Computer Interface概念——跟人类用的 GUI 对应Agent 需要自己专属的操作界面Stripe 的实践400 工具通过 MCP 服务器暴露但每个代理会话仅能访问其子集高风险场景下甚至从 schema 级别移除写操作工具——不是告诉代理别删数据而是让删数据的工具根本不存在 第三根缰绳控制行为流程用标准工作流程来约束模型的行为一个被广泛采用的反馈循环模式叫Ralph LoopInit 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 的 Harness2026 年 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维度内容Toolsfile I/O, shell, network, database, browserKnowledgeproduct docs, domain references, API specs, style guidesObservationgit diff, error logs, browser state, sensor dataActionCLI commands, API calls, UI interactionsPermissionssandboxing, approval workflows, trust boundaries2.3 五层洋葱架构从外到内的五层洋葱每一层都是一个独立的可替换子系统。30 顶层目录清晰对应每个 Harness 子系统目录Harness 角色src/tools/Agent 的双手40 工具src/commands/用户指令接口50 斜杠命令src/coordinator/多智能体协调src/skills/按需知识加载src/bridge/IDE 桥接层src/hooks/权限与生命周期src/components/终端 UI140 ReactInk 组件src/memdir/持久记忆src/tasks/任务系统2.4 核心组件一工具系统的 Harness 分层Claude Code 把工具按 Harness 层次精心分层这是源码分析的最大亮点工具Harness 层次BashTool行动层FileReadTool / GlobTool / GrepTool感知层FileWriteTool / FileEditTool行动层AgentTool协调层SkillTool知识层MCPTool扩展层EnterPlanModeTool / ExitPlanModeTool认知层EnterWorktreeTool / ExitWorktreeTool隔离层CronCreateTool / SleepTool调度层工具设计的三大原则原子性Atomicity每个工具只做一件事职责单一可组合性Composability输出 下一步输入自我描述性Self-DescribingZod 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子智能体隔离独立 messages[] 数组只回传摘要上下文压缩src/services/compact/自动压缩早期对话任务持久化src/tasks/ src/memdir/状态落盘跨会话恢复渐进式披露Progressive Disclosure——技能内容分三层Level 1Metadata触发描述Agent 首先看到Level 2Body主体内容按需加载Level 3References引用资料深入时加载2.6 核心组件三多智能体协调Multi-Agent HarnessClaude Code 支持六种多智能体架构模式模式适用场景通信Pipeline顺序依赖任务设计 → 前端 → 后端 → 测试上一步→下一步Fan-out/Fan-in并行独立任务多维度代码审查分发后聚合Expert Pool上下文依赖专业任务动态选专家Producer-Reviewer生成后验证内容创作 质量审核生产-审核交替Supervisor中心化动态调度Supervisor 统一调度Hierarchical Delegation复杂任务自顶向下递归拆分树状层级异步通信机制基于 JSONL 文件的异步邮箱Mailbox、Teammates 持久化、自主任务认领。Git Worktree 隔离main branch: /project/ (shared) ├── worktree-task-1/ (agent As sandbox) ├── worktree-task-2/ (agent Bs sandbox) └── worktree-task-3/ (agent Cs sandbox)2.7 核心组件四权限与 Harness 控制权限模式default每次工具调用前提示用户审批plan规划阶段只读执行阶段需审批auto自动批准低风险操作高风险仍需审批bypassPermissions跳过所有权限检查沙箱环境Anthropic 提出的 Plan-Execute-Verify (PEV) 闭环Plan as Contract规划不仅是步骤分解而是明确文件范围、预期不变量、验证命令、回滚点的契约Sandboxed Execution在隔离的文件系统、运行时与权限边界中执行Daytona、E2B、OpenHandsPermissioned State Transition多层级权限模型只读 → 沙箱编辑 → 完全访问高风险操作需 HITLDeterministic Verification通过 Linter、测试、静态分析、运行时监控等确定性传感器验证2.8 Anthropic 官方 Harness三个关键设计模式2026 年初 Anthropic 发布的Claude Managed Agents把 Harness 从概念变成产品。多家团队实测开发速度提升 10 倍从构思到交付只用了数周。开发者定义任务 / 工具 / 护栏Anthropic 基础设施负责运行内置编排 Harness 统一调度四大核心能力。Anthropic 在 Harness 设计上留下三个关键模式模式一使用 Claude 已知的工具SWE-bench VerifiedClaude 仅用2 个工具bash 文本编辑器就达到 49%bash 虽非为 Agent 设计但 Claude 深度理解并会随模型迭代改进使用能力核心理念提供 Claude 已精通的通用工具让它自己组合出解决方案模式二让 Claude 自主决策挑战假设每个工具结果都必须通过上下文窗口解法给 Claude 一个代码执行工具让 Claude 自己编写代码表达工具调用逻辑BrowseComp 基准Opus 4.6让模型过滤自己工具输出准确率45.3% → 61.6%编排决策从 harness 转移到模型本身模式三谨慎设置边界把命令字符串提升为专用工具可以拦截、控制、渲染、审计可逆性是好标准难以逆转操作外部 API需用户确认写入工具可包含过期检查防止覆盖自上次读取以来已更改的文件2.9 技术栈性能优化的工程细节类别技术运行时Bun支持 bun:bundle 死代码消除语言TypeScript (strict)终端 UIReact Ink140 组件CLICommander.jsSchema 验证Zod v4代码搜索ripgrep外部协议MCP SDK, LSP遥测OpenTelemetry gRPC特性标志GrowthBook认证OAuth 2.0, JWT, Keychain并行预取启动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 串联评测。关键发现baselineM3 在 swebench-lite 10 任务上通过率60%641K tokensv1直觉式压缩 → 通过率到 80%但 token 反而涨 11.7%架构上 PostToolUse hook 只能追加 systemMessage不是真压缩v19 突破仅一行代码ctxfTask #{n1}. Memory:{mem_count}tool outputs saved.通过率 80%token 643K基准 641K额外开销0.3%方案通过率Token 增量做法v980%17.6%注入 500 字符历史摘要v1980%0.3%一行 memory count 提示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项目 AI 代码率24.86%90.54%个人 AI 代码率14.24%87.85%四要素架构.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 阶段触发层按阶段加载对应 SkillL3 按需查询层Wiki 不主动加载Agent 自主查阅十阶段开发流程需求分析 → 需求评审 → 编码实现 → 编码评审 → 单元测试编写 → 单元测试评审 → 代码推送 → CI 验证 → 部署验证 → 用户确认每阶段三要素触发条件 / Skill 加载 / 质量门禁精确回退路径CI 0/0 → 回阶段 5编译错 → 回阶段 3评审循环上限需求评审最多 3 轮编码/测试最多 2 轮5 个 Human-in-the-Loop 确认点五条关键经验Harness 本身需要 Dry Run用虚拟需求走完全流程发现 4 个关键缺陷质量门禁必须可程序化验证“If it can’t be mechanically enforced, the agent will drift”错误示例“检查 CI 是否通过”SUCCESS 但测试 0/0 也会通过正确示例status SUCCESS total_tests 0 passed total分离执行与评判是关键杠杆评审 Agent 发现编码 Agent 遗漏的渠道判断逻辑潜在线上故障流程一致性优先于流程效率2 个文件 6 行代码的小需求也走完 10 阶段规范是活文档每条规则对应一个历史失败案例3.3 玩转 Harness 翻车清单哪些是必须哪里会翻车一位工程师在阶跃星辰 Step Plan 上用多个模型做了对照实验核心问题是同一套 Harness 配上不同模型效果差距有多大哪些 Harness 组件是必须的实验用 hero-coding 框架约 400 行 Go 代码跑简单、中等、困难三类任务测试了 step-3.5-flash 和 step-3.5-flash-2603Agent 强化版。核心发现简单和中等任务两个模型都能过但困难任务从零实现多范围解析器12 条验收标准——裸跑都失败。flash 跑了 267 次工具调用撞墙放弃实际上它已经写对了代码但不知道自己写对了继续改直到超时。加了两个简单护栏后——**工具调用上限80 次**防止死循环auto-rescue commitworker 被 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 常见失败模式速查表可贴墙上失败模式表现缓解完成幻觉报告完成但实际未完成Feature List 要求 passes 标准 强制运行验证上下文腐烂20-30 分钟后给矛盾答案60% 触发 Compaction每次迭代重新注入任务过早停止任务未完就停下Ralph Loop 拦截退出 “测试全过才停”级联错误第一步错导致后续全错关键步骤后验证门禁任务拆小上下文溢出Context length exceeded工具输出卸载、子 Agent 隔离工具误用参数错、用了不该用的工具改善工具描述、参数验证、使用示例跨会话失忆新会话重复已完成工作强制读 progress.txt范围蔓延做额外改进AGENTS.md 明确边界Feature List 划定3.6 Harness 设计 Checklist生产前必过□ 目标与边界 任务可验证 / 禁止操作已定义 / 成功标准可计算 □ 工具设计 覆盖核心场景 / Shell 后备 / 沙箱化 □ 上下文管理 渐进式披露 / 工具输出卸载 / Prompt 缓存 □ 状态管理 Progress File / Git 集成 □ 安全护栏 命令白名单 / 审批门禁 / 敏感路径限制 □ 验证循环 自动测试每次修改后运行 / 通过是下一步前提 □ 可观测性 Trace 接入 / 成本追踪 / 预算告警 □ 成本控制 模型路由 / 缓存 / 预算硬顶3.7 工程师新三大技能工程师面向 Agent 时代最需要的三项新能力约束工程Constraint Engineering不是告诉 Agent 做什么而是设计它不能做什么评估设计Evaluation Design定义什么叫做对了——可计算的成功标准、测试套件、LLM Judge 的评估维度反馈循环设计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 年每一个工程师最值得做的一次转身。