Appearance
Harness Engineering
Harness Engineering 是 OpenAI 提出的一种 AI Agent 驱动的软件开发方法论，核心理念是：人类制定方向与约束，AI 代理全权执行代码实现。该概念来自 OpenAI 2026 年 2 月发表的工程博客文章，描述了其团队如何在 5 个月内用 0 行手动编写的代码构建并交付了生产级软件产品。
Overview
2025 年 8 月，OpenAI 的一个小型工程团队开始了一项实验：从一个空白的 Git 仓库起步，使用 Codex（OpenAI 的 AI 编程代理）构建一个全新的软件产品。全程没有编写任何手动代码。 到 2026 年 2 月，该产品已有数百名内部用户、忠实日常用户，团队扩展至 7 名工程师——所有人的工作都是让代理做有用的工作，而非直接写代码。
该文章的核心理念是：在一个 AI 代理负责代码实现的世界里，工程团队的角色从"写代码"转变为"设计系统、构建脚手架、创造杠杆"。
Core Principles
1. 仓库知识即系统记录（Repository Knowledge as System of Record）
OpenAI 发现，给 Codex 一张地图而非一本 1000 页的说明书效果最佳。他们尝试过"一个大文件"（One Big Prompt）方法，但遇到了三个致命问题：
- 上下文是稀缺资源：超大指令文件挤占了任务、代码和相关文档的空间
- 过度指导等于无指导：当所有内容都标注为"重要"，代理只能做局部模式匹配
- 知识腐烂：单一文件很快变成过时规则的坟场，代理无法分辨哪些规则仍然有效
解决方案是创建一个结构化的知识目录：
AGENTS.md (约 100 行，作为目录索引)
├── ARCHITECTURE.md
│ ├── design-docs/
│ │ ├── index.md
│ │ ├── core-beliefs.md
│ │ └── ...
│ ├── exec-plans/
│ │ ├── active/
│ │ ├── completed/
│ │ └── tech-debt-tracker.md
│ ├── generated/
│ │ └── db-schema.md
│ ├── product-specs/
│ │ ├── index.md
│ │ └── new-user-onboarding.md
│ ├── references/
│ ├── DESIGN.md
│ ├── FRONTEND.md
│ ├── PLANS.md
│ ├── PRODUCT_SENSE.md
│ ├── QUALITY_SCORE.md
│ ├── RELIABILITY.md
│ └── SECURITY.mdAGENTS.md（约 100 行）仅作为入口地图注入上下文，用指针（pointers）指向更深的真理源。这实现了渐进式披露（Progressive Disclosure）——代理从一个小的稳定入口开始，按需深入。
2. 代理可读性即目标（Agent Legibility is the Goal）
因为整个代码库是代理生成的，代码的优化优先级从"人类可读"转向了"代理可读"。
"就像团队会为新工程师优化代码的可导航性一样，我们的人类工程师的目标是让代理直接从仓库本身推理整个业务领域。"
将更多系统信息编码为代理可以检查、验证和直接修改的形式，不仅能提升 Codex 的杠杆效应，也惠及其他代理（如审查代理）。
3. 用不变式替代微观管理（Enforce Invariants, Not Micromanage）
OpenAI 发现，代理在具有严格边界和可预测结构的环境中效率最高。
实践原则：
- 要求 Codex 在边界处解析数据形状（如用 Zod 做 schema 验证），但不规定具体实现方式
- 通过自定义 linter（Codex 自己生成的！）和结构性测试强制执行约束
- 强制要求结构化日志、命名约定、文件大小限制、平台特定可靠性要求
- 结果不一定符合人类的风格偏好——只要正确、可维护、对后续代理可读，就达标
"在人类优先的工作流中，这些规则可能显得迂腐或限制。但有了代理，它们变成了放大器：一旦编码，就无处不在。"
4. 吞吐量改变了合并哲学
随着 Codex 的吞吐量增加，许多传统的工程规范变得低效：
- 测试不稳定通常通过重跑解决，而不是阻塞进度
- 合并速度优先于完美审查——在低吞吐环境中这样做的后果是灾难性的，但在高吞吐的代理驱动环境中，这常常是正确的取舍
- Codex 可以处理自己的代码审查，几乎是代理对代理进行
5. 熵与垃圾回收（Entropy and Garbage Collection）
代理自动化的一个独特问题是：Codex 会复制仓库中已有的模式——即使是不均衡或次优的。 这导致了不可避免的架构漂移（drift）。
最初，人类手动修复——团队每周五花 20% 的时间清理"AI slop"。但这显然不可扩展。解决方案正在向自动化垃圾回收机制演化。
What "Agent-Generated" Actually Means
当 OpenAI 说代码库是由 Codex 代理生成时，指的是代码库中的一切：
| 产物 | 说明 |
|---|---|
| 产品代码和测试 | 应用逻辑、测试用例 |
| CI 配置和发布工具 | GitHub Actions、部署脚本 |
| 内部开发者工具 | 辅助脚本、CLI 工具 |
| 文档和设计历史 | README、架构文档、变更记录 |
| 评估框架（Evaluation Harnesses） | 用于验证系统行为的自动评估工具 |
| 代码审查评论和回复 | 代理生成 review 内容 |
| 仓库管理脚本 | 维护仓库本身的脚本 |
| 生产仪表盘定义文件 | 监控和可观测性配置 |
Levels of Autonomy
OpenAI 描述了代理自主性的演进层次。给定一个提示，Codex 现在可以端到端完成：
- 验证代码库当前状态
- 复现报告的错误
- 录制展示失败过程的视频
- 实现修复
- 通过驱动应用程序验证修复
- 录制展示解决方案的第二段视频
- 创建 Pull Request
- 响应代理和人类的反馈
- 检测并修复构建失败
- 仅在需要判断时升级给人类
- 合并变更
单个 Codex 运行经常连续工作 6 小时以上（通常是在人类睡觉时）。
Key Learnings & Open Challenges
| 挑战 | 描述 | 当前思路 |
|---|---|---|
| 上下文管理 | 让代理在大型复杂任务中拥有足够的上下文而不被淹没 | 渐进式披露 + 结构化知识目录 |
| 架构漂移 | 代理倾向于复制现有模式，即使这些模式在退化 | 自动化垃圾回收 + 质量评分追踪 |
| 评估困难 | 如何验证代理行为在长期中保持一致性 | 代理生成的自评估框架 |
| 安全与边界 | 确保代理不执行意外操作 | 最小权限工具设计 + 机械约束 |
| 知识腐烂 | 文档和规则随时间失去准确性 | 代码即是系统记录 + 机械可验证 |
Why It Matters
- Harness Engineering 定义了 AI 代理驱动软件工程的范式——人类从"写代码"转向"设计约束和方向"
- 它与 Hermes Agent、Codex、Claude Code 等 Agent 工具构成了一个完整的方法论体系
- 该文章展示了一种可复现的模式：AGENTS.md + 结构化知识库 + 机械约束 = 高自主性代理工作流
- 许多工程原则（渐进式披露、不变式优先、吞吐量驱动的合并哲学）跨越了特定工具，适用于任何 AI 代理编程场景
Extensions from the Community
OpenAI 的原始文章引发了广泛的社区讨论和理论深化。以下是最重要的几个扩展方向。
Guides × Sensors Framework（Böckeler/Fowler）
Birgitta Böckeler（Thoughtworks）在 Martin Fowler 博客上提出了一个更系统的框架——用控制论来理解 Harness Engineering。核心是一个 2×2 矩阵：
| 计算性（确定性，CPU） | 推理性（语义，LLM） | |
|---|---|---|
| 引导器/前馈 | bootstrap 脚本、OpenRewrite、LSP | AGENTS.md、Skills、architecture.md |
| 传感器/反馈 | linter、ArchUnit、类型检查、覆盖率 | AI code review、LLM-as-judge |
- 引导器（Guides/前馈）：在智能体行动之前引导它，增加首次成功概率
- 传感器（Sensors/反馈）：在智能体行动之后观察，启用自我纠正
- 计算性：确定性、快速、便宜，每次提交都跑
- 推理性：概率性、慢、贵，选择性运行
关键洞察：单独使用任一维度都不行——只有反馈 = 反复犯同样错误；只有前馈 = 不知道规则是否生效。
Böckeler 进一步将 Harness 的规制能力分为三个维度，成熟度依次递减：
| 维度 | 成熟度 | 说明 |
|---|---|---|
| 可维护性 Harness | 最成熟 | 内部代码质量，现有工具丰富 |
| 架构适应度 Harness | 中等 | 本质是 Fitness Functions |
| 行为 Harness | 最弱 | "房间里的大象"——功能正确性验证仍无可靠答案 |
Ashby 必要多样性定律： 调节器必须至少拥有与被调节系统同等的多样性。LLM 能生成几乎任何东西（高多样性）→ 选定拓扑结构 = 削减多样性 → 全面 harness 变得可行。这为"约束越严，自主性越强"提供了控制论根基。
Harness 的精确定义
社区提出了一个更精确的定义：
Agent = Model + Harness Harness = 模型之外的一切代码、配置和执行逻辑。
裸模型不是智能体——它接受文本/图片/音频/视频，输出文本。它不能原生维护状态、执行代码、访问实时知识、搭建环境。当 harness 给它状态、工具执行、反馈回路和可执行约束时，它才成为智能体。
完整的 Harness 组件清单（综合 LangChain、HumanLayer、Fowler）：
| 来源 | 组件 | 说明 |
|---|---|---|
| LangChain | System Prompts | AGENTS.md、CLAUDE.md |
| LangChain | Tools & MCP | 扩展智能体能力的工具和协议 |
| LangChain | Skills | 渐进式加载的知识包 |
| LangChain | 沙箱基础设施 | 文件系统、浏览器、隔离执行环境 |
| LangChain | 编排逻辑 | 子智能体生成、handoff、模型路由 |
| LangChain | Hooks/中间件 | compaction、续接、lint 检查 |
| HumanLayer | AGENTS.md | ≤60 行，禁止自动生成 |
| HumanLayer | MCP Servers | 信任边界 + 工具数量控制 |
| HumanLayer | Skills | 渐进式披露，按需加载 |
| HumanLayer | Sub-Agents | 上下文防火墙，隔离防 context rot |
| HumanLayer | Hooks | 生命周期脚本，成功静默/失败报错 |
| HumanLayer | Back-Pressure | 测试/构建/类型检查 = 自我验证回路 |
| Fowler | Context Engineering | 知识库 + 动态上下文 |
| Fowler | Architectural Constraints | LLM 审查 + linter + 结构测试 |
| Fowler | Garbage Collection Agents | 定期扫描 + 修复漂移 |
Model-Harness 共演化
一个关键的循环依赖问题：模型在 post-training 阶段会 overfit 到特定 harness；而 harness 编码了对特定模型能力的假设。这导致一个循环：
模型训练时适配 harness → harness 为模型量身设计 → 模型升级 → harness 过时 → 重新设计 harnessLangChain 的数据显示：纯 harness 优化可以将某模型在 Terminal Bench 2.0 上的排名从 Top 30 拉到 Top 5。这意味着最适合你任务的 harness，不一定是模型 post-training 时用的那个。跨模型可移植的 harness 是否可能，仍是一个开放问题。
Harness 生命周期
所有文章都把 harness 当作一个设计产物来讨论，但证据显示 harness 有完整的生命周期：
| 阶段 | 证据 |
|---|---|
| 诞生 | 从零设计 AGENTS.md + linter |
| 成长 | V1 多智能体编排（$200, 6h） |
| 瘦身 | V2 去掉冗余组件（$125, 4h） |
| 过时 | context reset 在新模型上变死重 |
| 被替换 | harness 是牲畜，可随时换掉 |
Anthropic 的时间线显示，一个 harness 从设计到过时大约是一个模型代际（3-6 个月）。这意味着 Harness Engineering 不是一次性的设计工作，而是持续的园艺工作（Harness Gardening）——每次模型升级后，压测每个组件、去掉死重、添加新能力。
四大学派
社区对 Harness Engineering 的瓶颈在哪里有不同的回答，形成了四个学派：
| 学派 | 代表 | 核心主张 | 层面 |
|---|---|---|---|
| 约束派 | OpenAI、HumanLayer | 答案是更好的约束 | 战术层 |
| 控制论派 | Fowler/Böckeler | 答案是系统性的控制回路设计 | 方法层 |
| 架构派 | Anthropic | 答案是更好的架构 | 战略层 |
| 怀疑派 | YDD | 答案可能是我们在解错问题 | 元层 |
四者不是互斥的——约束派解决当前模型的可靠性问题，控制论派提供如何系统设计约束的方法论，架构派解决跨模型代际的可维护性，怀疑派解决整个范式是否值得投入。
Harnessability（可驾驭性）
不是所有代码库都同样适合被 harness：
- 强类型语言（Java、Rust）天然自带类型检查传感器
- 清晰模块边界 支持架构约束规则
- 成熟框架（如 Spring）隐式提高智能体成功概率
- Ambient Affordances（Ned Letcher）：环境本身的结构属性——可读性、可导航性、可处理性
这意味着技术栈选择在 Agent 时代可能向 Java/Spring 等"高可驾驭性"平台倾斜。
一致性自动化的参考实现
开源社区（deusyu/harness-engineering）提供了一个完整的执行一致性检查方案，体现了"机械化执行"的实践精神：
- check-consistency.sh：三项自动化检查——C1 文章编号连续、C2 下游引用数量同步、C3 子目录文件数匹配 README 声明
- Pre-commit hook：每次提交自动运行一致性检查
- CI workflow（GitHub Actions）：在 CI 中运行，使用
<!-- check-consistency: skip-count -->标记支持选择性跳过
这种模式展示了如何将"机械约束"应用到知识库或文档的管理中，是 OpenAI "Enforce Invariants" 原则的实践延伸。
OpenAI 与 YDD 的数据矛盾
Harness Engineering 的有效性存在一个核心矛盾——OpenAI 的个体数据与大规模遥测数据直接冲突：
| 数据源 | 个体效率 | 组织效率 |
|---|---|---|
| OpenAI | 3 人 → 100 万行，人均 3.5 PR/天，扩展到 7 人后仍增长 | ✅ 正向 |
| YDD/METR | 客观慢 19%，主观快 20% | ❌ 负向 |
| YDD/Faros | 个体 PR +98% | DORA 四指标无一改善 |
可能的解释：
- OpenAI 团队是 outlier——他们有最好的模型、最好的 harness、最好的工程师，这不可复制
- 零手写代码是关键约束——强制所有工作走 harness，消除了"AI 写一半人改一半"的低效模式
- 从空仓库开始——没有遗留代码的认知负担，给遗留代码补 harness 可能不经济
- 生存者偏差——OpenAI 发布的是成功案例，那些用了 Codex 但失败的团队不会写博文
对我们的启示： 评估 harness engineering 的价值时，不应拿 OpenAI 的数据做基准，而应拿 YDD 的数据做底线，看 harness engineering 能在多大程度上缩小两者的差距。
供应链视角：AI 输出的端到端管理
将约束理论（Theory of Constraints）应用于 Harness Engineering，可以发现一个强大的类比：
| 制造业供应链 | AI 代码供应链 |
|---|---|
| 工厂 = 模型 | 生产代码 |
| 质检 = 背压（lint/测试） | 拦截坏代码 |
| 仓库 = Session | 持久化中间产物 |
| 物流 = Harness | 编排和路由 |
| 零售 = 交付（合并/部署） | 最终价值产出 |
约束理论的核心洞见： 优化非瓶颈工序不会提升整体吞吐量。YDD 数据证明编码不是瓶颈（PR +98% 但 DORA 不变）。从供应链视角看，真正的瓶颈可能在：
- 需求理解（人类把需求翻译成提示词的准确度）
- 评审（PR +154% 体积，评审时间 +91%）
- 集成（多个智能体产出的代码如何组合）
Harness Engineering 目前主要在优化"工厂"和"质检"，但供应链的瓶颈可能在"物流"和"零售"。下一步最有价值的创新可能不在模型端或约束端，而在评审自动化和集成编排上。
人类角色的渐次消解
追踪 7 篇核心文章中人类角色的演变，可以看到一个清晰的趋势：
| 文章 | 人类做什么 |
|---|---|
| OpenAI 原文 | 设计环境 + 拆解任务 + 提示智能体 + 验证结果 |
| LangChain | 写 AGENTS.md + 配置组件 |
| HumanLayer | 调 6 个杠杆 |
| Anthropic #4 | 写 1-4 句提示词 |
| Ralph 实验 | 写 PROMPT.md（7 行） |
| Anthropic #7（Managed Agents） | ？（文章没提人类） |
从"人类设计整个环境"到"人类写几行提示词"到"人类是 API 客户"，Managed Agents 的文章中"人类掌舵"这个概念没有出现过一次。
质疑： 当 harness 自己管理 session、自己 provision sandbox、自己决定重试策略时，"Human Steers, Agents Execute"是不是已经变成了礼貌性说辞？还是说"掌舵"的含义在升级——从"操作层掌舵"变成了"商业目标层掌舵"？
这个趋势类似于管理学中从"微观管理"到"OKR 管理"的转变——但前提是下属有自主判断力。对智能体来说，这个前提是否成立，恰恰是评估问题提出的根本性质疑。
技术栈收敛与单一栽培风险
Fowler 预测技术栈收敛（选型标准从"开发者偏好"变成"AI 友好度"）。Anthropic 预测 harness 收敛（meta-harness）。LangChain 揭示了 model-harness 耦合。如果三者同时发生：一个主流模型 → 一个主流 harness → 一个主流技术栈。
这是一个**数字单一栽培（monoculture）**风险。类比：全球 80% 的香蕉是 Cavendish 品种，一种真菌就能威胁整个产业。如果所有人都在 Claude + Claude Code + TypeScript 上构建，一个模型回归就能影响所有人。
反向力量：
- 开源模型（Llama、Mistral）提供了替代路径
- 但切换成本高——模型换了 harness 可能需要重新适配
- HumanLayer 的"简单开始"原则暗示了低锁定的可能性，但实践中一旦深度集成就难以迁移
目前没有任何文章讨论技术多样性作为系统韧性的角色。这是一个被忽视的系统级风险。
Related Concepts
- 相关概念：AI Agents、Transformer Architecture、Model Inference & Deployment、LLM Evaluation、Harness Engineering — The Evaluation Problem
- 相关实体：Nous Research、OpenAI
- 相关对比：Workflow vs Agent
Open Questions
- Harness Engineering 的方法论能否从 OpenAI 内部推广到更广泛的开发者社区？
- 没有手动代码的代码库在长期维护（团队更替、技术债务）中的表现如何？
- 自动化垃圾回收的最佳实践是什么？
- 人类"设计约束和方向"的角色会如何随代理能力提升而演变？
- 评估问题（行为正确性验证）是否有根本解法？还是只能渐进改善？
- 跨模型可移植的 harness 是否可能？model-harness 耦合是不可避免的吗？
- 技术栈是否会在 Agent 时代走向"高可驾驭性"平台（如 Java/Spring）的收敛？
Sources
- Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI Engineering Blog, Feb 11, 2026
- Harness Engineering (中文版) — OpenAI 工程博客
- Harness engineering for coding agent users — Birgitta Böckeler (Thoughtworks) on Martin Fowler Blog, Apr 2, 2026
- harness-engineering — Community learning archive and reference implementation (deusyu)
- Author: Ryan Lopopolo, Member of the Technical Staff at OpenAI