Harness 是围绕 AI agent 搭建的可执行工作环境，用来提供上下文、限制边界、赋予工具、保存状态、收集反馈、验证结果，并决定 agent 什么时候可以继续或停止。
如果说模型是“脑”，harness 就是“工作台、规章、仪表盘、质检线和安全围栏”。Prompt 只是 harness 的一部分，而且通常不是最重要的部分。
它不是什么
| 常见误解 | 更准确的理解 |
|---|---|
| Harness 等于 prompt engineering | Prompt 只负责表达意图。Harness 还包括工具、状态、验证、环境、权限和可观测性。 |
| Harness 等于 agent framework | Framework 提供开发抽象，harness 是围绕具体任务和仓库设计的执行系统。 |
| Harness 等于测试脚本 | 测试是反馈子系统的一部分。Harness 还要解决任务入口、上下文、状态、运行环境、错误恢复。 |
| Harness 等于自动化脚本 | 自动化脚本通常执行固定流程，harness 允许 agent 在边界内自主选择路径。 |
一个完整 harness 的组成
综合 WalkingLabs 课程、deusyu 中文学习档案、OpenAI 与 Anthropic 文章，可以把 harness 拆成七个互相咬合的子系统。
| 子系统 | 典型工件 | 作用 |
|---|---|---|
| 指令系统 | AGENTS.md、CLAUDE.md、.cursorrules、任务说明 |
告诉 agent 这个项目是什么、先读什么、不能做什么、如何验证。 |
| 上下文与状态 | PROGRESS.md、feature list、任务票据、执行计划、git 历史 |
让长任务跨会话延续，避免每次从零诊断。 |
| 工具系统 | shell、文件编辑、浏览器、数据库、MCP、项目内专用工具 | 让 agent 能真实操作世界，而不是只生成文字。 |
| 环境系统 | requirements.txt、pyproject.toml、Docker、devcontainer、.env.example |
保证依赖、版本、服务、外部配置可复现。 |
| 约束与安全 | lint、架构测试、权限策略、sandbox、secret 策略 | 在结果层面强制不变量，避免越权、乱改、泄漏和架构腐化。 |
| 验证与反馈 | unit test、integration test、smoke test、eval、验收脚本 | 用可执行证据代替 agent 的自我判断。 |
| 可观测性与生命周期 | trace、run ledger、日志、成本、token、handoff note | 让失败可复盘，让下一轮能接住上一轮。 |
Harness 能干什么
Harness 的价值不是“让模型更聪明”，而是让模型已有能力更稳定地转化成工程产出。
1. 让 agent 更快进入项目
没有 harness 的仓库里，agent 会把大量上下文浪费在猜测：
- 项目怎么启动
- 哪些模块是核心
- 测试怎么跑
- 哪些代码不能碰
- 当前任务做到哪一步
有 harness 后，agent 先读入口地图，再按需读取架构、命令、任务和验收标准。它不需要把整个仓库一次性塞进上下文。
2. 支撑长时间、多会话任务
长任务最大的敌人不是“不会写代码”，而是上下文丢失。Anthropic 的长任务 harness 强调 initializer、feature list、progress log、handoff artifact，本质就是把工作记忆落到磁盘和仓库里。
3. 防止 agent 过早宣布完成
Agent 常见失败模式是“代码看起来写完了，所以它说完成了”。Harness 要把完成定义改成：
完成 = 静态检查通过 + 运行行为通过 + 用户关键路径通过 + 验收证据已记录这把“我感觉好了”替换成“有证据证明好了”。
4. 把人类经验变成机械约束
文档里的规范会被忘记，CI 中的检查不会。deusyu 的学习档案特别强调机械化执行：不要只告诉 agent “保持架构清晰”，要把边界写成 lint、结构测试、文件大小检查、导入规则和验证命令。
5. 提高工具调用质量
AutoAgent 的 program.md 里有一个重要观点：只有一个泛化 run_shell 工具会迫使 agent 每次自己拼命令、解析 stdout，浪费 token 且容易错。更好的 harness 会提供更语义化的工具，例如“检查工作簿结构”“读取指定单元格”“运行 StockMind 离线验收”。
6. 让失败可复盘、可改进
没有日志、trace、运行台账时，失败只能靠猜。好的 harness 会记录：
- agent 做了什么
- 调用了哪些工具
- 哪一步失败
- 失败输出是什么
- 它为什么判断可以继续
- 最终证据是否足够
这样才能做失败归因和持续改进。
7. 让 harness 本身可迭代
AutoAgent 展示了更高级的模式：固定模型，用任务集评分，修改 harness 的 prompt、tools、orchestration、verification，然后用 passed/avg_score 决定保留还是丢弃。也就是说，harness 可以像产品一样被实验、度量和演进。
为什么需要 Harness
模型有能力，但环境不给力
强模型在 benchmark 上能解很多题，但真实项目不是单题问答。真实项目有旧代码、隐含约定、外部服务、环境变量、网络波动、测试漏洞和历史决策。Harness 的作用是把这些环境因素变成 agent 可见、可执行、可验证的系统。
上下文窗口不是可靠记忆
上下文窗口会满，会被压缩，会丢失细节。仓库内文档、任务状态、运行台账和 git 历史才是更稳定的记忆。
Agent 会复制仓库中的坏模式
Agent 会从现有代码中学习风格。如果仓库里有过时文档、重复逻辑、无测试路径，它很容易继续放大这些问题。Harness 需要定期做“熵管理”：清理坏示例、更新文档、补上不变量。
自我评估天然偏乐观
生成者检查自己的工作，往往会过度宽容。更可靠的做法是分离 worker 和 checker：生成 agent 负责实现，验证脚本、独立 evaluator 或人类 review 负责挑错。
Agent 吞吐量会放大质量问题
一个人一天写一个坏 PR，问题还慢。多个 agent 一天产出十几个坏 PR，架构腐化会很快。Harness 用边界、验证和台账把吞吐量转化成稳定产出，而不是混乱。
一个最小可用 Harness
如果只做最少的事情，建议从这五个文件开始：
项目根目录/
├── AGENTS.md
├── docs/ARCHITECTURE.md
├── docs/harness/PROGRESS.md
├── docs/harness/feature-list.json
└── scripts/harness/verify.sh最小 harness 的目标不是完美，而是先让 agent 每次开工都能回答五个问题：
- 我现在在哪个项目里？
- 我应该先读哪些文件？
- 当前任务的范围是什么？
- 我怎样证明自己完成了？
- 如果我停下，下一轮如何继续？
