你将学到什么

本指南从基本原理到实际应用全面涵盖了 Harness Engineering。你将了解它是什么，为什么 OpenAI 将其最大的内部项目押注于此，使其发挥作用的具体架构模式，以及如何将这些原则应用于你自己的 AI agent 工作流——无论你使用的是 Codex、Claude Code、OpenCode 还是任何其他 agent 系统。

Harness Engineering：2026年 AI Agent 开发全指南

如果说 2025 年是 AI agents 证明了它们可以编写代码的一年，那么 2026 年就是我们意识到 agent 本身不是难点——Harness（编排架构）才是的一年。

OpenAI 的 Codex 团队在 2026 年 2 月发布了一篇具有里程碑意义的博客文章，描述了他们如何构建了一个包含约 1,000,000 行代码的生产级应用程序，而其中没有一行代码是由人类亲手编写的。其秘诀不在于更好的模型或更聪明的 prompt，而在于他们围绕 agent 构建的系统——即 Harness。 Source

本指南将分解该实验以及随之而来的更广泛的 Harness Engineering 运动中的每一个原则、模式和实用技术。

第一部分：什么是 Harness Engineering？

定义

Harness Engineering 是一门设计整个环境的学科——包括脚手架、反馈循环、文档、架构约束和机器可读的构件——它允许 AI coding agents 以最小的人类干预，大规模地进行可靠、高质量的工作。

“Harness”一词源于马具：缰绳、马鞍、嚼子——这是一整套用于引导强大但不可预测的动物走向正确方向的设备。一匹不受控制的马是危险的，而一匹套上马具（harnessed）的马则造就了文明。这同样适用于 AI agents。 Source

为什么它在现在出现

从 prompt engineering 向 Harness Engineering 的转变反映了 AI 开发领域的成熟：

Source

推动这一转变的关键洞察是：agent 的能力已经足够强大，以至于瓶颈从模型质量转向了环境质量。一个在结构混乱的代码库中运行的最先进模型，其产出结果要逊色于一个在良好 Harness 环境中运行的普通模型。

第二部分：OpenAI Codex 实验

规模

在一次为期 5 个月的内部实验中，OpenAI 工程师构建并发布了一个包含约 1,000,000 行代码的 Beta 产品。该代码库涵盖了应用逻辑、基础设施、工具链、文档和内部开发工具。系统中不存在任何预先存在的、由人类编写的代码作为锚点。 Source

团队

该项目最初仅由 3 名工程师驱动 Codex。在 5 个月的时间里，大约有 1,500 个 pull requests 被开启并合并。随着团队增加到 7 名工程师，吞吐量反而增加了——这是一个违反直觉的结果，表明 Harness 本身是主要的生产力倍增器，而非个人技能。

OpenAI 估计，他们构建该系统所花费的时间大约只有手动编写代码所需时间的 1/10。 Source

初始脚手架

项目始于 Codex CLI 使用 GPT-5 生成的初始脚手架，并由一小组现有模板引导：

• 代码库结构和目录规范
• CI/CD 配置
• 代码格式化和 linting 规则
• 软件包管理器设置
• 应用程序框架样板

从这个种子开始，其他一切都通过 agent 驱动的开发而成长。

“周五问题”

在实验早期，团队发现了一个关键问题：他们每个周五（即 20% 的工程时间）都在清理他们所谓的“AI 废料（AI slop）”。这包括不一致的模式、重复的逻辑、命名错误的变量以及架构偏离。

这种模式无法扩展。解决方案是将他们的标准编码到 Harness 本身中，以便 agent 从一开始就生成更整洁的输出，并为残留的偏离构建自动化清理系统。

第三部分：五大核心原则

原则 1：代码库优先的知识

从 agent 的视角来看，任何它在运行时无法在上下文（in-context）中访问的内容实际上都不存在。存在于 Google Docs、聊天记录、Slack 消息或人们脑海中的知识对系统来说是不可见的。

这意味着所有知识必须作为代码库本地的、版本化的构件存在：

• 代码 —— 核心构件
• Markdown 文档 —— 架构决策、规范、入职指南
• Schemas —— API 合约、数据库架构、类型定义
• 可执行计划 —— agent 可以遵循的分步任务分解
• 配置 —— linter 规则、CI 流水线、格式化标准

团队意识到，随着时间的推移，他们需要将越来越多的上下文推入代码库。每当 agent 因为缺乏上下文而犯错时，修复方法不是写更好的 prompt，而是将该上下文添加到代码库中。 Source

实际应用：

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

原则 2：黄金原则

黄金原则（Golden Principles）是直接编码在代码库中的、具有主见且机械化的规则，它们能让代码库对未来的 agent 运行保持清晰和一致。它们不是理想化的指南，而是强制性的约束。

OpenAI 实验中的例子：

1. 优先使用共享工具包而非手写辅助函数 —— 集中不变性，以便在需要更改行为时，只需在一个地方更改。
2. 不要以 YOLO 风格探测数据 —— 验证边界或依赖类型化的 SDK，这样 agent 就不会意外地基于猜测的数据形状进行构建。
3. 一个概念，一个文件 —— 每个文件应代表一个单一概念，使 agent 更容易找到并修改正确的位置。
4. 显式优于隐式 —— 避免那些需要 agent 具备“部落知识”才能理解的神奇行为。

Source

这些原则不仅仅是文档。它们通过以下方式强制执行：

• Linter 规则 —— 自定义 linters（本身由 Codex 生成）来标记违规行为。
• 结构化测试 —— 验证架构合规性的测试。
• CI 门控 —— 违反黄金原则的 pull requests 会被自动拒绝。

原则 3：具有机械化执行力的分层架构

OpenAI 项目中的每个业务领域都被划分为一组固定的分层，并具有严格验证的依赖方向：

Types → Config → Repo → Service → Runtime → UI

依赖关系仅单向流动。UI 组件可以依赖 Runtime 和 Service，但 Service 绝不能从 UI 导入。Repo 可以依赖 Config 和 Types，但绝不能依赖 Service。 Source

这些约束通过机械化手段强制执行：

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

结构化测试验证合规性并防止违反模块化分层。这不是建议——而是由 CI 强制执行。每一个 pull request，无论是人类还是 agent 创建的，都必须通过这些测试。

原则 4：自动化垃圾回收

即使有黄金原则和结构化执行，agent 生成的代码也会随着时间产生偏离。OpenAI 团队通过实施自动化垃圾回收解决了这个问题——这是一些循环运行的后台任务：

1. 在整个代码库中扫描偏离黄金原则的情况。
2. 根据合规性得分更新每个模块的质量等级。
3. 开启针对性的重构 pull requests，修复特定类别的偏离。

这通过一个持续运行的系统取代了手动的“周五清理”。垃圾回收器本身由 Codex agents 驱动，创建了一个自我维护的循环。 Source

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

原则 5：可执行计划

在 agent 编写代码之前，它们先编写计划。这些计划不是非正式的笔记——它们是结构化的、可执行的文档，规定了：

• 目标：任务要完成什么。
• 要修改的文件：agent 将触及的文件的明确列表。
• 依赖项：此项工作依赖的其他任务或模块。
• 验收标准：如何验证工作已完成。
• 约束条件：绝不能违反的架构规则。

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

计划以 markdown 文件形式存在于代码库中，受版本控制，并且可以在执行前进行评审——这为人类在意图和实现之间提供了一个检查点。

第四部分：Codex Agent 循环

理解 Codex agent 循环如何在 Harness 中运行对于有效的 Harness Engineering 至关重要。

循环架构

OpenAI 在其配套博客文章《展开 Codex agent 循环》中发布了 Codex agent 循环的详细分解。 Source 该循环遵循以下周期：

读取上下文 → 计划 → 执行 → 验证 → 提交（或重试）

每一次迭代：

1. 读取上下文：agent 从代码库中读取相关文件、文档、schemas 和任务计划。
2. 计划：基于上下文，agent 决定做出哪些更改。
3. 执行：agent 编写或修改代码。
4. 验证：Harness 对更改运行测试、linters 和结构化检查。
5. 提交或重试：如果验证通过，agent 提交。如果失败，agent 读取错误输出并重试。

Harness 的作用是使第 1 步和第 4 步的信息尽可能丰富。agent 读取的上下文越多，其计划就越好。验证反馈越具体，它收敛到工作解决方案的速度就越快。

App Server Harness

在《解锁 Codex Harness：我们如何构建 App Server》一文中，OpenAI 描述了驱动 agent 循环的具体基础设施。 Source App Server 提供：

• 为每个 agent 任务提供沙盒执行环境。
• 预配置工具访问（文件系统、终端、浏览器）。
• 从代码库构件中自动注入上下文。
• 流式验证反馈，以便 agent 可以实时看到测试失败。

第五部分：将 Harness Engineering 应用于你的团队

快速开始：最小可行 Harness

你不需要复制 OpenAI 的整个基础设施就能从 Harness Engineering 中受益。从这些基础要素开始：

第 1 步：创建 ARCHITECTURE.md

在代码库根目录下，以机器可读的格式记录项目的架构规则。包括：

• 模块边界和允许的依赖关系
• 命名规范
• 文件组织规则
• 测试要求

由于 agent 在做出更改前会读取此文件，仅这一个文件就能显著提高 agent 的输出质量。

第 2 步：添加结构化测试

编写验证架构规则的测试。这些测试不检查业务逻辑——它们检查代码是否被正确组织：

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

第 3 步：配置 CI 验证

确保你的 CI 流水线对每一个 pull request 运行结构化测试、linters 和类型检查——包括由 agent 创建的那些。agent 应该看到与人类开发人员相同的验证输出。

第 4 步：在 Agent 执行前编写任务计划

在要求 agent 实现某项功能之前，编写一份结构化的计划文档，指明要修改的文件、要遵循的约束和验收标准。将这些计划存储在你的代码库中。

第 5 步：设置自动化清理

实施每周或每晚运行的 CI 任务，扫描代码库中偏离文档标准的情况，并创建集中的重构 PRs。

选择你的 Agent 系统

无论你使用哪种 agent，Harness Engineering 原则都适用：

Harness 存在于你的代码库中，而不是你的 agent 中。这意味着你可以切换 agent 而不会损失在 Harness 上的投入。

从单个 Agent 扩展到多个

OpenAI 的实验证明，Harness Engineering 能够实现并行的 agent 执行。由于 Harness 强制执行了架构边界，多个 agent 可以同时在代码库的不同部分工作而不会产生冲突。

并行 agent 执行的关键要求：

1. 清晰的模块所有权 —— 每个 agent 在定义的边界内工作。
2. 模块间的类型化接口 —— agent 可以针对接口编写代码，而无需了解实现细节。
3. 合并冲突预防 —— 任务范围被限定，以尽量减少文件重叠。
4. 集中式验证 —— 所有 agent 提交到同一个 CI 流水线。

第六部分：常见陷阱与反模式

反模式 1：将 Agent 当作 Harness

Agent 不是 Harness。Harness 是 agent 运行的环境。要求更聪明的模型来弥补结构混乱的代码库是错误的方法。应修复环境，而非 prompt。

反模式 2：文档放错地方

如果你的架构决策存在于 Confluence、Notion 或 Google Docs 中，agent 就无法看到它们。修复方法很简单但需要纪律：将所有与开发相关的文档移入代码库。

反模式 3：手动清理而非自动化执行

如果你花费大量时间清理 agent 生成的代码，你需要的是更好的执行机制，而不是更多的清理环节。每一个重复出现的清理任务都应该变成 linter 规则、结构化测试或自动化重构任务。

反模式 4：过度约束

过于僵化的 Harness 会阻止 agent 找到创造性的解决方案。目标是约束架构，而非实现。告诉 agent 它们可以修改哪些模块以及允许哪些依赖项，但让它们自己决定如何在这些边界内实现逻辑。

反模式 5：忽视 Agent 的反馈

当 agent 反复在某些任务上失败时，失败通常预示着 Harness 存在漏洞，而非 agent 的局限。跟踪失败模式，并利用它们来改进文档、结构化测试或架构约束。

第七部分：Harness Engineering 的未来

Martin Fowler 的观点

Martin Fowler 在其博客上发表了对 Harness Engineering 的分析，指出它代表了软件团队运作方式的根本转变。这一学科借鉴了数十年的软件工程最佳实践——持续集成、架构决策记录、依赖注入——但为了 agent 驱动的世界对其进行了重新利用。 Source

HumanLayer 框架

HumanLayer 团队发表分析称 Harness Engineering 是一个“能力问题（skill issue）”——他们认为设计有效 Harness 的能力将成为高效工程团队与挣扎型团队之间的主要分水岭。 Source

这对开发人员意味着什么

Harness Engineering 并没有取代开发人员的技能，而是重新定向了它。资深工程师不再是编写代码，而是设计能让 agent 编写好代码的系统。重要的技能从实现转向了架构，从编码转向了系统设计，从编写测试转向了设计测试框架。

对于构建应用程序的团队，像 ZBuild 这样的平台已经将 Harness Engineering 原则整合到了他们的应用生成器工作流中。ZBuild 不再要求开发人员从头开始设计自己的 Harness，而是提供了预配置的架构模式、依赖管理和验证系统，引导 AI agents 产出高质量的结果——让开发人员专注于产品决策而非基础设施。

三个愿景

展望未来，Harness Engineering 可能会经历三个阶段的演变：

1. 近期 (2026)：团队采用代码库优先的文档、结构化测试和黄金原则。Agent 辅助开发成为 Harness 良好项目的标准实践。

2. 中期 (2027)：Harness 生成本身变得由 agent 驱动。Agent 分析现有代码库，并根据观察到的模式提出 Harness 配置——如 linter 规则、结构化测试、依赖边界。

3. 长期 (2028+)：Harness 变得具有自适应性。它们不再是静态规则，而是根据 agent 生成代码的结果进行演变，在 agent 频繁出错的领域自动收紧约束，在它们持续成功的领域放宽约束。

第八部分：实践清单

使用此清单来评估你团队的 Harness Engineering 成熟度：

基础 (从这里开始)

• 代码库根目录存在 ARCHITECTURE.md
• 代码格式化已自动化 (Prettier, Black, gofmt)
• 每一个 pull request 都会运行 Linting
• 强制执行类型检查 (TypeScript strict, mypy 等)

中级

• 结构化测试验证依赖边界
• 黄金原则已文档化且可由机器强制执行
• 在 agent 执行前编写任务计划
• Agent 生成的 PR 与人类 PR 经过相同的 CI 流程

高级

• 定期运行自动化垃圾回收
• 多个 agent 可以并行工作而无冲突
• 跟踪 agent 失败模式并用于改进 Harness
• Harness 本身受版本控制，并像代码一样经过评审

专家级

• Agent 生成 Harness 的部分内容（linter 规则、结构化测试）
• 自动为每个模块分配质量等级
• 基于 agent 成功率，通过数据驱动 Harness 的改进
• 团队每位工程师每周交付的代码量比采用 agent 前显著增加

结论

Harness Engineering 不是一种昙花一现的时尚。它是软件工程在 AI agent 能够编写生产代码但需要结构化环境才能做好的时代的自然演进。OpenAI 的百万行实验在大规模范围内证明了这一概念，他们阐明的原则——代码库优先的知识、黄金原则、分层架构、自动化垃圾回收和可执行计划——适用于任何规模的团队。

在 2026 年掌握 Harness Engineering 的团队将比那些仅将 AI agents 视为高级自动补全的团队交付更快、保持更高的代码质量，并能更有效地扩展。Agent 是马，而 Harness 是使其发挥作用的关键。

来源

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote