Harness Engineering：在 Agent-First 范式下重构软件工程工作流

引言：当代码全部由 Agent 生成

OpenAI 内部团队在过去五个月完成了一项激进实验：从零开始构建并交付了一个软件产品的内部 Beta 版本，代码库中没有任何一行由人类手动编写。这个包含约一百万行代码的项目涵盖应用逻辑、测试、CI 配置、文档、可观测性工具和内部开发者工具，由最初的三名工程师驱动 Codex Agent 完成。令人意外的是，随着团队扩展到七人，代码吞吐量不降反升，达到了平均每人每天 3.5 个 Pull Request 的水平。

这个实验揭示了一个根本性转变：当软件工程团队的主要职责不再是编写代码，而是设计环境、明确意图、构建反馈循环时，工程实践需要如何重构。本文基于 OpenAI 公开的实践经验，梳理 Agent-first 范式下的关键工程原则与可落地参数。

核心转变：从 "写代码" 到 "设计环境"

在 Agent-first 的工作流中，人类工程师与系统的交互几乎完全通过 Prompt 完成：描述任务、运行 Agent、允许其创建 Pull Request。工程师的核心工作变成了让 Agent 能够可靠地完成任务。

这种转变带来了实践上的深度优先策略：将大型目标拆解为可组合的构建块（设计、代码、审查、测试等），引导 Agent 构建这些模块，再用它们解锁更复杂的任务。当任务失败时，修复方式不是 "再试一次"，而是追问 "缺少了什么能力，如何让它对 Agent 既清晰又可执行"。

关键洞察在于：Agent 在具有严格边界和可预测结构的环境中表现最佳。这类似于管理大型工程平台组织 —— 在中央层面强制执行边界和正确性，在边界内给予团队（或 Agent）充分的实现自由。

知识管理：给 Agent 一张地图，而非百科全书

上下文管理是 Agent 处理大型复杂任务时的最大挑战。OpenAI 团队的早期教训是：不要把 AGENTS.md 写成一本百科全书。

过长的指令文件会产生四个问题：上下文是稀缺资源，巨型文件会挤占任务、代码和相关文档的空间；过度指导会变成非指导，当所有内容都 "重要" 时，Agent 会陷入局部模式匹配而非有目的的导航；单体手册会迅速腐烂，Agent 无法判断哪些规则仍然有效，人类也停止维护；难以验证，单一文件不适合机械检查（覆盖率、新鲜度、所有权、交叉链接）。

解决方案是将 AGENTS.md 视为目录而非内容。实际的知识库存放在结构化的 docs/ 目录中，AGENTS.md 仅约 100 行，主要作为地图，指向其他位置的深层真相来源。设计文档被编目和索引，包含验证状态和定义 Agent-first 操作原则的核心信念；架构文档提供领域和包层级的顶层地图；质量文档对每个产品领域和架构层进行评级，跟踪随时间的差距变化。

计划被视为一等公民：小型变更使用临时轻量级计划，复杂工作则记录在带有进度和决策日志的执行计划中，并签入仓库。活跃的、已完成的计划以及已知的技术债务都被版本化并共置，使 Agent 能够在不依赖外部上下文的情况下运行。

可观测性重构：让应用对 Agent 可读

随着代码吞吐量的增加，瓶颈转向了人类 QA 能力。为了将更多能力赋予 Agent，团队致力于让应用 UI、日志和应用指标本身对 Codex 直接可读。

具体实践包括：使应用可按 Git worktree 启动，Codex 可以为每个变更启动和驱动一个实例；将 Chrome DevTools Protocol 接入 Agent 运行时，创建用于处理 DOM 快照、截图和导航的技能，使 Codex 能够复现 Bug、验证修复并直接推理 UI 行为；为可观测性工具做同样的事情 —— 日志、指标和追踪通过本地可观测性栈暴露给 Codex，该栈对任何给定 worktree 都是临时的，任务完成后即销毁。

Agent 可以使用 LogQL 查询日志，使用 PromQL 查询指标。有了这些上下文，像 "确保服务启动在 800ms 内完成" 或 "这四个关键用户旅程中的任何 Span 都不超过两秒" 这样的 Prompt 就变得可行。团队经常看到单个 Codex 运行处理单个任务长达六小时以上（通常发生在人类睡眠期间）。

架构守卫：用机械约束替代人工审查

仅靠文档无法保持完全由 Agent 生成的代码库的一致性。团队采用的策略是强制执行不变量，而非微观管理实现。例如，要求 Codex 在边界处解析数据形状，但不规定具体如何实现（模型似乎喜欢 Zod，但团队并未指定该特定库）。

应用围绕严格的架构模型构建：每个业务领域被划分为固定的层集合，具有严格验证的依赖方向和有限的允许边集。这些约束通过自定义 Linter（当然由 Codex 生成）和结构测试机械地强制执行。规则是：在每个业务领域内，代码只能 "向前" 通过固定的层集合（Types → Config → Repo → Service → Runtime → UI）依赖。横切关注点（认证、连接器、遥测、特性标志）通过单一显式接口 Providers 进入，其他一切都被禁止并机械地强制执行。

这种架构通常是拥有数百名工程师时才会采用的。有了编码 Agent，它成为早期先决条件：约束是允许速度而不衰减或架构漂移的条件。

实践中，团队用自定义 Linter 和结构测试以及一小套 "品味不变量" 来强制执行这些规则。例如，静态强制执行结构化日志、模式和类型的命名约定、文件大小限制以及平台特定的可靠性要求。由于 Linter 是自定义的，团队编写错误消息时将修复指令注入 Agent 上下文。

吞吐量驱动的流程重构

随着 Codex 吞吐量的增加，许多传统工程规范变得适得其反。仓库以最小化阻塞性合并门运行，Pull Request 生命周期短，测试 Flaky 通常用后续运行处理而非无限期阻塞进度。在 Agent 吞吐量远超人类注意力的系统中，修正是廉价的，等待是昂贵的。

这种策略在低吞吐量环境中是不负责任的，但在当前场景下往往是正确的权衡。团队观察到，随着更多开发循环被直接编码到系统中 —— 测试、验证、审查、反馈处理和恢复 —— 仓库最近跨越了一个有意义的阈值：Codex 可以端到端地驱动一个新功能。

给定单一 Prompt，Agent 现在可以：验证代码库当前状态、复现报告的 Bug、录制演示失败的视频、实现修复、通过驱动应用验证修复、录制演示解决的第二个视频、创建 Pull Request、响应 Agent 和人类反馈、检测和修复构建失败、仅在需要判断时升级给人类、合并变更。

熵管理与持续重构

完全由 Agent 自主也带来了新问题：Codex 会复制仓库中已存在的模式 —— 即使是不均匀或次优的模式。随着时间推移，这不可避免地导致漂移。

最初，团队每周五花费 20% 的时间手动清理 "AI slop"。 unsurprisingly，这无法扩展。替代方案是将所谓的 "黄金原则" 直接编码到仓库中，并构建定期清理流程。这些原则是固执己见的机械规则，保持代码库对未来 Agent 运行的可读性和一致性。

例如：优先使用共享工具包而非手写的辅助函数，以保持不变量集中；不采用 "YOLO 风格" 探测数据 —— 而是验证边界或依赖类型化的 SDK，这样 Agent 就不会意外地在猜测的形状上构建。在固定周期内，后台 Codex 任务扫描偏差、更新质量评级并创建有针对性的重构 Pull Request，大多数可以在一分钟内审查并自动合并。

这类似于垃圾回收：技术债务就像高利贷，持续小额偿还几乎总是比让它复利然后痛苦地一次性解决更好。人类品味被一次性捕获，然后在每一行代码上持续强制执行。

可落地参数清单

基于 OpenAI 的实践经验，以下是可立即应用的工程参数：

知识管理

• AGENTS.md 控制在 100 行以内，仅作为目录
• 结构化 docs/ 目录包含：架构文档（领域和包层级地图）、设计文档（带验证状态和核心信念）、质量文档（领域和层评级）、执行计划（复杂工作的进度和决策日志）
• 使用专用 Linter 和 CI 任务验证知识库是否最新、交叉链接和结构正确

可观测性

• 应用支持按 Git worktree 启动隔离实例
• 集成 Chrome DevTools Protocol 用于 DOM 快照、截图和导航
• 暴露 LogQL（日志）和 PromQL（指标）查询接口给 Agent
• 关键性能指标示例：服务启动 < 800ms，关键用户旅程 Span < 2s

架构约束

• 业务领域分层：Types → Config → Repo → Service → Runtime → UI
• 横切关注点通过单一 Providers 接口进入
• 自定义 Linter 强制执行依赖方向和命名约定
• 文件大小限制和平台可靠性要求静态检查

流程优化

• 最小化阻塞性合并门
• PR 短生命周期优先
• 测试 Flaky 用重试而非阻塞
• Agent 端到端能力：验证状态 → 复现 Bug → 录制视频 → 实现修复 → 验证修复 → 创建 PR → 响应反馈 → 自动合并

熵管理

• 编码 "黄金原则" 到仓库
• 定期后台任务扫描偏差和更新质量评级
• 目标：重构 PR 可在 1 分钟内审查并自动合并

结论

Agent-first 开发不是关于消除人类工程师，而是将人类注意力重新分配到更高杠杆的层面：确定优先级、将用户反馈转化为验收标准、验证结果。当 Agent 遇到困难时，将其视为信号 —— 识别缺少什么（工具、护栏、文档）—— 并将其反馈到仓库中，始终让 Agent 自己编写修复。

最困难的挑战现在集中在设计环境、反馈循环和控制系统，帮助 Agent 实现目标：大规模构建和维护复杂、可靠的软件。随着像 Codex 这样的 Agent 承担软件生命周期中更大的部分，这些问题将变得更加重要。核心启示是：构建软件仍然需要纪律，但纪律更多地体现在脚手架而非代码本身。

参考来源

• Harness engineering: leveraging Codex in an agent-first world — OpenAI 官方博客，2026 年 6 月

ai-systems