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 修复
- 文档不是写完就完了，而是被当作代码一样持续维护
落地建议：
- 在项目根目录建立 AGENTS.md（或 CLAUDE.md），写清架构分层、命名规范、模块边界
- 每个核心子模块放置局部指令文件，覆盖该模块特有的规则
- 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 的工作内容：
- 扫描并修复架构约束违规
- 清理未使用的代码、过时的接口
- 统一不一致的编码风格
- 修复文档与代码的偏差
落地建议：
- 设置定时任务，让 Agent 每天扫描代码库中的已知反模式
- GC 结果输出为 PR，人工快速审核后合并
- 监控技术债务指标的趋势，确保持续收敛而非发散
实践四：Agent Legibility — 让 Agent 能"看到"运行时
代码吞吐量上来后，瓶颈从"写代码"转移到"验证代码"。OpenAI 的突破点是让 Agent 直接访问运行时状态。
三大可观测性通道：
- UI 通道 — 通过 Chrome DevTools Protocol 实现，Agent 可以截取 DOM 快照、截图、操作页面验证
- 日志通道 — 通过 LogQL 查询接口实现，Agent 可以查询错误日志、追踪请求链路
- 指标通道 — 通过 PromQL 查询接口实现，Agent 可以查询延迟、吞吐量、错误率等指标
这意味着 Agent 可以处理这类任务：
"确保服务启动在 800ms 内完成"
Agent 可以自己启动服务、查询启动耗时指标、定位瓶颈、优化代码、再次验证 — 全程无需人工介入。
落地建议：
- 暴露结构化的日志查询接口，让 Agent 可以按 traceId、错误级别过滤
- 关键性能指标通过 API 可查询，而非只能在 Dashboard 上看
- 如果有前端项目，考虑集成浏览器自动化工具让 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 行为，截图结果可信
落地建议：
- 容器化你的应用，确保一条命令即可启动完整环境
- 使用 Docker Compose 或类似工具定义隔离的服务栈
- 数据库使用内存模式或独立实例，避免数据竞争
实践六：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 高效产出高质量代码的系统。 你设计的不是功能，而是约束、反馈和环境。
原文链接：https://juejin.cn/post/7615250753935048723
