第 2 章 · Harness 到底是什么
本章目标：掌握 harness 的精确定义——五子系统模型，理解"仓库即规范"的核心原则，学会区分 harness 与简单提示文件。
2.1 一个被滥用的词
"Harness"这个词在 AI 编码智能体圈子里被频繁使用，但大多数时候，人们说的" harness "其实只是一个提示文件。提示文件不是 harness。
本章给 harness 一个精确、可操作的定义——不是学术抽象，而是你今天就能用到的框架。一个完整的 harness 包含五个子系统：指令、工具、环境、状态、反馈。每个子系统有明确的责任和评估标准。
2.2 从类比开始
想象你是一个新入职的工程师，被扔进一个零文档的项目。没有 README，代码里没有注释，没人告诉你怎么跑测试，CI 配置埋在某个角落。你能写出好代码吗？也许——如果你足够聪明且有耐心。但你会花大量时间"搞懂这个项目是什么"，而不是"解决问题"。
AI 智能体面临完全相同的困境，而且更糟。你至少可以问同事。智能体只能看到你放在它面前的文件和它能执行的命令。
OpenAI 将 harness 工程的核心原则表述为**"仓库即规范" (the repo IS the spec)**——所有必要的上下文应存在于仓库中，通过结构化指令文件、显式验证命令和清晰的目录结构交付。Anthropic 的长运行智能体文档强调状态持久化、显式恢复路径和结构化进度跟踪。两家公司关注不同方面，但说的是同一件事：模型权重之外的一切工程基础设施，决定了模型的多少能力能被真正实现。
看看一些你已经熟悉的工具：
Claude Code 体现了 harness 思维。它读取仓库中的 CLAUDE.md，能运行 shell 命令，在本地环境执行，维护会话历史，能运行测试看结果。但如果你不告诉它如何运行测试，它就无法验证自己做对了没有。
Cursor 遵循类似逻辑。.cursorrules 文件是它的指令源，终端是它的工具，它能读取项目结构和 lint 配置。然而 Cursor 的状态管理相对较弱——关闭 IDE 再打开，之前的上下文就没了。
Codex (OpenAI 的编码智能体) 使用 git worktree 隔离每个任务的运行时环境，配合本地可观测性栈（日志、指标、追踪），所以每个变更都在独立环境中验证。它在有 AGENTS.md 和清晰验证命令的仓库中表现 far better。
AutoGPT 是反面教材。缺乏结构化状态管理导致长任务中上下文无限累积，缺乏精确反馈机制导致智能体陷入循环。许多人说 AutoGPT "不行"，但其实是 harness 不行。
2.3 五子系统模型
┌─────────────────────────────────────────────────────┐
│ AI Agent │
└───────────────┬─────────────────────────────────────┘
│
┌───────────┼───────────┬───────────┬───────────┐
↓ ↓ ↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│指令子系统│ │工具子系统│ │环境子系统│ │状态子系统│ │反馈子系统│
│ │ │ │ │ │ │ │ │ │
│AGENTS.md│ │shell │ │deps │ │PROGRESS│ │test │
│CLAUDE.md│ │files │ │versions│ │DECISIONS│ │lint │
│rules │ │tests │ │docker │ │commits │ │check │
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘2.3.1 指令子系统 (Instructions)
创建 AGENTS.md（或 CLAUDE.md），包含：项目概述与目标、技术栈与版本、首次运行命令、不可协商的硬约束、详细文档链接。
# AGENTS.md
## 项目概述
用户偏好管理系统，FastAPI + PostgreSQL + Redis。
## 技术栈
- Python 3.11+, FastAPI 0.100+, SQLAlchemy 2.0
- PostgreSQL 15, Redis 7
- pytest, mypy --strict, ruff
## 首次运行
```bash
./init.sh硬约束
- 所有 API 端点必须经过 OAuth 2.0 认证
- 禁止使用旧版 SQLAlchemy 1.x 语法
- 新增代码必须通过 pytest 和 mypy
### 2.3.2 工具子系统 (Tools)
确保智能体有充足的工具访问权限。不要因为"安全原因"禁用 shell——如果智能体甚至不能运行 `pip install`，它怎么可能完成任务？但也不要开放一切——遵循最小权限原则。
### 2.3.3 环境子系统 (Environment)
让环境状态自描述。用 `pyproject.toml` 或 `package.json` 锁定依赖，用 `.nvmrc` 或 `.python-version` 指定运行时版本，用 Docker 或 devcontainers 让环境可复现。
### 2.3.4 状态子系统 (State)
长任务必须有进度跟踪。用一个简单的 `PROGRESS.md` 文件记录：已完成、进行中、被阻塞。每次会话结束前更新；下次会话开始时读取。
### 2.3.5 反馈子系统 (Feedback)
这是 ROI 最高的子系统。在 `AGENTS.md` 中明确列出验证命令：
```markdown
## 验证命令
- 测试：pytest tests/ -x
- 类型检查：mypy src/ --strict
- Lint：ruff check src/
- 完整验证：make check（包含以上全部）缺少五个子系统中任何一个，harness 就不完整，智能体用起来总会感觉别扭。
2.4 量化 harness 组件价值
想知道哪个组件当前最有价值？用"控制变量排除法"：保持模型不变，逐个移除五个子系统，看哪个移除导致性能下降最大。下降最大的组件对当前任务边际贡献最高，值得优先加强。
无论到是加强还是暂缓，都要先检查失败记录和归因：任务是任务不清晰？上下文不足？环境不可复现？验证反馈缺失？还是状态管理断裂？组件消融结果只能作为辅助证据。
2.5 一个真实案例
一个团队用 GPT-4o 开发 TypeScript + React 前端应用（约 20,000 行代码）。经历了四个阶段，本质上是逐个添加 harness 组件：
阶段一：README 只有基本项目描述。5 次运行中 1 次成功（20%）。主要失败：选错包管理器（npm vs yarn）、不遵循组件命名规范、无法运行测试。
阶段二：添加 AGENTS.md 指定技术栈版本、命名规范、关键架构决策。成功率升至 60%。剩余失败主要来自环境问题和缺少验证。
阶段三：添加 init.sh 标准化启动、PROGRESS.md 记录进度、明确验证命令。成功率升至 85%。
阶段四：添加 DECISIONS.md 记录设计决策、git worktree 隔离任务。成功率稳定在 95%+。
他们没换模型。他们换了 harness。
2.6 本章小结
- Harness ≠ 提示文件；是模型权重之外的一切工程基础设施
- 五子系统：指令、工具、环境、状态、反馈
- "仓库即规范"：智能体看不到的信息等于不存在
AGENTS.md应是目录页而非百科全书，约 100 行- 约束而非微观管理：用可执行规则约束智能体，而非逐一列举指令
- 量化价值：逐个移除子系统，观察性能变化
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. 根据 OpenAI 的表述，harness 工程的核心原则"the repo IS the spec"意味着什么？
2. 以下哪个工具被描述为"缺乏结构化状态管理导致上下文无限累积"的反面教材？
3. harness 五子系统中，ROI 最高的是哪个？
4. AGENTS.md 的理想长度应该是？
🛠️ 动手实践
- 分析一个你熟悉的工具（Claude Code / Cursor / Codex），找出它的五子系统分别对应什么。
- 为一个空白仓库创建最小化 harness：AGENTS.md + init.sh + 验证命令。
- 做对照实验：同一个任务，分别用"仅有 README"和"完整五子系统 harness"运行，记录成功率和上下文效率差异。