驾驭工程：为什么你的 AI 编程助手总在失控？

1. 引言：AI 写代码，为什么有人 10 倍提效，有人一地鸡毛？

2026 年初，OpenAI 公布了一个令人震惊的数据：他们的一个内部团队，仅 3 名工程师，在 5 个月内用 Codex 生成了约 100 万行可上线的产品代码——没有一行是手写的。这个产品有真实的内部用户和外部 Alpha 测试者，经历了完整的交付、部署、故障和修复流程。每位工程师平均每天合并 3.5 个 Pull Request，团队总共完成了约 1500 个 PR [1]。

与此同时，在技术社区的另一端，大量开发者的体验截然不同：让 AI 写的代码”看起来能跑”，但越改越烂；需求稍微一复杂就开始胡说八道；几轮迭代之后，代码库变成了一团无人敢碰的浆糊，最终只能推倒重来。

同样的模型，同样的工具，为什么结果天差地别？

很多人把 Code Agent 当成了自动驾驶——输入目的地，躺平等到站。但现实是，当前的 AI 编码助手更像一匹未经驯服的野马：力量惊人，速度极快，但如果没有缰绳、马鞍和跑道，它只会把你甩下来。

差距不在模型能力，而在于你是否建立了一套驾驭系统。

OpenAI 团队将这套系统称为 Harness [1]，Martin Fowler 网站上 Birgitta Böckeler 的深度分析文章 [2] 将其上升为一种工程方法论——Harness Engineering（驾驭工程）。本文将从”为什么翻车”出发，拆解这套方法论的核心思想，以及它对每一个使用 AI 写代码的开发者意味着什么。

2. 失控的根源：Code Agent 不是你以为的那样工作

在讨论如何驾驭之前，我们需要先理解”失控”到底发生在哪里。

2.1 大模型的本质局限

Code Agent 最容易被忽视的特性是它的信息边界。

OpenAI 团队在实践中总结了一条冷酷的事实：Agent 在运行时无法在上下文中访问的内容，对它来说就不存在 [1]。你的 Google Docs 里写了详细的架构设计？不存在。你在 Slack 里和同事讨论了三天的技术方案？不存在。你脑子里那个”这里应该用单例模式”的想法？更不存在。

对 Agent 来说，只有代码仓库本地的、已版本化的工件才是真实的——代码、Markdown 文档、配置文件、可执行的计划。其余一切都是虚空。

更危险的是，Agent 会忠实地复现代码库中已有的模式——包括那些不理想的模式。如果你的代码库里有三种不同风格的错误处理方式，Agent 会随机挑一种来用，而且觉得理所当然。随着时间推移，这种模式复现会导致不可避免的漂移和熵增。

此外，Agent 没有真正的长期记忆。每次任务启动，它都像一个刚入职的实习生：聪明、勤奋，但对项目的历史和上下文一无所知。

2.2 “偷懒”路径的典型翻车姿势

理解了这些局限，我们就能看清为什么很多人的 AI 编程体验如此糟糕：

姿势一：扔一句话就跑。 “帮我写一个用户管理系统。” Agent 收到这个需求后开始自由发挥——它可能给你一个完美运行但完全不符合你技术栈的实现，或者选择了一种你的团队从未使用过的架构模式。你不说，它就不知道。

姿势二：写一个巨大的指令文件。 有些人意识到了需要给 Agent 规则，于是写了一个几百行甚至上千行的 AGENTS.md，把能想到的所有规范都塞进去。OpenAI 团队踩过同样的坑——他们发现上下文是稀缺资源，巨大的指令文件会挤掉真正重要的任务、代码和相关文档。更致命的是，”当一切都’重要’时，一切都不重要了”，Agent 最终会进行模式匹配而非有意识地导航这些规则 [1]。

姿势三：不看生成的代码。 既然让 AI 写了，那看什么看？这是最危险的心态。缺乏验证意味着 bug、安全漏洞、性能问题都在悄悄积累。

姿势四：出问题就手动修补。 发现 Agent 写的代码有问题，就自己上手改。一周下来，你的时间全花在了清理”AI 残渣”上。OpenAI 团队也经历过这个阶段——他们曾经安排每周五（20% 时间）来手动清理 Agent 引入的不一致，但很快发现这根本无法扩展 [1]。

2.3 失败的本质

所有这些翻车姿势背后，指向同一个根因：不是模型不够强，是环境不够明确。

OpenAI 团队坦承：”早期进展比预期慢，原因不是 Codex 能力不足，而是我们没有为它提供足够清晰的工具、抽象层和内部结构。” [1] 当他们把精力从”让 Agent 更努力”转向”让环境更清晰”时，一切开始加速。

这就是驾驭工程的核心直觉：问题不在马，在缰绳。

3. 什么是驾驭工程？

驾驭工程（Harness Engineering）是一套系统化的方法，用于约束、引导和支撑 AI Agent 在大型代码库中自主工作。

这个术语来自 OpenAI 团队的实践总结。Harness 在英语中的本意是”马具/挽具”——不是要消灭马的力量，而是引导它、控制它，让它的力量为你所用。这个比喻精确地描述了人类与 AI 编码 Agent 之间应有的关系。

值得强调的是，驾驭工程并非从零开始的全新概念。你的工具链中可能已经有了它的雏形：预提交钩子、ESLint/Ruff 等 linter、CI/CD 流水线、ArchUnit 这样的结构测试框架。驾驭工程所做的，是把这些分散的实践系统性地升级为Agent 可理解、可执行的约束体系，并补充 Agent 特有的需求 [2]。

OpenAI 团队将 Harness 归纳为三大支柱 [1]：

  1. 上下文工程（Context Engineering） —— 让 Agent 读懂你的意图
  2. 架构约束（Architectural Constraints） —— 给 Agent 划定边界
  3. 垃圾收集（Garbage Collection） —— 持续对抗 Agent 引入的熵增

接下来逐一拆解。

4. 支柱一：上下文工程——你不说，Agent 就不知道

上下文工程是驾驭工程中最基础也最容易被低估的部分。它的核心命题很简单：你必须把 Agent 需要知道的一切，显式地、结构化地放进代码仓库。

4.1 代码仓库是唯一的真相来源

这是驾驭工程的第一条铁律。

既然 Agent 只能看到仓库里的东西，那么所有的架构决策、编码约定、产品意图、技术债务记录，都必须以版本化的方式存在于仓库中。OpenAI 团队将代码仓库定位为记录系统（System of Record）——不仅记录代码本身，还记录代码背后的决策和意图 [1]。

他们的文档结构是这样的：

AGENTS.md (约100行)     ← 内容目录，小而稳定的入口
ARCHITECTURE.md         ← 顶层领域地图
    ↓
docs/
    ├── design-docs/                        # 设计文档与核心理念
    │   ├── index.md                        # 设计文档索引
    │   ├── core-beliefs.md                 # 核心设计信念与原则
    │   └── ...
    ├── exec-plans/                         # 执行计划
    │   ├── active/                         # 进行中的计划
    │   ├── completed/                      # 已完成的计划
    │   └── tech-debt-tracker.md            # 技术债务追踪
    ├── generated/                          # 自动生成的文档
    │   └── db-schema.md                    # 数据库 schema 文档
    ├── product-specs/                      # 产品规范
    │   ├── index.md                        # 产品规范索引
    │   ├── new-user-onboarding.md          # 新用户引导流程
    │   └── ...
    ├── references/                         # 外部参考（llms.txt 格式）
    │   ├── design-system-reference-llms.txt  # 设计系统参考
    │   ├── nixpacks-llms.txt               # Nixpacks 构建工具文档
    │   ├── uv-llms.txt                     # uv 包管理器文档
    │   └── ...
    ├── DESIGN.md                           # 架构设计总览
    ├── FRONTEND.md                         # 前端开发约定
    ├── PLANS.md                            # 项目计划与路线图
    ├── PRODUCT_SENSE.md                    # 产品感知与用户体验指南
    ├── QUALITY_SCORE.md                    # 代码质量评分标准
    ├── RELIABILITY.md                      # 可靠性要求与 SLA
    └── SECURITY.md                         # 安全规范与最佳实践

这里的关键设计原则是渐进式披露（Progressive Disclosure）：Agent 从一个小而稳定的入口（AGENTS.md）开始，被引导到下一步该去哪里查看，而不是一开始就被海量信息淹没。

💡 现实世界的妥协： 对于大多数非 OpenAI 级别的团队，强行要求所有决策都必须立刻、结构化地录入仓库是不现实的。人类的工作流天然包含异步讨论和临场决策。不必一步登天，更务实的“驾驭”可能是利用 Agent 辅助将虚空转为现实——例如让 Agent 旁听 Slack 会议总结技术决策，并自动提交 PR 更新 decisions/ 文件夹。这种缓冲策略能有效避免陷入“文档地狱”的误解。

4.2 避免大型指令文件的陷阱

OpenAI 团队在这个问题上栽过跟头，总结了三个关键教训 [1]：

教训一：巨大的指令文件会适得其反。 上下文窗口是稀缺资源。一个几百行的 AGENTS.md 会挤掉 Agent 处理实际任务所需的空间，导致它错过关键约束或针对错误的约束进行优化。

教训二：过多指导等于没有指导。 当所有规则都标注为”重要”时，Agent 无法区分优先级，最终退化为模式匹配——形式上遵守了，实质上没有理解。

教训三：文档会腐烂。 一个庞大的规范手册会迅速变成陈旧规则的坟场。Agent 无法判断信息是否仍然有效，一旦人类停止维护，它就从帮助变成了干扰。更棘手的是，大型文档难以进行机械化检查——你无法轻松验证它的覆盖率、新鲜度和所有权。

解决方案就是上面提到的”内容目录 + 结构化记录系统”模式：入口文件保持精简，详细信息分散在可独立维护的小文档中，通过自动化工具检查交叉引用和结构正确性。

4.3 让 Agent 能”看见”运行时

静态的文档和代码只是上下文的一部分。OpenAI 团队进一步将动态的运行时信息也纳入了 Agent 的感知范围 [1]。

UI 可读性方面，他们将 Chrome DevTools 协议集成到了 Agent 的运行时中，让 Codex 能够启动应用程序实例、生成 DOM 快照和截图、执行导航操作。这意味着 Agent 可以复现用户报告的 bug、验证自己的修复是否有效、直接推理 UI 行为——而不仅仅是在代码层面猜测。

可观测性方面，每个工作目录（worktree）都配备了临时的可观测性堆栈，Agent 可以使用 LogQL 查日志、PromQL 查指标、TraceQL 查链路追踪。这让 Agent 能够理解”服务启动是否在 800ms 内完成”、”关键用户路径中的任何跨度是否超过两秒”这样的性能约束。

这些能力的叠加带来了一个重要的结果：Agent 可以持续工作超过 6 小时（通常在人类睡觉的时间），因为它不需要人类来告诉它”这个改动到底有没有效果”。

4.4 面向 Agent 可读性选择技术栈

上下文工程还有一个经常被忽视的维度：你选择的技术栈本身，也在塑造 Agent 的能力边界。

OpenAI 团队倾向于选择可以”完全内化于仓库中进行推理”的依赖和抽象。对 Agent 来说，”枯燥”的技术反而更好用——可组合性强、API 稳定、在训练数据集中表现良好 [1]。

一个具体的例子：团队没有引入通用的 p-limit 风格并发控制包，而是自己实现了一个带并发限制的 map 辅助函数。这个自建实现与 OpenTelemetry 仪表紧密集成、具备 100% 测试覆盖率、行为完全符合运行时预期。Codex 可以检查、验证、直接修改它的每一行代码。

这个选择看起来违背了”不要重复造轮子”的工程直觉，但在 Agent 的语境下，逻辑是成立的：有时让 Agent 重新实现一个功能子集，比让它绕过不透明的第三方库的上游行为更便宜、更可靠。

5. 支柱二：架构约束——不是限制自由，是让速度可持续

如果说上下文工程是让 Agent “看得见”，那么架构约束就是让 Agent “不走偏”。

5.1 为什么约束是前提而非奢侈品

在传统软件工程中，严格的架构约束通常是大团队才会投入的事情——几百人的工程组织才会认真考虑分层架构、依赖方向控制、结构测试。小团队往往觉得”太重了，以后再说”。

但 AI 时代翻转了这个逻辑。OpenAI 团队的经验表明：对编码 Agent 来说，架构约束不是后期优化，而是第一天就需要的先决条件。 没有约束，Agent 的速度越快，代码库的混乱就积累得越快，最终速度会断崖式下降 [1]。

这背后的逻辑很直白：限制解决方案空间，才能增加输出的信任度和可靠性。 你放弃了”生成任何东西”的灵活性，换来的是 Agent 在受限空间内高质量、高一致性地交付。

Birgitta Böckeler 在 Martin Fowler 网站上的分析文章中将这概括为一条核心洞察：”增加信任和可靠性，需要限制解决方案空间。” [2]

5.2 确定性规则 > 自然语言描述

驾驭工程的一个关键理念是：能用代码强制执行的约束，就不要用自然语言描述。

OpenAI 团队构建了大量的确定性工具来处理 Harness 中的约束——不仅仅是生成 Markdown 规则文件，而是自定义 linter、结构测试和 CI 作业。这些工具的一个巧妙设计是修复指令注入：在 lint 错误信息中直接嵌入 Agent 可理解的修复指导，让 Codex 能够在遇到违规时立即自我纠正，而不是困惑地猜测该怎么办 [1]。

他们的分层域架构模型是一个典型案例：

每个业务领域内的依赖方向（严格单向）：

Types → Config → Repo → Service → Runtime → UI
         ↓
     Providers（横切关注点入口）
         ↓
     认证、连接器、遥测、功能标志

依赖方向通过自定义 linter 和结构测试机械地强制执行——不是靠文档说”请遵守单向依赖”，而是代码层面直接禁止逆向引用。Agent 不需要”理解”为什么要这样做，它只需要在违规时收到明确的错误信息和修复指令。

💡 人机协作的张力与平衡： 过强的机械约束在纯 Agent-First 环境中非常有效，但在人机混合的开发团队中可能会引发人类的对抗心理（如“我就想临时写个脚本，却一堆报错”）。一个实用的妥协方案是引入“警告（Warning） vs 错误（Error）”的分级治理策略：对于 Agent 运行环境（如 CI/CD），约束是严格的 Error；而对于人类本地开发环境，约束可以是 Warning，仅在合并 PR 时强制。这种“对人宽容，对机严格”的策略更适合大多数团队的过渡期。

5.3 编码化人类的品味

架构约束不仅包括宏观的依赖方向，还包括微观的”品味”——代码风格、命名约定、日志格式等不变式。

OpenAI 团队将这些品味编码为自定义 lint 规则 [1]：

  • 结构化日志记录：禁止随意的 console.log
  • 命名约定：Schema 和类型须遵循统一命名规范
  • 文件大小限制：单文件不超过规定行数
  • 可靠性要求：特定平台须满足额外可靠性标准

一个重要的认知转变是：生成的代码不必符合人类的风格偏好。只要输出是正确的、可维护的、对未来的 Agent 运行清晰可读，就算达标。人类的品味通过审查评论、重构 PR 和 bug 修复的方式被捕获，然后编码到工具和规则中——一旦被捕获，就会持续应用于每一行代码。

这里有一个优雅的分层设计：中央层面强制执行边界（正确性、可重复性），本地层面允许自主权（解决方案的表达方式）。 这和领导大型工程平台组织的方式异曲同工——平台团队定义铁律，业务团队在铁律内自由发挥。

6. 支柱三：垃圾收集——与熵的持久战

即使有了完善的上下文和严格的约束，熵增仍然是不可避免的。驾驭工程的第三根支柱，是一套持续对抗熵增的机制。

6.1 不可避免的漂移

Agent 会复现代码库中已存在的模式——这一点前面已经讨论过。问题在于，随着代码量的增长，即使每个模式单独看都是合理的，它们的组合也可能产生不一致。再加上 Agent 偶尔引入的不均衡或不理想的模式，代码库会逐渐漂移，偏离预期的架构和风格。

OpenAI 团队最初的应对方式是安排人类工程师定期手动清理。他们很快发现，在 Agent 的高吞吐量下，手动清理完全无法扩展——你清理的速度永远赶不上 Agent 引入偏差的速度 [1]。

6.2 用 Agent 对抗 Agent 的熵

解决方案是用自动化对抗自动化。

他们建立了一套”垃圾收集”循环：定期运行一组后台 Codex 任务，扫描代码库中的偏差，更新质量等级，发起有针对性的重构 Pull Request。这些 PR 通常足够小和聚焦，大多数可以在一分钟内完成审查和自动合并 [1]。

💡 风险边界提示： 这种“一分钟内自动合并”展现了极高的系统信任度，但必须明确其前置条件——这需要你的测试金字塔极其稳固。正如上文提到 OpenAI 拥有高达 100% 的测试覆盖率。如果没有极高覆盖率的单元测试和严谨的契约测试，盲目模仿这种自动合并，很容易引发灾难性的生产事故。

这个机制也覆盖了文档维护：专职 linter 验证知识库的更新状况，CI 作业检查交叉链接和结构正确性，”doc-gardening” Agent 定期扫描过时文档并自动发起修复 PR。

这套系统的运作逻辑类似于编程语言中的垃圾回收（GC）：你不需要手动管理每一块内存的分配和释放，运行时会自动处理。同样地，你不需要手动追踪每一处代码漂移，后台 Agent 会持续扫描和修复。

6.3 技术债务如同高息贷款

OpenAI 团队用了一个生动的比喻：技术债务像高息贷款 [1]。你有两个选择：

  • 持续以小额偿还：每天发现并解决不良模式，在它们传播之前消灭
  • 让债务累积，再痛苦地解决：等到问题大到不可忽视时批量处理

在传统的低吞吐量环境中，后者可能还勉强可行。但在高 Agent 吞吐量的环境中——每位工程师每天 3.5 个 PR——让债务累积意味着灾难。债务的复利会迅速吞噬你从 Agent 获得的所有效率增益。

这也引出了一个更深层的观念转变：吞吐量改变了合并的理念。 在传统的低吞吐量环境中，我们倾向于”确保万无一失再合并”，因为等待成本低而纠错成本高。但在高 Agent 吞吐量的环境中，等式反转了——等待成本极高（阻塞了大量后续 PR），而纠错成本极低（Agent 可以快速修复大多数问题）。因此，合并策略从”最小化测试失败”变为”最小化合并阻塞”。

7. 对普通开发者的启示

读到这里，你可能会想：这是 OpenAI 的故事，他们有最好的模型和资源，跟我有什么关系？

关系比你想象的大。

7.1 审视你当前的”驾驭系统”

你现在就可以做一个快速诊断：

  • 你有预提交钩子吗？它们检查什么？
  • 你有自定义 linter 规则吗？还是只用默认配置？
  • 你的项目有 AGENTS.md 或类似的 AI 指令文件吗？它有多长？
  • 你的架构约定是写在文档里，还是通过代码强制执行的？
  • 当 Agent 写出不符合预期的代码时，你的第一反应是手动修改，还是思考”缺了什么约束”？

这些问题的答案，就是你当前”驾驭系统”的快照。大多数人会发现自己处于一个非常早期的阶段——有一些零散的工具，但远未形成系统。

7.2 从小处开始

好消息是，你不需要一步到位。OpenAI 的系统也是 5 个月迭代出来的，而非一夜之间从天而降。

核心循环其实很简单：

Agent 在某个任务上挣扎
    → 识别缺失的约束 / 文档 / 工具
        → 补充缺失的部分（最好让 Agent 自己来写）
            → 纳入体系
                → Agent 下次表现更好

OpenAI 团队的原话是：”当 Agent 挣扎时，我们将其视为信号：识别缺失的内容——工具、护栏、文档——并将其反馈到仓库中，始终让 Codex 自己编写修复程序。” [1]

这个循环的关键在于”让 Agent 自己修复”。一方面，这确保修复是 Agent 可理解的（因为它自己写的）；另一方面，这本身就是对 Agent 能力的测试——如果 Agent 连修复约束的代码都写不好，说明这个约束可能需要用不同的方式来表达。

7.3 接受角色转变

驾驭工程意味着开发者角色的根本性转变：从”写代码的人”到”设计环境的人”。

这并不意味着工程能力变得不重要——恰恰相反。设计一个好的驾驭系统，需要对架构、测试、自动化和软件工程原则有更深的理解。你不是在降低标准，而是在更高的层面应用严谨性。

OpenAI 团队描述了一个三阶段的演变 [1]：

  • 第一阶段：人类掌舵，Agent 执行具体编码任务
  • 第二阶段：人类的工作重心从编写代码转向设计环境和架构
  • 第三阶段：深度优先地构建能力——把大目标拆解为小模块，让 Agent 构建基础模块，再用这些模块解锁更复杂的任务

到第三阶段，当事情进展不顺时，答案不再是”让 Agent 再努力一点”，而是：”还需要什么样的能力？如何让这个能力对 Agent 既清晰可读又可强制执行？”

8. 展望：当驾驭系统成为基础设施

驾驭工程的影响不会止步于单个团队的实践。Birgitta Böckeler 在 Martin Fowler 网站上的分析中指出了几个值得关注的趋势 [2]。

8.1 Harness 可能成为新的服务模板

未来，团队可能不再从零开始构建驾驭系统，而是从一组针对常见应用拓扑的标准化 Harness 中选择起点——类似于今天的”黄金路径”服务模板。一个 Web 应用有一套 Harness，一个数据管道有另一套，一个移动端 BFF 有第三套。

8.2 技术栈将被”AI 友好性”重新筛选

AI 可能推动技术栈收敛。当”Agent 能否高效地在这个技术栈中工作”成为选型标准时，那些 API 稳定、文档完善、行为可预测的技术会获得优势。代码库结构也可能默认采用更容易被 Harness 维护的形式。

8.3 Pre-AI 与 Post-AI 的维护分野

对于已有大量代码的老项目，改造（retrofit）一套 Harness 可能因为熵太大而不值得投入。Böckeler 做了一个精准的类比：这就像在一个从未运行过静态分析的代码库中突然启用所有规则——告警会多到让整个工具变得无用 [2]。

这可能导致一个分野：新项目从一开始就在 Harness 的框架下构建，而老项目则停留在”人类为主、AI 辅助”的模式中。

9. 结论：不是 AI 不行，是你还没学会驾驭

回到开头的问题：为什么有人用 AI 写代码 10 倍提效，有人一地鸡毛？

答案现在应该清晰了。差距不在于你用了哪个模型、买了哪个工具的会员，而在于你是否建立了一套系统来约束 Agent 的输出空间、喂给它正确的上下文、持续清理它引入的熵增。

这套系统——驾驭工程——的三根支柱值得再次强调：

  • 上下文工程：把 Agent 需要知道的一切显式地、结构化地放进代码仓库，并让它能感知运行时状态
  • 架构约束：用确定性工具（linter、结构测试、CI）机械化地强制执行边界，而非依赖自然语言描述
  • 垃圾收集：用后台 Agent 持续扫描和修复偏差，像 GC 一样自动管理技术债务

这些实践的背后是一个更深层的认知：严谨性从未消失，它只是换了个地方。

Chad Fowler 将这种现象称为”Relocating Rigor”（严谨性的迁移）。在 AI Agent 时代，严谨性从手写每一行代码，迁移到了设计环境、反馈回路和控制系统。工具、抽象和反馈回路——这三者变得比以往任何时候都更重要。

更进一步地说，Harness Engineering 并非仅仅是在“伺候” AI，它本质上是在倒逼我们完成本该在 20 年前就做好的软件工程基本功，纠正我们过去因赶工期而欠下的工程债务。 AI 只是一个催化剂，它让我们无法再容忍模糊的架构、腐烂的文档和缺失的测试。

最后，如果你今天就想开始行动，从一件事做起：下次 Agent 写出不符合预期的代码时，不要手动修改它，而是问自己——我的驾驭系统里缺了什么？

10. 参考文献

[1] Ryan Lopopolo, “Harness engineering: leveraging Codex in an agent-first world,” OpenAI, 2026. [Online]. Available: https://openai.com/index/harness-engineering/

[2] Birgitta Böckeler, “Harness Engineering,” martinfowler.com, 2026. [Online]. Available: https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html