Harness Engineering 是围绕 AI Agent 设计约束机制、反馈回路、工作流控制和持续改进循环的系统工程实践。它解决的核心问题是：当 AI Agent 拥有了强大的代码生成能力后，如何确保其输出的可靠性、一致性和长期可维护性。
引言：三层工程概念的嵌套关系
Prompt Engineering、Context Engineering 和 Harness Engineering 构成了嵌套关系，而非并列概念。Phil Schmid 打了个比方：模型是 CPU，Harness 是操作系统——CPU 再强，OS 拉胯也白搭。
Prompt Engineering 解决的是”如何与模型对话”：如何编写清晰的指令、如何设计 Few-shot 示例、如何使用 Chain-of-Thought 推理。它是原子层面的交互优化。
Context Engineering 解决的是”给 Agent 看什么”：如何组织上下文窗口、如何检索相关信息、如何管理对话历史。它是会话层面的信息管理。
Harness Engineering 解决的是”系统怎么防崩、怎么量化、怎么修”：如何构建多协作系统、如何设计反馈回路、如何强制执行架构约束。它是系统层面的工程实践。
三者层层递进：Prompt Engineering 是基础，Context Engineering 在其之上构建会话管理，Harness Engineering 在更上层构建完整的开发和运维体系。mtrajan 的区分更直接：Context Engineering 管的是输入，Harness Engineering 管的是系统行为。
第一部分：为什么需要 Harness Engineering
模型能力不是瓶颈
Can.ac 实验：仅改变 Harness 的工具格式，Grok Code Fast 1 从 6.7% 跃升至 68.3%——没有修改模型权重，提升超过 10 倍。
LangChain 实验：同一模型通过 Harness 改进，Terminal Bench 2.0 排名从第 30 名跃升至第 5 名，提升 13.7 分。
五个独立团队得出相同结论：基础设施才是瓶颈，而非智能水平。OpenAI 团队指出：”真正卡你的不是 Agent 写代码的能力，而是围绕它的结构、工具和反馈机制跟不上。”
上下文窗口利用率法则
Dex Horthy 的经验观察：上下文填得越满，LLM 输出质量越差。以 168K token 窗口为例：
- Smart Zone（前约 40%）：聚焦、准确的推理
- Dumb Zone（超过约 40%）：幻觉、循环、低质量代码
给 Agent 塞更多 MCP 工具、冗长文档、累积对话历史，不会让它更聪明——反而会让它变笨。
Agent 的典型失败模式
失败模式 1：试图一步到位（One-shotting）
Agent 倾向于一次做完所有事情，上下文窗口耗尽，后续会话看到半成品代码，需大量时间恢复工作状态。
失败模式 2：过早宣布胜利
部分功能完成后直接宣布任务完成，忽略大量未实现功能。
失败模式 3：过早标记功能完成
写完代码标记”完成”，未做端到端测试，单元测试通过不代表功能可用。
失败模式 4：环境启动困难
每次新会话须花费大量 token 弄清如何运行应用，而不是花在实际开发上。
第二部分：核心原则与设计思想
四大支柱
Harness Engineering 的四大支柱来自五个独立团队（OpenAI、Anthropic、Carlini、Huntley、Horthy）的实践收敛。
支柱一：上下文架构（Context Architecture）
核心原则：Agent 应当恰好获得当前任务所需的上下文——不多不少。
解决方案是分层上下文与渐进式披露。不要将所有指令塞进一个文件，而是构建三层体系：
- Tier 1（会话常驻）：AGENTS.md / CLAUDE.md，项目结构概览
- Tier 2（按需加载）：专业化 Agent 的上下文、领域知识
- Tier 3（持久化知识库）：研究文档、规格说明、历史会话
OpenAI 实践：使用小型 AGENTS.md 指向更深层的事实源——设计文档、架构图、执行计划、质量评级——全部版本控制。
支柱二：Agent 专业化（Agent Specialization）
核心原则：专注于特定领域、拥有受限工具的 Agent 优于拥有全部权限的通用 Agent。
专业化是上下文管理策略。每个专家携带更少的无关信息，运行在”Smart Zone”内。实践中的角色分工：
| Agent 角色 | 职责范围 | 工具权限 |
|---|---|---|
| 研究 Agent | 探索代码库、分析实现细节 | 只读（Read, Grep, Glob） |
| 规划 Agent | 将需求分解为结构化任务 | 只读，无写入权限 |
| 执行 Agent | 实现单个具体任务 | 限定范围的读写权限 |
| 审查 Agent | 审计完成的工作，标记问题 | 只读 + 标记权限 |
| 调试 Agent | 修复审查发现的问题 | 限定范围的修复权限 |
| 清理 Agent | 对抗熵积累，清理低质量代码 | 读写权限 |
支柱三：持久化记忆（Persistent Memory）
核心原则：进度持久化在文件系统上，而非上下文窗口中。每次新会话从零开始，通过文件系统制品重建上下文。
典型会话启动流程：
- 运行
pwd查看工作目录 - 读取 git log 和进度文件，了解最近工作
- 读取 feature list，选择最高优先级未完成功能
- 启动开发服务器，运行基础端到端测试
- 确认基本功能正常后，开始新功能开发
关键发现：使用 JSON 格式追踪 feature 状态比 Markdown 更有效，因为 Agent 不太可能不恰当地修改或覆盖结构化数据。
支柱四：结构化执行（Structured Execution）
核心原则：将思考与执行分离。研究和规划在受控阶段进行，执行基于验证过的计划，验证通过自动化反馈（测试、Linter、CI）和人类审查完成。
执行序列：理解 → 规划 → 执行 → 验证。
人工检查点的价值：审查计划远比审查代码快。当规格正确时，实现自然可靠；当规格有误时，可在 500 行代码生成之前及时纠正。
第三部分：OpenAI 的工程结构实践
代码仓库作为记录系统
OpenAI 团队的核心原则：将代码仓库作为唯一事实源。写在 Slack 讨论或 Google Docs 中的知识对 Agent 来说等于不存在。
他们构建了结构化的 docs/ 目录作为知识库：
1 | docs/ |
简短的 AGENTS.md（约 100 行）被注入到上下文中，作为内容目录，指向更深层的事实源。
架构约束的机械化执行
OpenAI 为每个业务域定义了严格的架构约束和依赖方向：
1 | Types → Config → Repo → Service → Runtime → UI |
横切关注点（认证、连接器、遥测、功能标志）通过单一的显式接口进入：Providers。任何违反依赖方向的代码都被自定义 Linter 和结构测试自动检测和阻止。
自定义 Linter 的巧妙设计：当 Agent 违反架构约束时，错误消息不仅标记违规——还告诉 Agent 如何修复。工具在 Agent 工作时同时”教会”它。
文档中记录是不够的；如果不能机械化地强制执行，Agent 就会偏离。在以人为本的工作流程中，这些规则可能会让人感到迂腐或束缚。有了智能体，它们就成了倍增器：一旦编码，它们就能立即应用于所有地方。
可观测性集成
OpenAI 团队将可观测性连接到 Agent 工作流：
浏览器自动化：将 Chrome DevTools 接入智能体运行时，创建用于处理 DOM 快照、截图和导航的技能。这使 Codex 能够复现错误、验证修复，并直接推理 UI 的行为。
可观测性堆栈：日志、指标和追踪记录通过本地可观测性堆栈展示给 Codex。Codex 可以使用 LogQL 查询日志，使用 PromQL 查询指标。”将启动时间降至 800ms 以下”或”这四个关键用户旅程中的任何跨度都不得超过两秒”这样的提示变得可行。
熵管理与垃圾回收
AI 生成的代码以不同于人类编写的方式积累”技术债”——Codex 会复现代码仓库中已存在的模式，甚至包括那些不均衡或不够理想的模式。
最初团队每周五花 20% 的时间手动清理”AI Slop”（低质量生成物）。这后来被自动化为循环清理流程：
- 将”黄金原则”编码到代码仓库中——带主观意见的机械规则，保持代码库的可读性和一致性
- 定期运行后台 Codex 任务，扫描偏差、更新质量等级，并发起重构 Pull Request
- 大多数清理 PR 可在一分钟内审查并自动合并
这类似于垃圾回收：技术债务像高息贷款，不断地以小额贷款的方式偿还好过让债务不断累积再痛苦地一次解决。人类的品味一旦被捕捉，就会持续应用于每一行代码。
自动化端到端的能力
最近，代码仓库跨过了一个重要门槛，使 Codex 能够端到端地驱动一个新功能：
给定一个提示，智能体现在可以：
- 验证代码库的当前状态
- 重现已报告的漏洞
- 录制一个演示故障的视频
- 实施修复措施
- 通过运行应用程序来验证修复
- 录制第二个视频，演示解决方案
- 打开 Pull Request
- 回应智能体和人类反馈
- 检测并修复构建故障
- 仅在需要判断时才交由人工处理
- 合并更改
单次 Codex 运行在单个任务上可持续工作超过六个小时（通常在人类睡眠时间）。
第四部分：工程师角色的范式转变
从写代码到设计环境
OpenAI 和 Anthropic 的实践指向同一个结论：工程师的工作正在分成两块不一样的部分。
第一部分：构建环境
当 Agent 卡住时，团队将其视为环境设计问题——诊断”究竟还需要什么样的能力，又该如何让这个能力对智能体来说既清晰可读又可强制执行”，并将其反馈到代码仓库中，始终由 Codex 自己编写修复。
焦点从”实现”转向”赋能”。解决进展的唯一方式是让 Codex 来完成工作，而人类工程师总是介入追问：”缺少什么才能可靠地继续工作”。
第二部分：管理工作
Greg Brockman 建议每个团队指定一名”Agent 队长”——负责思考 Agent 如何融入团队工作流。Peter Steinberger（OpenClaw 创作者）在一个月内完成了 6,600+ 次提交，同时运行 5-10 个 Agent。
这两部分不是顺序关系。你同时做两件事，每件事都影响另一件：Agent 的失败告诉你环境缺少什么；更好的环境让管理更顺畅。
规划是新的编码
越来越多的开发者强调与 AI 合作时前期规划的广度——如此之深，以至于大多数 AI 编码工具现在都包含专用的”更多规划”功能。
Cloudflare 的 Boris Tane：”永远不要让 Agent 在你审查和批准书面计划之前写代码。这种规划与执行的分离是我做的最重要的一件事。“
Anthropic 的做法：初始化 Agent 从高级 prompt 生成综合 feature 列表——单个 Web 应用超过 200 个独立功能，每个都有明确的测试步骤，全部初始标记为”failing”。
计划被视为一流的工件。临时轻量计划用于小幅变更，复杂工作则记录在执行计划中，并附带进度和决策日志，提交到代码仓库。活跃计划、已完成计划和已知的技术债务都已版本控制并集中存放。
两种管理风格
| 模式 | 描述 | 优势 | 要求 |
|---|---|---|---|
| 有人值守并行化 | 主动管理多个 Agent 会话，检查每个、按需重定向 | 更多控制，更早发现问题 | 认知负担高 |
| 无人值守并行化 | 开发者发布任务后离开，Agent 自主完成到 PR | 更好的可扩展性 | Harness 必须足够好 |
Stripe 能做到无人值守并行化，是因为他们已经建立了 Toolshed（500+ 工具）、预热 Devbox 和紧密的 CI 集成。大多数团队还不具备这些条件。
团队在光谱上的位置取决于两个因素：Harness 的成熟度和对 Agent 在代码库中的信任程度。
人工品味的持续反馈
生成的代码不总是符合人类的风格偏好，这也没关系。只要输出是正确的、可维护的，并且对未来的智能体运行而言清晰易读，就可以算作达标。
人类的品味会不断反馈到系统中。审查评论、重构的 Pull Request 和面向用户的 Bug 会被记录为文档更新，或直接编码到工具中。当文档不够完善时，团队会将规则转化为代码——由 Codex 编写修复。
审查计划远比审查代码快。当规格正确时，实现自然可靠；当规格有误时，可以在 500 行代码生成之前及时纠正。
结语
Harness Engineering 解决的核心问题是：当 AI Agent 拥有了强大的代码生成能力后，如何确保其输出的可靠性、一致性和长期可维护性。
随着模型能力提升，Harness 应该越做越薄，但核心工程原则——上下文管理、约束执行、持续验证——将持续重要。工程师的工作重心从”写代码”转向”设计环境”，从”调试代码”转向”调试环境让 Agent 可靠地工作”。
未来，团队可能会从一组预制 Harness 中选择，就像今天的服务模板。但这种转变不会自动发生——它需要主动学习、实验和沉淀。最好的 Harness 不是设计出来的，而是在一次次失败中演化出来的。
正如 Mitchell Hashimoto 所说：”每当发现 Agent 犯错，就花时间设计一个解决方案，确保 Agent 永远不会再犯同样的错误。”这就是 Harness Engineering 的本质——通过系统地投入工程时间，让 AI Agent 今日之错误，成为明日系统之约束。
引用来源
- 工程技术：在智能体优先的世界中利用 Codex - OpenAI 工程博客 (2026-02-11)
- Harness design for long-running application development - Anthropic 工程博客 (2026-03-24)