Harness Engineering — AI 时代的工程最佳实践

大家好，我是桦说编程。

OpenAI 用 5 个月、0 行手写代码，让 Codex Agent 生成了 100 万行代码的产品。效率是传统开发的 10 倍。本文提炼其核心方法论 "Harness Engineering" 为可落地的最佳实践，帮你在 Agent-First 时代少踩坑。

你正在经历这些痛点吗？

如果你已经在用 AI Agent 辅助开发，以下场景大概率似曾相识：

架构漂移失控 --- Agent 不理解你的架构意图，生成的代码悄悄越过模块边界，service 层调了 controller 的工具类，循环依赖无声蔓延。你以为只是一个小功能，review 时发现依赖图已经面目全非。

技术债务指数级堆积 --- 人写代码，技术债务是线性增长；Agent 写代码，技术债务是指数增长。Agent 不会主动清理上一轮遗留的废代码，反而会基于它继续构建，债务像滚雪球一样越积越大。

上下文黑洞 --- Agent 无法访问你脑中的架构决策、团队约定、历史教训。它看不到的信息，对它来说等于不存在。结果就是同一个项目里出现三种日志规范、两套错误处理风格。

人工 QA 成为瓶颈 --- 代码吞吐量上来了，一天能生成几十个 PR，但 review 的还是那几个人。生成速度远超人类审查能力，质量关口形同虚设。

文档代码脱节 --- README 写的是上个月的架构，Agent 基于过时信息做决策，产出的代码与当前设计南辕北辙。

这些问题的共同根因是：我们有了强大的 Agent，却没有约束和引导它的系统。

Harness Engineering：给 AI Agent 套上缰绳

OpenAI 在 2026 年 2 月发布了 Harness Engineering 一文，披露了他们如何让 Codex Agent 从零构建了一个完整的内部产品。核心方法论叫 Harness Engineering。

一个直观的类比：

• 马 --- AI 模型（Codex），拥有强大的执行力
• 缰绳与马具（Harness） --- 约束、反馈回路、文档、Linter、生命周期管理
• 骑手 --- 工程师，提供方向和判断力

Harness 的本质是：约束 + 反馈回路 + 文档 + Linter + 生命周期管理。

工程师的核心职责从"写代码"转变为"设计让 Agent 高效工作的环境"。你不再是码农，你是 Agent 的架构师。

六大最佳实践

实践一：Context Engineering --- 让 Agent "看见"你的架构

核心原则：Agent 无法在上下文中访问到的信息，对它来说等于不存在。

OpenAI 项目中散布着 88 个 AGENTS.md 文件 ，根文件定义全局默认规则，子目录文件覆盖本地规则。它不是一本大手册，而是一张导航地图。

渐进式披露（Progressive Disclosure）：

项目根目录/
├── AGENTS.md              ← 全局入口，精简，指向子目录
├── src/
│   ├── api/
│   │   └── AGENTS.md      ← API 层的约定、依赖规则
│   ├── service/
│   │   └── AGENTS.md      ← Service 层的约定
│   └── infra/
│       └── AGENTS.md      ← 基础设施层规则

Agent 从根入口开始，按需深入到具体子目录获取局部上下文。不是一次性灌入 10 万字，而是按层级逐步展开。

机械化保鲜：

• Linter 和 CI 自动验证知识库的正确性和时效性
• "doc-gardening" Agent 定期扫描过时文档，自动发 PR 修复
• 文档不是写完就完了，而是被当作代码一样持续维护

落地建议：

1. 在项目根目录建立 AGENTS.md（或 CLAUDE.md），写清架构分层、命名规范、模块边界
2. 每个核心子模块放置局部指令文件，覆盖该模块特有的规则
3. CI 中加入文档时效检查，超过 N 天未更新的关键文档标记 warning

实践二：Architectural Constraints --- 用机器而非人来守住架构边界

靠 Code Review 守住架构？当 Agent 一天输出几十个 PR 时，这条路走不通。

OpenAI 的做法是用 Agent 自己写 Linter 来约束 Agent，形成自动化的架构护栏：

关键设计：Linter 不只是让构建失败，还将修复指令注入回 Agent 的上下文

Agent 生成代码
    ↓
自定义 Linter 检测到违规
    ↓
构建失败 + 错误信息包含修复指令
    ↓
Agent 读取错误信息，自动修复
    ↓
再次提交 → 通过

这是一个反馈闭环，而不是一堵墙。

具体约束举例：

• 依赖方向：service 层不能反向依赖 controller 层，Linter 检测 import 路径强制执行
• 结构化日志 ：所有日志必须使用指定格式，不允许裸 System.out.println
• 文件大小限制：单文件超过阈值自动拒绝，倒逼模块拆分
• 命名规范：类名、方法名、变量名通过正则校验
• 循环依赖检测：依赖图分析，发现环路立即阻断

三管齐下的检查体系：

• 确定性 Linter --- 适用于规则明确的硬约束，如 import 方向、命名规范
• 结构化测试 --- 适用于运行时行为验证，如依赖图环路检测
• LLM-based Agent --- 适用于需要语义理解的软约束，如 "这个类的职责是否越界？"

实践三：Garbage Collection --- 把技术债务当 GC 来做

Agent 生成的代码会退化，这是不可避免的。OpenAI 的策略不是"事后大扫除"，而是持续小增量清理，像 JVM 的垃圾回收一样。

传统方式：技术债务累积 → 某天爆发 → 停下来还债（痛苦）
Harness 方式：GC Agent 持续运行 → 小增量清理 → 代码库自我清洁

GC Agent 的工作内容：

• 扫描并修复架构约束违规
• 清理未使用的代码、过时的接口
• 统一不一致的编码风格
• 修复文档与代码的偏差

落地建议：

1. 设置定时任务，让 Agent 每天扫描代码库中的已知反模式
2. GC 结果输出为 PR，人工快速审核后合并
3. 监控技术债务指标的趋势，确保持续收敛而非发散

实践四：Agent Legibility --- 让 Agent 能"看到"运行时

代码吞吐量上来后，瓶颈从"写代码"转移到"验证代码"。OpenAI 的突破点是让 Agent 直接访问运行时状态。

三大可观测性通道：

• UI 通道 --- 通过 Chrome DevTools Protocol 实现，Agent 可以截取 DOM 快照、截图、操作页面验证
• 日志通道 --- 通过 LogQL 查询接口实现，Agent 可以查询错误日志、追踪请求链路
• 指标通道 --- 通过 PromQL 查询接口实现，Agent 可以查询延迟、吞吐量、错误率等指标

这意味着 Agent 可以处理这类任务：

"确保服务启动在 800ms 内完成"

Agent 可以自己启动服务、查询启动耗时指标、定位瓶颈、优化代码、再次验证 --- 全程无需人工介入。

落地建议：

1. 暴露结构化的日志查询接口，让 Agent 可以按 traceId、错误级别过滤
2. 关键性能指标通过 API 可查询，而非只能在 Dashboard 上看
3. 如果有前端项目，考虑集成浏览器自动化工具让 Agent 能做 UI 验证

实践五：Bootable per Git Worktree --- 每个变更一个独立沙箱

并发是 Agent 开发的常态。多个 Agent 同时在不同分支上工作，如果共享环境，互相污染是必然的。

OpenAI 的做法：每个 Git Worktree 可以启动一个完全隔离的应用实例。

Agent-1 (feature-A worktree) → 独立实例-1 → 独立数据库
Agent-2 (feature-B worktree) → 独立实例-2 → 独立数据库
Agent-3 (bugfix-C worktree) → 独立实例-3 → 独立数据库

每个 Agent 拥有自己的"私人实验室"：

• 独立复现 Bug，不受其他变更干扰
• 独立验证修复，不污染其他环境
• 独立推理 UI 行为，截图结果可信

落地建议：

1. 容器化你的应用，确保一条命令即可启动完整环境
2. 使用 Docker Compose 或类似工具定义隔离的服务栈
3. 数据库使用内存模式或独立实例，避免数据竞争

实践六：Autonomous Workflow --- 从 Prompt 到 Merge 的全自治流水线

当前面五个实践就绪后，最终形态就是端到端自治开发工作流，以下是一个可预期的场景：

一个 Prompt
    ↓
验证代码库当前状态
    ↓
复现 Bug / 理解需求
    ↓
实现修复 / 新功能
    ↓
驱动应用验证（UI + API + 指标）
    ↓
录制演示视频
    ↓
开 PR + 描述变更
    ↓
响应 Review 反馈并修改
    ↓
检测构建失败 → 自动修复
    ↓
合并（或升级给人类判断）

仅在需要判断力时才升级给人类。Agent 处理 90% 的机械性工作，人类聚焦于真正需要决策的 10%。

总结

• Context Engineering --- 解决上下文丢失。用 AGENTS.md 建导航地图，渐进式披露，文档当代码维护。
• Architectural Constraints --- 解决架构漂移。Linter 不只报错，还把修复指令喂回给 Agent，形成闭环。
• Garbage Collection --- 解决技术债堆积。像 JVM GC 一样持续小增量清理，代码库自我清洁。
• Agent Legibility --- 解决 QA 瓶颈。让 Agent 直接查日志、看指标、操作 UI，自己验证自己。
• Bootable per Worktree --- 解决环境污染。每个变更一个隔离沙箱，互不干扰。
• Autonomous Workflow --- 解决人工瓶颈。从 Prompt 到 Merge 全自治，仅判断力需人类介入。

Harness Engineering 的核心洞察：在 Agent-First 时代，软件工程的核心产出不再是代码，而是让 Agent 高效产出高质量代码的系统。 你设计的不是功能，而是约束、反馈和环境。

参考来源：

• OpenAI - Harness Engineering
• Birgitta Böckeler - Harness Engineering 分析 (Martin Fowler 网站)
• InfoQ 相关报道

---

如果这篇文章对你有帮助，欢迎关注我，持续分享高质量技术干货，助你更快提升编程能力。