Harness engineering: 在 Agent 优先的世界中利用 Codex

来源：Hacker News / Ryan Lopopolo (Member of the Technical Staff) 时间：2025年8月（基于文中提到的首次提交时间）

背景

在过去五个月里，Ryan Lopopolo 及其团队进行了一项极具实验性的工程实践：构建并交付一个内部 Beta 版本的软件产品，其代码库中 0 行由人类手动编写的代码。

该产品的日常内部用户和外部 Alpha 测试者正在使用它。它经历着标准的软件生命周期：发布、部署、故障以及修复。但与众不同的是，每一行代码——包括应用逻辑、测试、CI 配置、文档、可观测性设置以及内部工具——均由 Codex 生成。团队估算，这一过程耗时仅为手动编写代码的十分之一。

这一实验的核心约束在于：人类负责引导（Steer），Agent 负责执行（Execute）。

团队故意设定这一约束，旨在探索如何使工程速度提升数个数量级。在短短几周内，他们交付了最终达到百万行规模的代码。为了达成这一目标，团队必须重新定义软件工程的核心职能：从“编写代码”转变为“设计环境、明确意图以及构建反馈回路”，从而让 Codex Agent 能够可靠地工作。

核心内容

1. 从零开始的构建与规模

2025年8月底，第一个提交记录落入了一个空仓库。初始脚手架（包括仓库结构、CI 配置、格式化规则、包管理器设置及应用框架）由 Codex CLI 基于 GPT-5 生成，并参考了少量现有模板。甚至连指导 Agent 如何在仓库中工作的 AGENTS.md 文件本身也是由 Codex 编写的。

五个月后，该仓库包含了约 100 万行代码，涵盖应用逻辑、基础设施、工具、文档及内部开发者实用程序。在此期间，一个小团队（最初仅 3 名工程师，后扩展至 7 名）驱动 Codex 打开了约 1,500 个 Pull Request (PR) 并完成合并。

• 吞吐量：平均每位工程师每天处理 3.5 个 PR。
• 增长趋势：令人惊讶的是，随着团队从 3 人扩展到 7 人，吞吐量不降反升。
• 真实性：这并非单纯的输出堆砌，产品已被数百名内部用户（包括每日活跃的高级用户）实际使用。

2. “无手动代码”哲学的实践

团队的核心哲学是“不手动编写任何代码”。这种缺乏人类直接编码的做法，将工程工作重心转移到了系统、脚手架和杠杆效应上。

早期进展慢于预期，并非因为 Codex 能力不足，而是因为环境定义不足（Underspecified）。Agent 缺乏实现高层目标所需的工具、抽象和内部结构。因此，工程师的主要工作变成了“赋能 Agent 进行有用工作”。

具体实践包括：

• 深度优先工作法：将大目标拆解为小块（设计、编码、审查、测试等），提示 Agent 构建这些模块，进而解锁更复杂的任务。
• 故障修复逻辑：当任务失败时，人类不会简单地要求“再试一次”，而是介入分析：“缺失什么能力？如何使其对 Agent 既清晰又可执行？”
• 基于 Prompt 的交互：人类通过 Prompt 描述任务，运行 Agent，并允许其打开 PR。为了推动 PR 完成，团队指示 Codex 在本地审查自身更改，并在本地和云端请求其他特定 Agent 的审查。Agent 需响应人类或 Agent 的反馈，并在循环中迭代，直到所有 Agent 审查者满意（即所谓的 "Ralph Wiggum Loop"）。
• 工具集成：Codex 直接使用标准开发工具（如 gh、本地脚本及仓库嵌入的技能）来收集上下文，无需人类手动复制粘贴到 CLI。

3. 突破瓶颈：从代码生成到系统可观测性

随着代码吞吐量的增加，瓶颈转移到了人类 QA（质量保证）能力上。由于人类的时间和注意力是固定且稀缺的资源，团队致力于通过增强 Agent 的能力来突破这一瓶颈，具体做法是让应用 UI、日志和应用指标本身对 Codex 变得“可读”。

• UI 自动化测试：

  • 使应用支持按 Git worktree 启动，以便 Codex 为每个更改启动并驱动一个实例。
  • 将 Chrome DevTools Protocol 接入 Agent 运行时，创建用于处理 DOM 快照、截图和导航的技能。
  • 这使得 Codex 能够直接复现 Bug、验证修复方案并推理 UI 行为。

• 可观测性集成：

  • 日志、指标和追踪通过一个临时的本地可观测性栈暴露给 Codex。
  • Codex 在完全隔离的环境中工作（包括其日志和指标），任务完成后环境即销毁。
  • Agent 可以使用 LogQL 查询日志，使用 PromQL 查询指标。
  • 在此背景下，诸如“确保服务启动在 800ms 内完成”或“这四个关键用户旅程中没有任何 Span 超过两秒”等提示变得具有可操作性。

团队经常观察到单个 Codex 运行在一个任务上长达六小时以上（通常发生在人类睡眠期间）。

4. 上下文管理：从“百科全书”到“目录”

在大型复杂任务中，上下文管理是使 Agent 有效的最大挑战之一。团队学到的早期教训是：给 Codex 一张地图，而不是一本 1000 页的操作手册。

团队曾尝试“单一巨型 AGENTS.md”方法，但遭遇了可预测的失败：

1. 上下文稀缺：巨大的指令文件会挤占任务、代码和相关文档的空间，导致 Agent 忽略关键约束或优化错误的目标。
2. 指导失效：当一切都被标记为“重要”时，就没有重点。Agent 倾向于局部模式匹配，而非有意导航。
3. 迅速腐烂：单体手册变成过时规则的墓地。Agent 无法判断哪些规则仍然有效，人类停止维护，文件成为“诱人的陷阱”。
4. 难以验证：单个文件块不利于机械检查（覆盖率、新鲜度、所有权、交叉链接），漂移不可避免。

因此，团队将 AGENTS.md 视为目录（Table of Contents），而非百科全书。

• 知识库结构：仓库的知识库位于结构化的 docs/ 目录中，作为记录系统。
• 精简指令：简短的 AGENTS.md（约 100 行）被注入上下文，主要作为地图，指向其他更深层次的真理来源。
• 文档分类：
  • 设计文档被编目和索引，包括验证状态和定义 Agent 优先操作原则的核心信念。
  • 架构文档提供领域和包分层的顶层地图。
  • 质量文档对每个产品领域和架构层进行分级，跟踪随时间的差距。
• 计划即工件：
  • 临时轻量级计划用于小更改。
  • 复杂工作记录在执行计划中，包含进度和决策日志，并检入仓库。
  • 活跃计划、已完成计划和技术债务均版本化并共存，使 Agent 无需依赖外部上下文即可操作。
• 渐进式披露：Agent 从小型、稳定的入口点开始，被教导下一步去哪里看，而不是 upfront 被信息淹没。

团队通过专门的 Linter 和 CI 作业机械地强制执行这一结构。

关键要点

• 零手动代码可行性：通过完全依赖 Codex 和 GPT-5，团队在5个月内构建了百万行代码的产品，耗时仅为传统的 1/10。
• 角色转变：工程师的角色从“代码编写者”转变为“环境设计师”和“意图指定者”。核心工作是为 Agent 构建可执行、可验证的反馈回路。
• 吞吐量随规模增长：随着驱动 Agent 的工程师从 3 人增加到 7 人，PR 吞吐量反而上升，表明该模式具有良好的可扩展性。
• Agent 自循环审查：通过让 Agent