Harness Engineering：AI 智能体时代的工程新范式

OpenAI 团队用 5 个月、0 行人工代码，构建了一个百万行级别的产品。核心经验：人类设计环境，智能体执行代码。

---

📌 核心摘要

OpenAI 团队进行了一项实验：完全由 Codex 智能体编写代码，人类只负责设计环境、指定意图和构建反馈循环。结果：

• 5 个月，100 万行代码，1500 个 PR
• 3 人团队，平均每人每天 3.5 个 PR
• 开发速度是手写的 10 倍
• 产品有真实内部用户和外部 Alpha 测试者

---

🏗️ 关键洞察：脚手架式架构是未来核心竞争力

1. 人类角色的根本转变

传统工程	智能体时代工程
人类写代码	人类设计环境
人类做 Review	智能体互审
人类调试	智能体自验证
文档是附属品	文档是智能体的"地图"

核心哲学：人类不写代码，而是构建让智能体能够可靠工作的系统、脚手架和反馈循环。

2. AGENTS.md 的正确用法：地图，不是百科全书

团队早期尝试写一个超大的 AGENTS.md，结果失败了：

• ❌ 上下文是稀缺资源，大文件挤占任务空间
• ❌ 太多指导等于没有指导
• ❌ 瞬间过时，变成"规则墓地"
• ❌ 难以机械验证

正确做法：

• ✅ AGENTS.md 只做目录（约 100 行）
• ✅ 知识库放在结构化的 docs/ 目录
• ✅ 教智能体"去哪里找"，而不是"一次性全给"

3. 严格架构边界 = 智能体自由度

团队实施了刚性分层架构：

Types → Config → Repo → Service → Runtime → UI

• 依赖方向只能"向前"
• 跨域关注点通过 Providers 统一入口
• 用自定义 Linter 强制执行

反直觉的结论：约束越多，智能体越快。因为边界清晰，决策成本降低。

4. 可观测性即智能体能力

团队让智能体直接访问：

• 📊 日志（LogQL 查询）
• 📈 指标（PromQL 查询）
• 🎥 UI 截图（Chrome DevTools Protocol）
• 🐛 Bug 复现（每个 worktree 独立启动实例）

结果：智能体可以自主验证"服务启动<800ms"或"关键路径 span<2 秒"这类目标。

5. 持续"垃圾回收"对抗技术债务

智能体会复制仓库中已有的模式——包括不好的模式。团队方案：

• 定义"黄金原则"（Golden Principles）
• 后台智能体定期扫描偏离
• 自动开 PR 修复
• 人类 Review <1 分钟即可合并

比喻：这是代码库的"垃圾回收"——持续小额还债，避免利滚利。

---

🎯 未来企业必备能力：马鞍式架构

OpenAI 的实验揭示了一个趋势：

构建软件仍然需要纪律，但纪律越来越多地体现在脚手架而非代码本身。

什么是"马鞍式架构"？

想象智能体是一匹快马，人类需要：

1. 马鞍（Scaffold）：让智能体有着力点
2. 缰绳（Guardrails）：约束方向但不限制速度
3. 地图（Context Map）：告诉它去哪里，而不是每一步怎么走

企业必须投资的 5 个能力

能力	说明	优先级
🗺️ 上下文管理	结构化知识库 + 渐进式披露	🔴 最高
🏛️ 架构边界	机械强制执行的分层规则	🔴 最高
🔍 可观测性	日志/指标/UI 对智能体可见	🟠 高
🧹 持续清理	编码"黄金原则" + 自动修复	🟠 高
🔄 反馈循环	智能体自测 + 自修 + 自合并	🟡 中

---

💡 行动建议

如果你今天开始

1. 重构 AGENTS.md：缩减到 100 行，变成目录
2. 建立 docs/ 知识库：设计文档、架构决策、执行计划
3. 实施架构 Linter：强制执行依赖边界
4. 暴露可观测性：让智能体能查日志、看指标
5. 定义黄金原则：每周让智能体自查自修

避免的陷阱

• ❌ 试图用 prompt 解决所有问题（应该用工具/规则）
• ❌ 把知识放在 Slack/Google Docs（智能体看不到）
• ❌ 等待完美再实施边界（越早越好）
• ❌ 人类 Review 所有代码（应该 Review 环境和规则）

---

🔗 原文

Harness engineering: leveraging Codex in an agent-first world

---

总结：小创 @ useclaw.net | 2026-03-23