一、Harness 基本概念

1. Harness 是什么？

Agent = Model + Harness。你不是模型，那你做的东西大概率就是 Harness。

• Model（CPU）：只提供推理和生成能力，是一个输入输出函数；
• Harness（OS）：模型之外的整套系统——系统提示词、工具调用、文件系统、沙箱环境、编排逻辑、钩子中间件、反馈回路、约束机制。

Harness 把状态、工具、反馈、执行环境和安全边界串起来，Agent 才能真正开始干活。CPU 再强，OS 天天崩，体验也不会好。

关键实验：同一个模型，只换了文件编辑接口的调用方式，编码基准分数从 6.7% 跳到 68.3%。模型没变，变的是它外面那套系统。

2. Harness vs Prompt Engineering vs Context Engineering

三者是一层套一层的关系，处理的问题范围越来越大：

层级	解决的问题	关注点	典型工作
Prompt Engineering	怎么把指令说清楚	让模型理解意图，减少局部歧义	系统提示词、Few-shot、思维链引导
Context Engineering	该给 Agent 看什么	在合适时机提供正确且必要的信息	上下文管理、RAG、记忆注入、Token 优化
Harness Engineering	系统怎么持续执行、纠偏、观测和恢复	长链路任务中的持续正确、偏差修正、故障恢复	文件系统、沙箱、约束执行、反馈回路、观测

模型决定上限，Harness 决定底线。
简单任务 Prompt 就够；需要外部知识时 Context 更重要；到了长链路、可执行、低容错的商业场景，Harness 才是主要矛盾。

3. Harness 包含哪些组件？

反过来问：模型做不到什么？

模型做不到的事	Harness 怎么补	对应组件
记住多轮对话历史	维护对话历史，每次请求拼进上下文	记忆系统
执行代码、跑命令	提供 Bash 和代码执行环境	通用执行环境
获取实时信息	接入 Web Search、MCP 工具	外部知识获取
操作文件和环境	抽象文件系统，引入 Git 版本控制	文件系统
判断自己有没有做对	提供沙箱、测试工具、浏览器自动化	验证闭环
长任务中保持连贯	上下文压缩、记忆文件、进度追踪	上下文管理

二、Harness 进阶

1. 六层架构

层级	名称	解决什么问题	关键设计
L1	信息边界层	Agent 该知道什么、不该知道什么	定义角色与目标，裁剪无关信息，结构化组织任务状态
L2	工具系统层	Agent 怎么和外部世界交互	选择工具、控制调用时机、提炼工具结果并反馈
L3	执行编排层	多步骤任务怎么串起来	让模型按"理解目标→判断信息→分析→生成→检查"推进
L4	记忆与状态层	长任务中间结果怎么管理	独立管理当前任务状态、中间产物和长期记忆，避免状态混在一起
L5	评估与观测层	Agent 怎么知道自己做对了没有	建立独立于生成过程的验证机制
L6	约束、校验与恢复层	出错了怎么办	预设规则拦截错误，失败时提供重试、回滚或降级

落地建议：不要一上来就搭齐六层。先做 L1（信息边界）和 L6（约束恢复），投入不高但最容易见效；中间几层随项目复杂度慢慢补。

2. 为什么瓶颈经常不在模型？

• Can.ac 实验：同一模型只换工具调用格式，效果差十倍；
• LangChain 实践：优化 Agent 运行环境（文档组织、验证回路、追踪系统），Terminal Bench 2.0 从全球第 30 名升到第 5 名，得分 52.8% → 66.5%，模型没换；
• model-harness 耦合现象：Claude Code、Codex 等产品的模型和 Harness 是一起调优的，会过拟合。Opus 在 Claude Code 的 Harness 下得分远低于其他 Harness。
• 结论：the best harness for your task is not necessarily the one a model was post-trained with。

3. 为什么上下文喂越多，Agent 反而越蠢？

Dex Horthy 观察：168K token 上下文窗口，用到约 40% 时输出质量开始明显下降。

区间	占比	表现
Smart Zone	0 ~ 40%	推理聚焦、工具调用准确、代码质量高
Dumb Zone	超过 40%	幻觉增多、兜圈子、格式混乱、代码变差

Anthropic 称之为"上下文焦虑"：Sonnet 4.5 上下文快填满时会变得犹豫，甚至提前收工。单靠压缩不够，他们采用 context resets：清空上下文窗口，通过结构化交接文档保留关键状态，启动新的干净 Agent 继续。

生产建议：把 40% 当成告警线，超过后触发压缩、分段执行或任务交接。等 Agent 已经开始兜圈子再处理就被动了。

4. 从哪里开始搭 Harness？（P0 / P1 / P2 优先级）

P0：可以马上做

行动	为什么	参考实践
创建 AGENTS.md 并持续维护	Agent 每次启动自动加载，犯错后更新，形成反馈循环	Hashimoto 每一行对应一个历史失败案例
写自定义 Linter + 修复指令	错误消息直接告诉 Agent 怎么改	OpenAI 的 Linter 报错自带修复方法
把团队知识放进仓库	Slack、Wiki、Docs 里的知识对 Agent 很难稳定可见	OpenAI 把仓库作为事实来源

坑：不要把 AGENTS.md 写成超级 System Prompt。OpenAI 的做法更克制——AGENTS.md 只当目录用，约 100 行，详细规则放到子文档按需加载。

P1：P0 稳了之后再补

行动	为什么	参考实践
分层管理上下文	避免所有信息塞进一个文件，按需披露	OpenAI 把 AGENTS.md 当目录用
建立进度文件和功能列表	用 JSON 追踪功能状态，Agent 不太容易乱改结构化数据	Anthropic 初始化 Agent + 编码 Agent 两阶段
给 Agent 端到端验证能力	让 Agent 像用户一样验证功能	Anthropic 使用 Playwright / Puppeteer MCP
控制上下文利用率	尽量不超过 40%，用增量执行降低污染	Dex Horthy 的 Smart Zone / Dumb Zone

P2：有余力再考虑

行动	为什么	参考实践
Agent 专业化分工	每个 Agent 携带更少无关信息，留在 Smart Zone	Carlini 的去重、优化、文档 Agent
定期垃圾回收	清理速度要跟得上生成速度	OpenAI 的后台清理 Agent
可观测性集成	把性能优化从感觉问题变成可测量的问题	OpenAI 接入 Chrome DevTools

5. Harness 成熟度阶段

阶段	特征	工程师角色
Level 0：无 Harness	直接给 Agent Prompt，没有结构化约束	手动写代码，偶尔使用 AI
Level 1：基础约束	AGENTS.md、基础 Linter、手动测试	主要写代码，AI 辅助
Level 2：反馈回路	CI/CD 集成、自动化测试、进度追踪	规划和审查为主
Level 3：专业化 Agent	多 Agent 分工、分层上下文、持久化记忆	设计环境和管理执行过程
Level 4：自治循环	无人值守并行化、自动清理、自修复	架构设计和质量把关

不需要追求一步到 Level 4，很多团队从 Level 0 到 Level 1 收益就已经很明显。

三、Harness 还没解决的问题

问题	现状	谁在关注
棕地项目怎么改造	公开成功案例几乎都是绿地项目，缺少成熟方法论	Böckeler 比作"在从没用过静态分析的代码库上跑静态分析"；提出 Ambient Affordances：环境本身的结构特性（类型系统、模块边界、框架抽象）会影响 Harness 能做到什么程度
怎么验证 Agent 做对了事	更擅长限制别做错，但验证功能正确性还很弱	Böckeler 批评：用 AI 生成的测试验证 AI 生成的代码，像"用同一双眼睛检查自己的作业"
AI 生成代码的长期可维护性	LLM 代码经常重新实现已有功能，长期效果还不好判断	Greg Brockman 提出过，但目前没有清晰答案
Harness 该做厚还是做薄	Manus 五次重写越做越简单，OpenAI 五个月越做越复杂	场景决定：通用产品追求最小化，特定产品可高度定制；模型变强后 Harness 应定期简化
单 Agent 还是多 Agent	Hashimoto 坚持单 Agent，Carlini 使用 16 个并行 Agent	规模决定：小项目单 Agent 够用，大项目走向专业化分工

绿地项目：从零开始的新项目，无历史包袱；棕地项目：在已有代码库上改造，有历史架构和技术债。目前公开案例基本都是绿地项目，棕地改造是最大挑战。

四、一线团队实战案例

1. OpenAI：三个人，五个月，一百万行，零手写代码

指标	数值
团队规模	3 名工程师，后扩至 7 人
持续时间	5 个月（2025 年 8 月起）
代码规模	约 100 万行
手写代码	0 行，只做设计约束
合并 PR 数	约 1,500 个
日均 PR/人	3.5 个
效率提升	约 10 倍

核心做法：

1. 给 Agent 一张地图，不要塞一本千页手册：AGENTS.md 约 100 行当目录，指向 docs/ 下深层设计文档，即渐进式披露。Agent Skills 也是这个思路的标准化实现。
2. 架构约束要靠工具执行：定义固定分层 Types → Config → Repo → Service → Runtime → UI，依赖方向不能反，靠自定义 Linter 和结构测试保证。违反规则时工具不只是报错，还告诉 Agent 怎么改。

   原话：If it cannot be enforced mechanically, agents will deviate. 只写在文档里的约束不够。

3. 可观测性也要给 Agent 看：接入 Chrome DevTools Protocol，Agent 可自己抓 DOM 快照和截图；日志、指标、链路追踪通过本地可观测性栈暴露。"把启动时间降到 800ms 以下"变成 Agent 可自己测量验证的目标。
4. 熵不会自己消失：AI 生成代码越多，低质量实现、重复逻辑、文档不一致也越多。一开始每周五花 20% 时间手动清理，后来自动化：后台 Agent 定期扫描并自动提交清理 PR。
5. Slack 里的知识 Agent 很难稳定用上：把团队知识作为版本控制制品放进仓库，让仓库成为可追踪、可引用的事实来源。

OpenAI 自己也说：这个结果不应被假设为在缺少类似投入的情况下可以复现。普通团队先学地图式文档、机械化约束和主动清理这些思路。

2. Anthropic：从上下文焦虑到三智能体架构

案例 A：Carlini 用 16 个 Agent 写 C 编译器

指标	数值
持续时间	约 2 周
并行 Agent 数	16 个 Claude Opus 实例
会话数	约 2,000 个
产出	10 万行 Rust 代码
GCC torture test	99% 通过率
可编译项目	PostgreSQL、Redis、FFmpeg、CPython、Linux 6.9 Kernel 等 150+
API 成本	约 2 万美元

Harness 细节：

• 日志不打控制台，全部写文件，用 grep 友好的单行格式（如 ERROR: [reason]），主动减少上下文污染；
• 测试不全部跑：每个 Agent 只跑随机 1-10% 测试子集，单次运行内确定，跨 VM 随机，整体覆盖全部测试，单个 Agent 不会耗几小时；
• Agent 角色逐渐专业化：核心编译器、去重、性能优化、代码质量、文档。LLM 经常重新实现已有功能，专门做去重很有必要。

Carlini 原话："我必须不断提醒自己，我是在为 Claude 写这个测试框架，不是为自己写。"Harness 的服务对象首先是 Agent。

案例 B：借鉴 GAN 的三智能体架构

• Planner：拿 1-4 句产品描述，扩展成完整产品规格，被要求"在范围上要大胆"；
• Generator：按功能一个个做 Sprint，每个 Sprint 有明确完成标准；
• Evaluator：用 Playwright MCP 实际点击运行中的应用，按产品设计深度、功能性、视觉设计、代码质量等维度打分。

解决两个问题：

问题	表现	解法
上下文焦虑	Sonnet 4.5 快到上下文上限时草草收尾	context resets + 结构化交接，单靠压缩不够
自我评价偏差	Agent 自信地夸自己做得好，实际质量一般	生成和评估交给两个独立 Agent

打分权重设计：前端设计里设计质量和原创性权重故意调得比功能性和代码质量更高，因为模型很容易做出"功能齐全但长相平庸"的东西。

context resets：遇到上下文焦虑选择重启

当 Agent 上下文接近饱和时：先把当前任务状态、已完成工作、待办事项结构化提取 → 启动新的干净 Agent → 把交接文档给它 → 新 Agent 从干净状态继续。

类似程序遇到内存泄漏时重启进程再从检查点恢复。长任务里，一个干净的新 Agent 往往比塞满历史信息的 Agent 表现更好。

两种配置成本对比：

配置	耗时	花费	效果
Solo Harness（单 Agent + 最少工具）	20 分钟	$9	跑不起来的半成品
Full Harness（三 Agent + 完整工具链）	6 小时	$200	完整可用的应用

重要发现：把模型从 Sonnet 4.5 换成 Opus 4.6 后，Sprint 机制可以完全移除，Evaluator 从每个 Sprint 检查变成最后只检查一次。

Every component in a harness encodes an assumption about what the model can’t do on its own, and those assumptions are worth stress testing.
Harness 里每个组件都在假设"模型自己做不到这个"，模型变强后这些假设要重新测试，Harness 也要定期简化。

3. Stripe：每周 1300+ 个 PR 的无人值守模式

Minions 系统：开发者发一条 Slack 消息，Agent 从写代码、跑 CI 到提 PR 全部完成，人只在最后审查。每周 1300+ 个完全由 Minions 生产、无人类手写代码的 PR 被合并。

组件	作用	关键设计
Devbox	开发环境	AWS EC2 预装源码和服务，预热池分配，启动约 10 秒，“牲口不是宠物”
编排状态机	流程控制	混合确定性节点（lint、push）和 Agent 节点（实现功能、修 CI）
Toolshed MCP	工具服务	集中式 MCP 服务，近 500 个工具，每个 Minion 拿到筛选后的子集
反馈回路	质量保障	Pre-push hook 秒级修 lint；推送后最多 2 轮 CI，覆盖 300 万+ 测试

理念：What’s good for humans is good for agents。过去为人类工程师投入的 Devbox、工具链和开发者体验，在 Agent 上也直接产生回报。Agent 不需要一套完全独立的基础设施，更应被当作开发环境中的一等公民。

4. Mitchell Hashimoto：一个人的 Harness 工程学

Vagrant、Terraform、Ghostty 作者。坚持一次只跑一个 Agent，保持深度参与：“我不打算跑多个 Agent，也不想跑。”

步骤	名称	做法
1	放弃聊天模式	让 Agent 在能读文件、跑程序、发 HTTP 请求的环境里直接干活
2	复现自己的工作	每件事做两次，一次自己做，一次让 Agent 做，“痛苦至极”
3	下班前启动 Agent	每天最后 30 分钟布置任务（深度调研、模糊探索、Issue 分拣）
4	外包确定性任务	挑出 Agent 几乎一定能做好的任务后台跑，关掉桌面通知避免上下文切换
5	工程化 Harness	Agent 每犯一次错，就工程化一个方案，让它以后不再犯同类错误
6	始终有 Agent 在跑	目标是 10-20% 的工作时间有后台 Agent 运行

Ghostty 的 AGENTS.md 每一行都对应一个过去的 Agent 失败案例，是一个持续积累的防错系统。

5. Birgitta Böckeler：对 Harness 的结构化梳理

Thoughtworks Distinguished Engineer，把 Harness 组件归为三类：

归类	关注点	典型实践
Context Engineering	管理 Agent 看到什么、什么时候看到	从巨大 AGENTS.md 演化为入口文件 + 分层文档
Architectural Constraints	确保 Agent 不跑偏	自定义 Linter、结构测试、LLM Agent 充当约束
Garbage Collection	对抗熵积累	定期运行清理 Agent，扫描不一致和违规

关键判断：

• Harness 可能变成新的服务模板：未来团队可能从一组预制 Harness 中选择，就像今天从服务模板创建新服务；
• 棕地项目改造是最大挑战；
• 功能验证体系还很薄：用 AI 生成的测试验证 AI 生成的代码，仍然缺少独立验证视角。

五、核心总结

1. Agent = Model + Harness，模型是 CPU，Harness 是 OS；很多时候瓶颈不在模型，而在模型之外的工作环境。
2. Prompt ⊂ Context ⊂ Harness：简单任务靠 Prompt，外部知识任务靠 Context，长链路商业场景靠 Harness。模型决定上限，Harness 决定底线。
3. 六层架构：信息边界→工具系统→执行编排→记忆状态→评估观测→约束恢复。落地先做 L1 和 L6，最容易见效。
4. 上下文不是越多越好：超过窗口 40% 进入 Dumb Zone，质量明显下降；用 context resets（重启+结构化交接）对抗上下文焦虑。
5. 落地路径：P0（AGENTS.md + Linter + 知识入库）→ P1（分层上下文 + 进度追踪 + 端到端验证 + 上下文利用率控制）→ P2（Agent 专业化 + 垃圾回收 + 可观测性）。
6. 约束必须机械化执行：只写在文档里的约束不够，If it cannot be enforced mechanically, agents will deviate。
7. 熵不会自己消失：生成速度上来了，清理速度必须跟上，否则项目被自己的产物拖垮。
8. Harness 要定期简化：每个组件都在假设"模型做不到这个"，模型变强后这些假设要重新测试。
9. 共性问题：上下文污染、代码熵积累、工具调用可靠性，这三道坎几乎所有团队都会遇到；区别在于出问题后补救，还是一开始就把约束、验证、清理放进 Harness。