Harness Engineering 入门

2026 年 2 月，Mitchell Hashimoto（HashiCorp 联合创始人，Terraform 作者）在个人博客发布了一篇博文，正式使用 “Harness Engineering” 这个术语。他在文章开篇讲了一个比喻：

"想象一匹野马。它很强壮、很快、很有潜力——但如果你不套上缰绳、笼头、马鞍，它就只能跑给你看，不能骑。

现在的 AI Agent 就是野马。模型本身已经足够强，潜力无穷。但你需要给它套上 Harness（缰绳、笼头、马鞍）——也就是 Spec（要做什么）、Boundary（边界在哪）、Verification（怎么确认做对了）——它才能真正为你工作。"

这个比喻被广泛传播，Harness Engineering 成为 2026 年 AI 编程领域最热的关键词之一。

但 Harness Engineering 不是一个新造的概念——它有清晰的思想源头、有完整的方法论、有可验证的工程实践。本章要回答的问题是：

1. Harness Engineering 是什么？
2. 它从哪里来？
3. 它怎么让 AI 从"野马"变成"坐骑"？
4. 它和"套壳 Agent"有什么区别？

---

4.2 术语溯源：Harness Engineering 的三条思想源流

Harness Engineering 不是 2026 年突然出现的术语，它有三条清晰的源流。

4.2.1 源流一：Anthropic 的"长时运行 Agent"系列（概念源头）

2025 年 11 月到 2026 年 3 月，Anthropic 先后发布三篇关键文章：

时间	文章	核心贡献
2025.11	“Effective Harnesses for Long-Running Agents”	提出 Agent 持久化、检查点、错误恢复的概念
2026.01	“Harness Design for Long-Running Apps”	系统化 Harness 的设计原则
2026.03	“Engineering Reliable Agentic Systems”	把 Harness 推广到企业级应用

Anthropic 的关注点不是"AI 写多快"，而是"AI 怎么在长时段运行中不出错"。

关键洞察：Agent 的失败不是"模型不够强"，而是"运行环境不够健壮"。

4.2.2 源流二：OpenAI 的"百万行代码"实验（命名推广）

2026 年 2 月，OpenAI 发布《Harness engineering: leveraging Codex in an agent-first world》，把 Harness 升格为完整工程方法论。

关键数据（详见 1.4.3）：

• 3 工程师 → 7 工程师
• 5 个月
• 100 万行代码
• 零手写代码
• 1500 PR
• 3.5 PR/工程师/天

OpenAI 团队的核心结论：

“我们不再写代码，我们写让代码写得对的环境。”

4.2.3 源流三：Mitchell Hashimoto 的术语命名（社区共识）

2026 年 2 月 5 日，Mitchell Hashimoto 在个人博客发布博文，正式使用 “Harness Engineering” 这一术语。他的贡献是把之前散落在各处的实践统一命名，让社区有了共同语言。

博文发布后两周，Hacker News 讨论帖冲到 286 赞、~200 评论——Harness Engineering 正式从"圈内术语"变成"行业共识"。

4.2.4 时间线

2024.07  Anthropic 内部创建 MCP
2024.11  Anthropic 开源 MCP
2025.05  Claude Code GA，Boris Cherny 开始推广 "Loop" 概念
2025.11  Anthropic 发布《Effective Harnesses for Long-Running Agents》
2026.01  Anthropic 发布《Harness Design for Long-Running Apps》
2026.02.05  Mitchell Hashimoto 博文正式命名 "Harness Engineering"
2026.02  OpenAI 发布《Harness engineering: leveraging Codex in an agent-first world》
2026.02  HN 讨论帖 286 赞
2026.03  Anthropic 发布《Engineering Reliable Agentic Systems》
2026.04  LangChain 内部实验：仅改 Harness，Terminal Bench +13.7 分
2026.05  Sequoia AI Ascent 2026，Boris Cherny 公开演讲
2026.06  Loop Engineering 概念命名，Harness/Loop 共同成为行业共识

---

4.3 Harness 的精确定义

我们给出一个被广泛引用的精确定义：

Harness 是一个为 AI Agent 设计的、可配置的、可验证的运行环境。它包括：模型可见的信息（Context）、模型必须遵守的约束（Constraint）、模型可以执行的动作（Action）、模型产物的验证机制（Verification）、以及模型行为的可观测性（Observability）。

用更简洁的话说：

Harness = AI 的"工作场"——有规则、有边界、有验证、有反馈。

4.3.1 Harness 的三大支柱

Harness 由三大支柱构成：

支柱一：Spec（规范）

Spec 定义"Agent 应该做什么、不能做什么"。

Spec 的三种形态：

形态	描述	工具
自由文本	AGENTS.md、CLAUDE.md	Anthropic、OpenAI
结构化	YAML、JSON Schema	OpenAPI、JSON Schema
形式化	状态机、TLA+、Alloy	TLA+、Alloy

支柱二：Boundary（边界）

Boundary 定义"Agent 在哪工作"。

Boundary 的类型：

类型	描述	实现
架构边界	哪些模块归 Agent 管、哪些归人管	ADR、模块所有权
文件边界	Agent 可以改哪些文件、不能动哪些	.claude/permissions.json
API 边界	Agent 可以调哪些 API、不能调哪些	沙箱 + ACL
资源边界	Agent 最多能用多少 token、多少时间	配额 + 超时

支柱三：Verification（验证）

Verification 定义"怎么确认 Agent 做得对"。

Verification 的层次：

层次	工具	验证频率	关键指标
语法层	Silent Failure Hunter、ESLint	每次提交	错误吞没率
行为层	Reality Checker、E2E 测试	每轮迭代	证据完备度
安全层	Security Reviewer、Snyk	每次部署	漏洞密度
业务层	Business Validator	每日	目标达成率

4.3.2 三大支柱的协同关系

        Spec（规范）
           ↓
   ┌────────┴────────┐
   ↓                 ↓
Context (上下文)   Boundary (边界)
   ↓                 ↓
   └────────┬────────┘
           ↓
   ┌────────┴────────┐
   ↓                 ↓
Action (执行)   Verification (验证)
   ↓                 ↓
   └────────┬────────┘
           ↓
   ┌────────┴────────┐
   ↓                 ↓
Observer (观测)  Optimizer (优化)
   └─────────────────┘

关键：三大支柱不是独立的——Spec 同时定义了 Context 和 Boundary，Verification 同时检查 Action 和 Output，Observation 同时反馈给 Spec 和 Verification。

---

4.4 OpenAI 百万行代码实验：拆解数据

第 1 章我们引用过这个实验，本章我们深入拆解。

4.4.1 实验背景

• 时间：2025.10-2026.02
• 团队：OpenAI 内部产品团队
• 任务：构建一个面向开发者的新工具（代号 “Codex 内部测试版”）
• 工具：OpenAI 自研 Codex 模型 + Harness 体系

4.4.2 关键数据

维度	数值	备注
初始团队	3 人	全栈工程师
最终团队	7 人	扩到 7 人
周期	5 个月	包含假期
代码量	~100 万行	应用 + 测试 + CI + 文档
手写代码量	0	全部由 Codex 生成
PR 数	~1500	全部由 Codex 生成
人均 PR/天	3.5	包括 review 和修正
项目周期（估算）	1/10	相对手写的 1/10

4.4.3 Harness 的具体构成

OpenAI 公开了他们使用的 Harness：

Context 层：

• 88 个 AGENTS.md 文件散布在代码库各目录
• 每个 AGENTS.md 定义该目录的编码规范、依赖关系、命名约定
• Codex 进入目录时自动加载对应 AGENTS.md

Constraint 层：

• 自定义 Lint 规则 200+ 条
• 架构约束（ADR 200+ 篇）
• 安全约束（Hook 50+ 个）
• 性能约束（benchmark 50+ 个）

Verification 层：

• 单元测试覆盖率 > 85%
• E2E 测试 100% 关键路径
• 自动审计（Codex 评审 Codex 生成的 PR）
• 形式化验证（核心模块使用 TLA+）

Orchestration 层：

• Codex 同时跑 8-12 个 worker
• 每个 worker 负责一个模块
• 主控 Codex 协调 worker 之间的接口
• Hook 自动拦截违规操作

Observability 层：

• 每个 PR 的生成时间、token 消耗、失败原因
• 每周 review harness 效果
• 自动调整 Context 和 Constraint

4.4.4 团队角色变化

阶段	工程师主要工作
1-2 周	设计 Harness 骨架
3-8 周	维护 Harness、解决边界问题
9-16 周	维护 Harness、PR review（只 review Harness 异常）
17-20 周	收尾 Harness 文档、移交维护

关键观察：工程师 80% 的时间花在维护 Harness 上，20% 用来 review 异常 PR。他们不是在"写代码"，而是在"养环境"。

---

4.5 LangChain 实验：仅改 Harness，+13.7 分

OpenAI 的实验是"全方位 Harness"，但 LangChain 在 2026 年 4 月做过一个更精妙的实验——只改 Harness，不换模型。

4.5.1 实验设计

• 工具：deepagents-cli（LangChain 内部的 AI agent CLI）
• 模型：保持 Sonnet 3.5 不变
• 任务：Terminal Bench（一个 terminal 操作 benchmark）
• 对照组：使用原版 deepagents-cli
• 实验组：使用改造版 deepagents-cli（Harness 升级）

4.5.2 改造内容

实验组对 Harness 做了 5 项改造：

1. 更严格的 System Prompt：明确每个工具的输入输出格式
2. 更细的 Tool Description：增加工具的使用示例和限制
3. 专门的 Error Recovery Prompt：失败时自动注入错误恢复指引
4. 更激进的 Context Pruning：定期压缩不相关的历史
5. 更详细的 Trajectory Logging：每一步都记录，方便回放

4.5.3 实验结果

指标	对照组（原版）	实验组（升级 Harness）	提升
Terminal Bench 得分	52.8	66.5	+13.7
任务完成率	71%	89%	+18pp
平均耗时	124s	87s	-30%
Token 消耗	1.0x	0.83x	-17%
错误恢复成功率	42%	78%	+36pp

关键发现：

• 得分 +13.7 分：相当于 Sonnet 3.5 跳到 Sonnet 4.5 的水平
• Token 消耗 -17%：好的 Harness 让 agent 更高效
• 错误恢复 +36pp：好的 Harness 让 agent 更健壮

这个实验的意义：模型不是唯一变量，Harness 本身就是产品。一个好的 Harness 能让中等模型表现得像高级模型。

---

4.6 Harness vs 套壳 Agent：本质区别

这是 2025-2026 年最容易混淆的概念。我们明确区分两者。

4.6.1 套壳 Agent（Wrapping Agent）

定义：套壳 Agent = LLM + 一个简单的 chat UI + 一些预设的 prompt 模板。

典型形态：

• ChatGPT 套壳：UI 是 ChatGPT，加上自定义角色 prompt
• 客服机器人：LLM + 知识库 RAG
• 代码助手：LLM + 代码补全 API

特点：

• LLM 是主体
• 工具是辅助
• 人是消费者
• 没有"环境"概念

4.6.2 Harness Agent（Harness Engineering Agent）

定义：Harness Agent = 完整的"运行环境"（Harness）+ LLM 作为"工人"。

典型形态：

• Claude Code：Harness 体系（CLAUDE.md + Skill + Hook + Verification）
• OpenAI Codex：Harness 体系（AGENTS.md + Lint + 自动审计）
• Trae SOLO：Harness 体系（Rules + MCP + Plan Mode）

特点：

• Harness 是主体
• LLM 是工人
• 人是设计师
• 强"环境"概念

4.6.3 对比矩阵

维度	套壳 Agent	Harness Agent
主体	LLM	Harness（LLM 是工人）
角色	Tool	Worker
工具	API 包装	Action 抽象 + 沙箱
失败处理	重新 prompt	自动回退 + 升级
状态管理	无	完整状态机
验证	人工	自动 + 形式化
适用规模	小	大
典型用户	C 端	B 端 + 高级开发者

4.6.4 经典类比

套壳 Agent = 给汽车加个方向盘（让 AI 能被人操控）
Harness Agent = 给汽车装上刹车、ABS、安全气囊、车道保持（让 AI 能在野生环境安全运行）

两者不是替代关系，而是不同时代的产品。

---

4.7 Harness 的核心思想

总结起来，Harness Engineering 的核心思想可以归纳为 4 条：

4.7.1 思想一：模型是工人，Harness 是工厂

传统观念：模型 = 产品（OpenAI/Anthropic 卖的就是模型）
Harness 观念：模型 = 工人，Harness = 工厂

关键差异：

• 工人可以换（GPT-4 → Claude → Gemini）
• 工厂不能换（你的 Harness 是项目的核心资产）
• 工人有 bug 正常，工厂有 bug 灾难

4.7.2 思想二：人设计环境，AI 在环境里工作

传统观念：人写代码，AI 辅助
Harness 观念：人设计 Harness，AI 写代码

关键差异：

• 人做的事从"写"变成"设计"
• 人的产出从"代码"变成"环境"
• 人的 ROI 从"每小时代码行数"变成"每个 PR 的质量"

4.7.3 思想三：约束是朋友，不是敌人

Vibe Coding 观念：约束 = 限制 AI 发挥
Harness 观念：约束 = 让 AI 发挥稳定

关键差异：

• 没有约束的 AI 就像"没刹车的跑车"——能跑但危险
• 有约束的 AI 就像"有刹车的跑车"——能跑且可控
• 约束不是为了压制 AI，是为了规模化 AI

4.7.4 思想四：失败是数据，不是事故

Vibe Coding 观念：AI 出错 = 事故
Harness 观念：AI 出错 = 数据

关键差异：

• Harness 把每次 AI 失败都记录成 trajectory
• trajectory 用于训练/调整 Harness
• 这是 Harness 自演化的基础（详见 HarnessX 论文）

---

4.8 一个简单的 Harness 示例

我们用一个最简化的例子展示 Harness 是什么样子。

4.8.1 场景

我们要让 Claude Code 帮我们给一个 Python Web 项目添加新功能。

4.8.2 Harness 文件结构

project/
├── AGENTS.md                 # 全局规范
├── src/
│   ├── users/
│   │   ├── AGENTS.md         # users 模块规范
│   │   └── ...
│   ├── payments/
│   │   ├── AGENTS.md         # payments 模块规范
│   │   └── ...
│   └── ...
├── .claude/
│   ├── commands/             # 自定义命令
│   │   ├── review.md
│   │   └── refactor.md
│   ├── skills/               # 自定义 skill
│   │   ├── db-migration/
│   │   │   └── SKILL.md
│   │   └── ...
│   └── hooks/                # 拦截器
│       ├── pre-commit
│       └── post-test
├── tests/
└── .harness/
    ├── config.yaml           # Harness 配置
    ├── constraints.yaml      # 约束清单
    └── verification.yaml     # 验证清单

4.8.3 关键文件示例

AGENTS.md（全局规范）：

# Project AGENTS.md

## 项目概述
本项目是 Python Web 应用，使用 FastAPI + SQLAlchemy + PostgreSQL。

## 编码规范
- 使用 Type Hints
- 异步优先（async/await）
- 数据库访问走 ORM，不写原生 SQL
- 错误处理用自定义异常类，不直接 raise Exception

## 命名约定
- 类名：PascalCase
- 函数/变量：snake_case
- 常量：UPPER_SNAKE_CASE
- 私有方法：_leading_underscore

## 必读模块
- src/core/ - 核心业务逻辑
- src/lib/ - 工具函数
- tests/ - 测试用例

## 不要做
- 不要修改 migrations/ 目录下的历史文件
- 不要修改 .env 类文件
- 不要直接连接生产数据库

.harness/config.yaml（Harness 配置）：

harness:
  name: "fastapi-web-harness"
  version: "1.2.0"
  model: "claude-opus-4-8"
  
context:
  agents_md: ["AGENTS.md", "**/AGENTS.md"]
  max_tokens: 200000
  auto_compress: true
  
constraints:
  forbidden_files:
    - "migrations/**"
    - ".env*"
    - "**/secrets.*"
  required_tests:
    - "pytest tests/unit/"
    - "pytest tests/integration/"
  lint_rules:
    - "ruff check src/"
    - "mypy src/"
  
verification:
  auto_review: true
  review_agents: ["claude-opus-4-8", "claude-sonnet-4"]
  require_coverage: 0.85
  require_types: true
  
observability:
  log_trajectory: true
  track_tokens: true
  weekly_audit: true

.claude/commands/review.md（自定义命令）：

# Review Command

调用此命令时：
1. 读取最新的 PR diff
2. 用 review_agents 中配置的模型做 review
3. 输出 review 结果到 stdout
4. 记录 trajectory 到 logs/

.claude/skills/db-migration/SKILL.md（自定义 skill）：

# DB Migration Skill

## 用途
生成安全的数据库 migration。

## 输入
- 旧 schema
- 新 schema
- 数据迁移需求

## 步骤
1. 生成 alembic migration 文件
2. 包含 up 和 down 两个方向
3. 添加单元测试
4. 验证 schema 一致性

## 限制
- 只能在 src/migrations/ 目录创建
- 不能修改历史 migration
- 必须有 down 迁移

4.8.4 工作流

当 Claude Code 在这个 Harness 中工作时：

1. 进入目录：自动加载对应 AGENTS.md
2. 生成代码：受到 constraints.yaml 中的禁止文件列表限制
3. 执行命令：所有命令通过 hooks 拦截和审计
4. 测试代码：必须跑 verification.yaml 中定义的测试
5. 提交 PR：自动调用 claude/commands/review.md 做 review
6. 记录轨迹：所有操作记录到 logs/trajectory-*.jsonl

这就是 Harness 的样子——一个为 AI 设计的工作场。

---

4.9 常见误区

4.9.1 误区一：“Harness 就是写 CLAUDE.md”

不对。CLAUDE.md 只是 Harness 的一个组件（Context Manager）。

完整 Harness 至少包括：

• ✅ Context（CLAUDE.md / AGENTS.md）
• ✅ Constraints（架构、文件、API、安全）
• ✅ Verification（测试、Lint、审计）
• ✅ Orchestration（Skill、Hook、Sub-agent）
• ✅ Observability（Trace、Token、行为画像）

只写 CLAUDE.md，不写其他组件 = 不完整的 Harness。

4.9.2 误区二：“Harness 是 OpenAI 创造的”

部分错误。

• 概念源头：Anthropic（2025.11-2026.03）
• 术语命名：Mitchell Hashimoto（2026.02.05）
• 方法论推广：OpenAI（2026.02）
• 概念升格：社区共识（2026.02-至今）

Harness Engineering 是社区共建的方法论，不是单一公司的发明。

4.9.3 误区三：“Harness 是大公司才能用的”

错误。

• 个人项目可以写 3-5 个 AGENTS.md 做最小 Harness
• 中型项目可以加 Lint + 测试 + Skill
• 大公司可以做完整 Harness 平台

门槛在"意识到 Harness 的价值"，不在"团队规模"。

4.9.4 误区四：“用 Claude Code 就有 Harness”

部分错误。

Claude Code 提供了 Harness 能力（CLAUDE.md、Skill、Hook、Sub-agent），但你需要主动配置才生效。

只用 Claude Code 不配置任何东西 = 用 Cursor 不用 .cursorrules = 没用 Harness。

---

4.10 范式对照表

维度	Vibe Coding	In-the-loop	Harness
主体	AI	人	Harness
角色	执行者	Reviewer	环境
约束	无	人的注意力	显式约束
验证	“跑起来”	人 review	自动审计
适用规模	原型	小	大
团队满意度	高（短期）	低	中高
代码质量	低	中	高

---

4.11 本章小结

Harness Engineering 是 AI 编程范式跃迁的关键。它把 AI 从"野马"变成"坐骑"——让 AI 仍然很强，但跑在你设计的缰绳里。

核心要点：

1. 术语溯源：Anthropic 概念源头 + OpenAI 方法论推广 + Mitchell Hashimoto 术语命名
2. 三大支柱：Spec + Boundary + Verification
3. 核心思想：模型是工人，Harness 是工厂；人设计环境，AI 在环境里工作
4. 关键证据：OpenAI 百万行实验 + LangChain +13.7 分实验
5. 本质区别：Harness ≠ 套壳 Agent

下一章（第 5 章）我们将深入 Harness 的五大组件——Context、约束、编排、验证、观测——并教你为项目设计第一套 Harness。

---

4.12 思考题

1. 你的项目目前有 Harness 吗？列出 3 个具体证据。
2. 如果让你设计一个最小 Harness（只包含 3 个组件），你会选哪 3 个？为什么？
3. OpenAI 实验中的 “88 个 AGENTS.md” 给你什么启发？你的项目应该有多少个 AGENTS.md？

---

4.13 参考资料

• Mitchell Hashimoto, “Harness Engineering”, 2026.02.05
• OpenAI, “Harness engineering: leveraging Codex in an agent-first world”, 2026.02
• Anthropic, “Effective Harnesses for Long-Running Agents”, 2025.11
• Anthropic, “Harness Design for Long-Running Apps”, 2026.01
• Anthropic, “Engineering Reliable Agentic Systems”, 2026.03
• LangChain, “deepagents-cli Harness Upgrade”, 2026.04
• Hacker News, “Harness Engineering” 讨论帖, 2026.02
• Rohit Raj, “What Is Harness Engineering? OpenAI’s Agent-First Codex Playbook”, 2026.06.08
• CSDN, “2026 年最火的工程范式：Harness Engineering 指南与应用”, 2026.06.15
• CSDN, “Harness Engineering：AI Agent 落地企业的工程化核心”, 2026.06.13
• HarnessX 论文, arxiv 2606.14249, 2026.06.15