Harness Engineering：Agent-First 时代的软件工程实践

很多团队在用代码生成工具时，第一反应是“怎么让模型写得更快”。

这篇文章更有价值的地方在于，它把问题换成了：当“写代码”不再是工程师的主要工作时，工程团队应该把精力放在哪里？

OpenAI 团队做了一个极端实验：用 Codex 构建并发布一个真实可用的内部产品，约束是“人工不直接写代码”。结果是，他们在约 5 个月内完成了百万行规模代码，并声称整体速度约为手写方式的 10 倍。

文章反复强调一句话：Humans steer. Agents execute.

这不是“放手让 Agent 自由发挥”，而是把工程工作上移到三个更高杠杆层面：

• 设计可执行的任务边界
• 搭建 Agent 可理解、可验证的工作环境
• 建立持续反馈与纠偏回路

如果环境、规则和反馈回路不完整，模型能力再强也会在复杂任务里反复失速。

从传统工程视角看，这个约束似乎很反直觉。但它带来一个副作用：团队不能“临时手改”，只能把问题转化为可复用能力。

这迫使团队每次失败都问同一个问题：

1. 缺的到底是哪个能力？
2. 如何把它编码成 Agent 可复用的规则、工具或文档？

长期看，这种做法会形成复利：今天修的是一次故障，明天得到的是整类任务吞吐提升。

文章里最实用的一点，是“不要只让 Agent 看代码”。

团队给 Codex 接入了完整可观测与交互链路，包括：

• 每个 git worktree 可独立启动应用
• 可通过 Chrome DevTools 协议操作和验证 UI
• 可查询隔离环境内的日志、指标、链路数据

于是，Prompt 才能从“修下这个 bug”变成可验证目标，例如“启动耗时小于 800ms”或“关键链路 span 不超过 2 秒”。

这代表一种工程范式变化：把“可测试性”升级为“可代理性（agent legibility）”。

他们踩过一个典型坑：把 AGENTS.md 写成超长总手册。结果是上下文被稀释、规则变陈旧、难维护且难验证。

后来的做法是：

• AGENTS.md 只保留高层入口（目录）
• 详细知识沉淀在结构化 docs/ 中
• 用 lint/CI 机制检查文档新鲜度、交叉引用与结构正确性
• 用常驻“文档园丁”任务持续修复过期内容

对 Agent 来说，仓库里看不到的信息几乎等于不存在。把设计决策、计划、技术债和质量基线都版本化，才能支撑长期自主运行。

文档不会自动防止代码库熵增。文章给出的策略是：

• 严格定义分层与依赖方向
• 用结构化测试和自定义 lint 机械执行
• 把“口味偏好”尽量编码成可检查规则

他们强调的是“约束边界，而不是微观控制实现”。

这很像平台工程：中央层保障一致性和正确性，局部任务保留表达自由。只要输出正确、可维护、对后续 Agent 可读，就算达标。

当 Agent 吞吐显著高于人类注意力时，一些传统流程会变成瓶颈。

文中做法是减少阻塞式 gate，让 PR 生命周期更短，把部分问题留给后续快速修复，而不是在单个 PR 上长期阻塞。

这并不适合所有团队，但它提醒我们：流程设计必须与系统吞吐匹配。在高吞吐环境里，“等待成本”可能比“修复成本”更高。

不是“禁止人工写代码”，而是以下三个可迁移原则：

• 让 Agent 能读到它完成任务所需的全部上下文
• 让质量要求变成机器可执行的不变量
• 让反馈闭环在仓库内持续自动运行

如果只能先做一件事，我会建议从“仓库知识体系化”开始：把分散在聊天、会议和脑内的规则迁移到版本化文档，并给它配套验证机制。

把 AGENTS.md 控制在短文档，明确：

• 项目架构入口
• 规范入口
• 测试与验证入口
• 常见任务入口

优先沉淀三类信息：

• 业务边界与分层依赖
• 常见故障处理流程
• 评审中反复出现的“风格/可靠性要求”

至少落三类检查：

• 结构与依赖规则
• 文档完整性与时效性
• 关键路径性能/可靠性阈值

安排固定节奏的 Agent 任务扫描坏味道和技术债，生成小而快的修复 PR，让债务小额持续偿还，而不是季度爆发。

这篇文章传递的信号很明确：在 Agent-First 世界里，工程纪律没有消失，只是从“写代码”转移到了“设计系统”。

真正拉开差距的，不是谁会写更复杂的 prompt，而是谁更早把环境、文档、约束和反馈做成可复用的工程基础设施。