Harness Engineering
创建时间： 2026-04-27
来源： [[sources/Effective harnesses for long-running agents]]、[[sources/Harness design for long-running application development]]、[[sources/Harness engineering_ leveraging Codex in an agent-first world]]
相关： Generator-Evaluator-Architecture、Agent-First-Repository-Design、Deep-Module-Architecture、Vibe-Coding-to-Agentic-Engineering、Agent-Native-Infrastructure
定义
Harness Engineering（harness 工程）是为 AI 编码智能体设计工作环境的工程学科——包括提示词、工具、工件、反馈回路和多智能体结构——使智能体能够在长时间跨度、多上下文窗口中一致地产出可靠、高质量的工作。
核心范式转移：人类的角色从编写代码转变为设计智能体的工作环境，指定意图，构建反馈回路，并将品味编码为可机械执行的规则。
人类掌舵。智能体执行。
为什么需要 Harness Engineering
将前沿编码模型（如 Opus 4.5 / GPT-5）直接放在代码仓库中并给出高层次提示（如”构建 claude.ai 的复刻版”），其表现远达不到生产质量的水平。失败遵循两种一致的模式：
- 一把梭（One-shot）：智能体试图一次完成所有工作，耗尽上下文窗口，留下半实现的、未文档化的功能供下一个会话猜测。
- 过早得意（Premature victory）：智能体看到已取得一些进展，便宣布任务完成。
另外还有两个深层问题：
- 自我评价偏差：当被要求评估自己生成的输出时，智能体会自信地赞扬自己的工作——即使质量对任何人类观察者来说都明显平庸。
- 上下文焦虑：某些模型（特别是 Sonnet 4.5）在接近其认为的上下文限制时会开始过早收尾。
核心原则
1. 将工作分解为可处理的单元
每个智能体会话只应处理一个特性、一个冲刺或一个定义明确的任务。这解决了”一把梭”问题，并提供了进展的自然检查点。
实践示例：
- Anthropic 初始器智能体将提示扩展为 200+ 个特性，全部标记为
"passes": false - OpenAI 团队将工作分解为执行计划（exec-plans），包含进展和决策日志
- 冲刺合同（Sprint contract）：在编写代码之前，生成器和评估器就”完成”的具体含义进行协商
2. 结构化交接工件
当智能体以全新上下文窗口启动时，它需要快速理解工作状态。解决方案是让每个智能体留下结构化档案以传递给下一个智能体：
| 工件 | 用途 | 来源 |
|---|---|---|
claude-progress.txt | 按时间顺序记录已完成的工作 | Anthropic 文章 1 |
| 特性列表 JSON | 全面描述所有特性及其通过/失败状态 | Anthropic 文章 1 |
| Git 提交历史 | 带有描述性消息的可审计代码变更记录 | 全部三个来源 |
init.sh | 可运行开发服务器的可重现脚本 | Anthropic 文章 1 |
| 冲刺合同 | 生成器在冲刺中与评估器协商的测试标准 | Anthropic 文章 2 |
| 执行计划（Exec plans） | 带有进展与决策日志的版本化计划文件 | OpenAI 文章 3 |
3. 环境清洁状态
每次会话结束时，代码库应处于适合合并到主分支的状态：没有重大 bug，代码有序，文档良好。这可以防止后续智能体在实施新功能之前不得不清理无关的混乱。
4. 分离生成与评估
智能体无法可靠地评估自己的工作。生成器和评估器的分离是一个强有力的杠杆。评估器使用浏览器自动化（Playwright/Puppeteer MCP）像用户交互一样测试应用程序，根据明确的标准进行评分，并给出具体的、可操作的反馈。详见 Generator-Evaluator-Architecture。
5. 约束作为倍增器
严格的架构边界——通过自定义 linter 和结构测试机械执行——使智能体能够在没有架构漂移的情况下高速交付。在每个业务领域内，代码只能按照固定的层次顺序（类型 → 配置 → 仓库 → 服务 → 运行时 → 用户界面）向前依赖。跨领域关注点通过单一显式接口（Providers）进入。
你原本会推迟到拥有数百名工程师时才实施这种架构。对于编码智能体来说，这是一个早期前提条件：约束是保持速度而不衰退的关键。
这一原则与 Deep-Module-Architecture 中 Ousterhout 的深模块理论直接呼应：AI 加速软件熵增，而深度模块——接口窄而实现深的模块——正是对抗熵增的结构性解药。约束（linter、架构测试）是把深模块思维机械化的工具。
6. 渐进式信息披露
智能体从一个小而稳定的入口点开始，并被教导接下来到哪里查找——而不是在一开始就被淹没。
实践中：AGENTS.md（约 100 行）仅作为目录，指向 docs/ 中更深层次的真实来源。像 DESIGN.md、FRONTEND.md、RELIABILITY.md 这样的文档被嵌入到智能体上下文中的必要位置。详见 Agent-First-Repository-Design。
7. 将品味编码为工具
在人类优先的工作流程中可能显得迂腐的规则——结构化日志、命名规范、文件大小限制、在边界处验证数据形状——在编码为自定义 linter 和 CI 检查后，成为倍增器。由于检查是自定义的，错误消息可以直接将修复指令注入到智能体上下文中。
跨来源的架构演进
Anthropic 文章 1：初始器 + 编码双智能体
初始器智能体（首次运行） 编码智能体（每个后续会话）
├─ 编写 init.sh ├─ 运行 pwd 以定位
├─ 编写 claude-progress.txt ├─ 阅读 git 日志和进度文件
├─ 编写 features.json（200+） ├─ 阅读 features.json
└─ 初始 git 提交 ├─ 选择一个特性
├─ 实施它
├─ 使用 Puppeteer 进行端到端测试
├─ git commit + 进度更新
└─ 留下清洁环境
Anthropic 文章 2：三智能体 GAN 式架构
规划器 生成器 评估器
├─ 将 1-4 句话 ├─ 每个冲刺实施 ├─ 通过 Playwright 测试
│ 提示 → 完整 │ 一个特性 ├─ 根据四个标准
│ 产品规格 ├─ 与评估器协商 │ 评分（设计质量、
├─ 设定范围 │ 冲刺合同 │ 原创性、工艺、
└─ 融入 AI 功能 ├─ 自我评估 │ 功能性）
└─ 提交 + 文档 └─ 给出详细反馈
演进：Opus 4.6 修复了上下文焦虑 → 取消了上下文重置；取消了冲刺结构 → 评估器改为仅在结束时单次运行。
OpenAI 文章 3：以智能体为优先的完整仓库
drafts/ ← 规划工件
├─AGENTS.md ← 约 100 行目录
├─ ARCHITECTURE.md ← 领域与包层叠结构地图
docs/
├─ design-docs/ ← 核心信念与设计文档，含验证状态
├─ exec-plans/ ← 活跃计划、已完成计划、技术债务追踪
├─ product-specs/ ← 产品规范
└─ references/ ← 由智能体使用的 LLM 优化参考文件
人类工程师仅通过提示词进行交互：描述任务 → 运行智能体 → 允许智能体开启 PR。代码审查越来越多地从智能体到智能体处理。
吞吐量效应
当智能体吞吐量远超人类注意力时，传统工程规范需要重新校准：
- 最小阻塞合并门槛：拉取请求生命周期短，测试不稳定常通过后续运行处理。
- 纠错成本低廉，而等待成本高昂。
- 垃圾回收模式：定期的后台智能体扫描偏差，更新质量评分，并开启有针对性的重构 PR——大多数可在不到一分钟内审核并通过自动合并。
开放问题
- 单次通过的通用智能体还是专业化智能体（测试员、QA、代码清理员）——哪种在多上下文窗口中表现更好？
- 架构一致性在纯智能体生成系统中，经过多年将如何演变？
- 随着模型能力的持续提升，如何界定”人类判断”与”编码入系统的判断”之间的最大杠杆点？
参考资料
- 来源：Anthropic《Effective harnesses for long-running agents》——初始器+编码双智能体模式
- 来源：Anthropic《Harness design for long-running application development》——GAN 式多智能体架构与模型升级驱动的简化
- 来源：OpenAI《Harness engineering: leveraging Codex in an agent-first world》——智能体优先仓库设计与零手写代码团队