📚 喵喵的笔记库

01-Harness是什么

22分钟阅读

Harness 是什么

Agent = Model + Harness。Harness 不是框架，是让模型能力变得有用的操作系统。 下一步 → 02-核心架构

🧠 我的心智模型

Harness 的比喻：

(用你自己的话，描述 Harness 是什么) ✍️ 你的理解：

[来源：OpenAI] OpenAI 的定义更直白：人类掌舵，智能体执行。在这个范式下，工程师的角色发生了根本转变——从写代码变为三件事：设计环境（让 Agent 知道在什么上下文里工作）、明确意图（把模糊需求转化为可执行规格）、构建反馈回路（让 Agent 能自我验证和纠错）。Harness 就是这三件事的工程化产物。

[来源：LangChain/Vivek Trivedy] Vivek Trivedy 的核心公式简洁有力：Agent = Model + Harness。如果你不是模型，你就是 harness。这意味着我们作为工程师的全部工作，都是在 harness 层面——优化模型周边的一切，让模型的能力真正有用。

三次范式跃迁：

(Prompt Engineering → Context Engineering → Harness Engineering，每次跃迁解决了什么问题？) ✍️ 你的理解：

[来源：Externalization 论文] Externalization 论文提供了一个更深层的历史演进框架：Weights → Context → Harness。早期 AI 能力锁定在模型权重里（Weights 阶段），后来发现通过精心构造上下文能大幅提升表现（Context 阶段），再后来发现需要系统性的工程化设施来持续、可靠地管理这些上下文（Harness 阶段）。每次跃迁不是否定前一个，而是在其基础上叠加——Harness 包含 Context Engineering，Context Engineering 包含 Prompt Engineering。

Agent = Model + Harness：

(如果你不是模型，你就是 Harness 的一部分。—— Vivek Trivedy) ✍️ 你的理解：

[来源：O'Reilly/Addy Osmani] Addy Osmani 提出了"棘轮原则"（Ratchet Principle）：每个错误变成规则。当你发现 Agent 犯了一个错，你不应该手动修一次就完了，而是把它工程化成一条规则，让 Agent 永远不再犯同样的错。这意味着 Harness 是你的失败历史塑造的——它凝结了你踩过的所有坑。这也是为什么 Harness "下载不来"：别人的失败历史和你不一样，通用的 Harness 只能覆盖通用问题。

🎯 核心问题

  1. Harness 和传统框架（LangChain/CrewAI）有什么本质区别？为什么要独立研究它？
  2. "模型几乎无关紧要，Harness 就是一切"这个说法对吗？极端了还是真有道理？
  3. Stripe 400+ 工具的 Minions 和 OpenAI 百万行零人工实验，共同的设计哲学是什么？
  4. Claude Code 源码泄露的 12 种 Harness 设计模式，哪些你已经在用？

📝 我的理解

Harness 的定义

✍️

[来源：Terminal Bench 2.0] Terminal Bench 2.0 的数据提供了最直观的证据：同一模型（Opus 4.6），仅换 harness，排名从 Top 30 飙升到 Top 5。这个实验完美回答了"模型重要还是 harness 重要"的问题——模型决定了天花板在哪，但 harness 决定了你能离天花板多近。同一个模型，在不同 harness 的加持下，表现可以差出一个数量级。

从 Prompt 到 Context 到 Harness

✍️

三次跃迁的核心驱动力：Prompt Engineering 解决了"怎么说模型才听懂"的问题，但单轮优化无法应对复杂任务。Context Engineering 把视野扩大到整个上下文窗口的管理，但仍然缺乏系统性的工程方法。Harness Engineering 最终把所有这些——提示词、工具、编排、记忆、反馈——统一成一个可工程化、可迭代、可积累的系统。

核心案例对比

✍️

⚡ 我的实战

✍️ 我自己做过什么、踩过什么坑。

🔒 关书自测

  1. Agent = Model + Harness，请分别解释每一层的职责。如果去掉 Harness 层会怎样？
  2. Harness 的四大杠杆分别是什么？各举一个使用场景。
  3. Stripe Minions 的"反馈左移"策略核心思想是什么？为什么最多两轮 CI？
  4. OpenAI 的"架构即护栏"和"工具即反馈"，在你的项目中能怎么落地？

🎤 费曼输出

1 句话版本:✍️ 3 分钟版本:✍️ 信心:_/10 最可能翻车的地方:✍️

参考资料

核心定义

Agent = Model + Harness — Vivek Trivedy (2025) 首创 Harness Engineering 术语。Mitchell Hashimoto（Terraform/Ghostty 创建者）2026年2月正式命名：

"每当你发现 Agent 犯了一个错误，你就花时间工程化一个解决方案，使 Agent 永远不再犯同样的错误。"

核心问题：不是"如何让模型更聪明"，而是"如何从今天的模型中获得最大收益"。

Harness 的本质

词源与比喻："Harness"原意是马具——缰绳、鞍具、嚼子——用来驾驭一匹强大但不可预测的动物。

  • 马 = AI 模型：强大、快速，但自己不知道该往哪里走
  • 马具 = Harness：引导、约束、使力量变得可控且有方向

技术定义：Harness 是除模型本身以外的所有代码、配置和执行逻辑。包括：

  • 系统提示（System Prompt / AGENTS.md）
  • 工具、Skills、MCP 及其描述
  • 捆绑基础设施（文件系统、沙箱、浏览器）
  • 编排逻辑（Sub-agent 生成、任务交接、模型路由）
  • Hooks / 中间件（上下文压缩、续行、lint 检查等确定性执行逻辑）

类比理解：Harness 就像操作系统。模型（大体上）接受文本输入并输出文本，仅此而已。开箱即用，它们无法做到：跨交互维护持久状态、执行代码、访问实时知识、搭建环境。这些都是 Harness 层面的特性。

三次范式跃迁

  1. Prompt Engineering（2023）→ 如何写好提示词
  2. Context Engineering（2024, Dex @ 12-factor agents）→ 系统性提升 AI agent 可靠性的技术超集
  3. Harness Engineering（2025-2026, Vivek Trivedy）→ Context Engineering 的子集，专注于利用 Harness 配置点来管理编程 Agent 的上下文窗口

范式转移的底层趋势：

  • 模型商品化：Claude/GPT/Gemini 基准测试表现接近，竞争优势不再是模型本身
  • Agent 从 Demo 走向生产：可靠性标准从"令人印象深刻的 Demo"变成"不能宕机"
  • 基准测试不再衡量真正重要的东西：标准基准衡量单轮任务完成率，但生产 Agent 运行数小时甚至数天

四大杠杆 + 两个补充

来源：Vivek Trivedy 四大核心杠杆，HumanLayer 团队补充两个。

| 杠杆 | 核心作用 | 关键洞见 | |------|---------|---------| | 系统提示 | 最直接的配置点 | AGENTS.md 当目录不当百科全书，上下文是稀缺资源 | | 工具/MCP | Agent 与外部世界交互 | 工具不仅扩展能力，更是反馈机制——自定义 linter 错误消息同时充当修复指令 | | 上下文 | 给 Agent 足够好的输入 | 把关键上下文放系统提示，其他放 Markdown 文件按需加载 | | Sub-agents | 最被低估的杠杆 | 上下文防火墙——离散任务在隔离的上下文窗口中运行 | | Hooks（补充） | 确定性控制流 | 成功时静默（零上下文开销），失败时只暴露错误信息 | | Skills（补充） | 渐进式知识披露 | 不在启动时加载所有指令，按需加载相关知识模块 |

Stripe Minions：400+ 工具的无人值守 Agent

背景：数亿行 Ruby 代码库，每年处理超 1 万亿美元支付。每周 1,300+ PR 合并。

五层核心架构：

| 层次 | 组件 | 核心技术 | |------|------|---------| | 第一层 | 触发 | Slack、CLI、Web UI、工单系统 | | 第二层 | 执行沙箱（Devboxes） | AWS EC2 预热池，10 秒启动，QA 隔离 | | 第三层 | Agent 核心 | Block 开源 Goose 的深度定制 fork | | 第四层 | 蓝图编排 | 确定性节点 + Agent 循环节点的混合工作流 | | 第五层 | Toolshed（~500 MCP 工具） | 集中式 MCP 服务器，目录范围规则文件 |

核心设计哲学：

  • 反馈左移：Pre-push hooks（<1秒）→ 本地 Linting（<5秒）→ CI 选择性测试 → 最多两轮 CI
  • 蓝图（Blueprints）：确定性代码节点与自由流动的 Agent 子任务的混合编排——linter 总是要运行的，分支总是要按特定方式推送的
  • Agent 需要与人类工程师相同的上下文和工具：Toolshed ~500 工具，人类和 Agent 共用同一套。规则文件跨 Cursor/Claude Code/Minions 三系统同步
  • "把 LLM 放入有围墙的盒子里，积累起来就产生了系统级的可靠性收益。模型不运行系统，系统运行模型。"

OpenAI：百万行代码零人工实验

背景：3-7 人团队，5 个月，~100 万行代码，1500+ PR，零行人工编写代码。

六大核心经验：

  1. AGENTS.md 是目录，不是百科全书 — 短小入口（~100行），知识库放结构化 docs/ 目录
  2. 一切为 agent 可读性优化 — Agent 运行时看不到的东西 = 不存在
  3. 刚性架构约束是前提 — 每个业务域固定分层，依赖方向严格校验，自定义 linter 机械强制
  4. 让 agent 能自己验证自己 — 浏览器自动化 + 可观测性 stack + 录视频验证
  5. 端到端自主驱动 — 一个 prompt 完整执行：验证→复现→修复→验证→开PR→响应review
  6. "AI Slop" 垃圾回收 — Golden Principles 一次编码，持续在每行代码上强制执行

架构即护栏的深层洞见：

  • 人类开发者对过于严格的架构约束感到不适，但 Agent 没有"审美偏好"
  • 严格的架构规则在 Agent 手中变成巨大的优势——不会偷懒绕过规则
  • 反直觉：提高 AI 代码信任和可靠性，需要缩小解决方案空间而非扩大它

工具即反馈的精妙设计：

  • 传统 linter 错误消息面向人类（需要经验推断修复方式）
  • Agent 优化的 linter 错误消息包含：VIOLATION 说明 + FIX 步骤 + EXAMPLE 示例 + REFERENCE 文档链接
  • 创造零人工干预的紧密反馈回路：Agent 写代码 → Linter 发现违规 → 错误消息=修复指令 → Agent 按指令修复 → 通过

Claude Code 源码的 12 种 Harness 设计模式

来源：Claude Code 泄露源码解读，分为四类：

Memory & Context（5 种）：

  1. 持久化指令文件模式 — AGENTS.md/CLAUDE.md 跟着仓库走
  2. 作用域上下文组装模式 — 从组织级到子目录，动态加载
  3. 分层记忆模式 — 紧凑索引 + 主题文件 + 完整记录
  4. 梦境整合模式 — 空闲时间垃圾回收，去重修剪
  5. 渐进式上下文压缩 — HISTORY_SNIP → Microcompact → CONTEXT_COLLAPSE → Autocompact

Workflow & Orchestration（3 种）： 6. 探索-计划-执行循环 — 读权限 → 讨论方案 → 完整工具权限 7. 上下文隔离子 Agent — 研究/计划/编辑各自独立上下文 8. Fork-Join 并行 — Git worktree 隔离，合并结果

Tools & Permissions（3 种）： 9. 渐进式工具扩展 — 默认 <20 个工具，按需激活 10. 命令风险分类 — 确定性预解析 + 按工具权限门控 11. 单用途工具设计 — FileReadTool/FileEditTool/GrepTool 替代通用 shell

Automation（1 种）： 12. 确定性生命周期钩子 — 25+ 个钩子点（PreToolUse/PostToolUse/SessionStart/CwdChanged）

Anthropic Harness 实践三篇

1. Effective harnesses for long-running agents（2025.11）

  • 两阶段架构：Initializer Agent（设置环境 + 展开需求为 feature list）→ Coding Agent（增量执行 + 干净交接）
  • 四大失败模式：过早宣布完成、环境留 bug、提前标记完成、不会启动 app
  • 关键洞察：Feature list 是核心，浏览器自动化测试是必须的

2. Harness design for long-running application development（2026.03）

  • 灵感来自 GAN — Generator 和 Evaluator 分离
  • 三 Agent 架构：Planner → Generator → Evaluator（Playwright MCP 像用户一样点页面）
  • Sprint Contract 机制：spec 高层，contract 填补到可测试粒度
  • 发现：Claude 默认是个差 QA，Evaluator 不是必需品（当任务在模型能力边界内时）

3. Building a C compiler with parallel Claudes（2026.02）

  • 16 个 Claude 并行写 10 万行 Rust C 编译器
  • Ralph Wiggum Loop：while true; do claude ... done
  • 关键经验：测试质量决定一切、为 Claude 设计（不打印大量输出）、Agent 角色专精

控制论框架（Birgitta Böckeler / Martin Fowler）

三层同心圆：

  • 最内层：模型——被套上 Harness 的对象
  • 中间层：构建者 Harness——Agent 产品内置的系统提示、编排、检索
  • 最外层：用户 Harness——我们针对自身用例构建的外部 Harness

前馈 vs 反馈：

  • 前馈（指引）：预测 Agent 行为，力求在行动前引导——提高首次成功率
  • 反馈（传感器）：行动后观察，帮助自我纠正——当传感器产生针对 LLM 消费优化的信号时尤其强大

三种监管类别：

  • 可维护性 Harness — 内部代码质量（最容易实现）
  • 架构适应性 Harness — 应用架构特性（Fitness Functions）
  • 行为 Harness — 应用按需运作（最具挑战性）

实践的 Do's 和 Don'ts

有效的做法：

  • 偏向交付，只在 Agent 实际失败时才添加配置
  • 设计、测试、迭代——并丢弃无用的东西
  • 优化迭代速度，而非"第一次尝试就一击即中的概率"
  • 给 Agent 一套能力后仔细削减暴露给模型的内容

无效的做法：

  • 在还没遇到真实失败之前就试图设计理想的 Harness 配置
  • 以"以防万一"的心态安装几十个 Skills 和 MCP Servers
  • 在每个 Agent 会话结束时运行完整的测试套件（超过 5 分钟）
  • 试图微观优化哪些 Sub-agents 可以访问哪些工具

关键文献时间线

| # | 时间 | 作者/来源 | 标题 | 定位 | |---|------|---------|------|------| | 1 | 2025.09 | Viv | Claude Code SDK 与 HaaS 的诞生 | 定义起点·4 杠杆 | | 2 | 2026.02 | Mitchell Hashimoto | 我的 AI 采纳之旅 | 术语命名·个人路径 | | 3 | 2026.02 | Stripe | Minions Part 1 & 2 | 企业实战·架构设计 | | 4 | 2026.02 | OpenAI | Harness Engineering | 百万行零人工实验 | | 5 | 2026.02 | Charlie Guo | Harness Engineering 实践手册 | 跨组织规律综合 | | 6 | 2026.03 | Viv · LangChain | Agent Harness 的解剖 | 理论推导·从缺陷反推 | | 7 | 2026.03 | HumanLayer | 技能问题 | 战术工具箱 | | 8 | 2026.04 | Martin Fowler / Birgitta | 面向编程 Agent 用户的 HE | 控制论框架升华 |

本文综合自 Vivek Trivedy、Mitchell Hashimoto、Stripe、OpenAI、Charlie Guo、HumanLayer、Birgitta Böckeler 等多方来源。

英文原始资料

Anthropic 官方 Engineering Blog

OpenAI 官方

Google 官方

权威第三方

行业综合分析

学术

关系图谱

反向链接