作者 | Ryan Lopopolo
译者 | 田橙
策划 | Tina
过去五个月，团队完成一项关键实践：从零启动并发布一款完全由 Codex Agent 生成的内部测试产品。该产品已投入真实环境运行，拥有稳定日活用户及外部 Alpha 测试群体。全部代码——涵盖应用逻辑、测试脚本、CI 配置、可观测性系统、文档与内部工具——均由 Codex 自主产出，开发效率达人工编码的 10 倍。
人类掌舵，Agent 执行
项目设定“禁止人工编写代码”的硬约束，旨在验证工程效能能否实现数量级跃升。面对数周内交付百万行代码的压力，团队重新定义工程师角色：不再聚焦于写代码，而是构建可信赖的开发环境、精准表达意图、设计闭环反馈机制，使 Agent 能持续产出高质量成果。
从空仓库起步
2025 年 8 月底，首个 Commit 提交至空白仓库。初始脚手架由 Codex CLI 调用 GPT-5 生成，辅以少量模板，覆盖目录结构、CI 配置、格式化规则、包管理及框架选型；连指导 Agent 工作的 AGENTS.md 文件，也由 Codex 自行撰写。
全仓无一行人工代码作为“锚点”，形态完全由 Agent 塑造。五个月后，仓库代码量达约 100 万行，覆盖应用逻辑、基础设施、工具链、文档及内部组件。一支 3 人工程师团队驱动 Codex 发起并合并约 1500 个 PR，人均日均产出 3.5 个；扩至 7 人后，人均效率进一步提升。
该产品已被数百名内部用户高频使用，核心用户每日深度依赖。全程无人工代码提交，“拒绝人工编写代码”成为团队根本原则。
重新定义工程师的角色
工程师重心转向系统设计、脚手架搭建与杠杆力建设。初期进展缓慢，并非因 Codex 能力不足，而是环境“规范度”欠缺——Agent 缺乏达成高层目标所需的工具、抽象与结构支撑。因此，团队首要任务是“赋能 Agent 高效工作”。
实践中采用深度优先策略：将大目标拆解为微小构建块（设计→编码→评审→测试），驱动 Agent 逐个实现；再以已建模块解锁更复杂任务。当任务失败，修复重点不是重试，而是追问：“缺失何种能力？如何让该能力对 Agent 显性且强制？”
人机交互几乎全通过提示词完成：工程师描述任务→运行 Agent→授权开启 Pull Request。PR 合入流程亦由 Agent 主导：本地自审代码，并调用其他 Agent（本地或云端）交叉评审；依据人类或 Agent 反馈持续迭代，直至所有评审方满意——形成典型的“拉尔夫·维格姆循环”（Ralph Wiggum Loop）。
Codex 直接调用标准开发工具（如 GitHub CLI gh、本地脚本、仓库内置技能），自主获取上下文，无需人工复制粘贴。人类虽可参与评审，但非强制；目前绝大多数评审已交由 Agent 对 Agent 协作完成。
增强应用的“可读性”
随着代码产出加速，人类 QA 成为瓶颈。为释放 Agent 能力，团队着力提升 UI、日志与指标对 Codex 的直接可读性与可操作性。
例如：支持按 Git 工作树（worktree）独立启动应用实例，使 Codex 可为每次变更运行专属环境；接入 Chrome DevTools Protocol，赋予 Agent 处理 DOM 快照、截图与导航的能力，从而直接复现 Bug、验证修复、推导 UI 行为。
可观测性栈同样面向 Agent 重构：日志、指标、链路追踪通过轻量本地栈暴露，每个工作树独享临时实例，任务结束后自动销毁。Agent 可用 LogQL 查询日志、PromQL 查询指标。诸如“服务启动耗时 ≤800ms”或“四个关键用户旅程中无 Trace Span 超过 2 秒”等提示词，由此具备明确可执行性。
单次 Codex 运行常持续超 6 小时（多在夜间），全自动处理完整任务链。
以仓库知识作为“事实来源”
上下文管理是 Agent 应对复杂任务的核心挑战。关键经验是：提供一张“地图”，而非千页“手册”。
早期尝试“单一 AGENTS.md 大文件”方案迅速失败，原因有四：1）上下文稀缺，大文件挤占任务代码空间，导致关键约束遗漏或目标偏移；2）过度引导等于无引导，“全部重要”即“全部不重要”，Agent 仅做局部模式匹配；3）文档易腐化，单体手册快速沦为陈旧规则坟场，反成误导源；4）难以验证，无法进行覆盖率、时效性、归属权等机械化检查，架构偏离不可避免。
因此，AGENTS.md 被降级为目录，而非百科全书。真正“唯一事实来源”是结构化 docs/ 目录。一份精简版 AGENTS.md（约 100 行）注入上下文，仅作导航地图，指向各处深层事实。
AGENTS.md
ARCHITECTURE.md
docs/
├── design-docs/
│ ├── index.md
│ ├── core-beliefs.md
│ └── ...
├── exec-plans/
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/
│ └── db-schema.md
├── product-specs/
│ ├── index.md
│ ├── new-user-onboarding.md
│ └── ...
├── references/
│ ├── design-system-reference-llms.txt
│ ├── nixpacks-llms.txt
│ ├── uv-llms.txt
│ └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md设计文档被编目索引，标注验证状态与“Agent 优先”核心信条；架构文档提供领域划分与包分层总览；质量文档对各产品域与架构层评分并长期跟踪差距。
执行计划（Plans）为一等公民：轻量变更用临时计划，复杂任务则提交至 exec-plans/，附带进度与决策日志；活跃、已完成计划及技术债统一版本化管理，使 Agent 无需外部上下文即可工作。
实现渐进式披露：Agent 从稳定微小入口出发，按指引逐步获取所需信息，避免信息过载。
该机制由机械化手段保障：专用 Linter 与 CI 任务验证文档时效性、交叉引用合规性及结构一致性；“文档园丁”Agent 定期扫描陈旧文档，自动发起修复 PR。
以“Agent 可读性”为目标
随代码库演进，Codex 的设计决策框架同步进化。因全仓由 Agent 生成，首要优化方向是“Agent 可读性”——如同为新人工程师提升可导航性，人类工程师的目标是让 Agent 能直接从仓库推导完整业务知识。
对 Agent 而言，运行时不可见的信息即不存在。Google Docs、聊天记录或人脑中的知识均不可访问；唯仓库本地、版本化的工件（代码、Markdown、Schema、可执行计划）构成其全部认知世界。
团队意识到需将更多上下文沉淀至仓库。例如，曾达成架构共识的 Slack 讨论若未存档，对 Agent 即为“不可读”——如同对三个月后入职的新员工缺失背景。
向 Agent 提供上下文，重在组织与暴露正确信息以支撑推理，而非堆砌临时指令。正如向新成员介绍产品原则、工程规范与团队文化，向 Agent 注入同类信息可显著提升产出一致性。
该思路明晰了多项技术选型权衡：优先采用可完全内化、便于仓库内推理的依赖与抽象。所谓“乏味”技术（如高组合性、API 稳定、训练集覆盖率高者）更易被 Agent 建模。某些场景下，重写部分功能比绕过公共库中不透明行为成本更低。例如，未引入通用 p-limit 包，而是自研并发映射助手：深度集成 OpenTelemetry 监控、100% 测试覆盖、严格契合运行时预期。
将系统更多部分转化为 Agent 可检查、可验证、可修改的形式，不仅提升 Codex 杠杆效能，亦惠及同库其他 Agent（如 Aardvark）。
强制执行架构与审美
仅靠文档无法维持全 Agent 生成代码库的连贯性。团队通过强制“不变量”而非微观管控细节，在高速交付中守护系统根基。例如：要求系统边界处必须进行数据格式解析，但不限定具体实现（模型倾向 Zod，但从未指定）。
Agent 在边界清晰、结构可预测环境中效率最高。因此，应用基于一套刚性架构模型构建：每个业务领域划分为固定层级，依赖方向严格验证，连接点有限。此类约束由自定义 Linter（同样由 Codex 生成）与结构化测试机械化执行。
如下图所示：在“应用设置”等业务域内，代码仅允许沿固定层级“前向”依赖（类型定义 → 配置 → 仓库层 → 服务层 → 运行时 → UI）。跨域关注点（认证、连接器、遥测、特性开关）仅通过明确定义的“提供者（Providers）”接口接入；其余任何依赖均被禁止并强制拦截。
此类架构通常在百人以上工程团队才推行，但对编程 Agent 而言，却是前置必要条件——正是这些约束，确保系统在高速迭代中不腐化、不偏离。
实践中，通过自定义 Linter、结构化测试与“审美不变量”共同执行：强制结构化日志、命名规范、文件大小限制及平台可靠性要求。Linter 支持定制错误信息，可将修复指令直接注入 Agent 上下文。
在人类中心工作流中，此类规则或显僵化；但在 Agent 环境下，它们是效能倍增器——一旦编码，即刻全局生效。
团队明确区分“需约束”与“可自由”区域，类似大型平台组织治理：中央严守边界、正确性与可复现性；边界内允许 Agent 充分发挥解决方案表达力。
最终代码未必符合人类审美偏好，但只要正确、可维护、且对后续 Agent 运行可理解，即达标准。人类审美持续反馈至系统：评审意见、重构 PR、用户 Bug 均转化为文档更新或工具链编码。当文档失效，规则即晋升为代码。
吞吐量提升改变合并哲学
随 Codex 吞吐量激增，传统工程规范反成阻力。
仓库阻塞性合并门槛极低，PR 生命周期极短。偶发测试失败通常由后续运行解决，而非无限期阻塞。在 Agent 吞吐远超人类注意力的系统中，纠错廉价，等待昂贵。
此策略在低吞吐传统环境中或属失责，但在当前语境下，是更优权衡。
“Agent 生成”的真正含义
“Codex Agent 生成”指代码库中一切内容：
- 产品代码与测试脚本
- CI 配置与发布工具
- 内部开发者工具
- 文档与设计历史
- 评估框架（Evaluation harnesses）
- 评审评论及回复
- 管理仓库本身的脚本
- 生产环境仪表盘定义文件
人类仍掌控全局，但抽象层级提升：聚焦需求排序、用户反馈转验收标准、结果终审把关。当 Agent 开发受阻，即为系统缺陷信号——缺工具？缺护栏？缺文档？定位后，仍坚持由 Codex 自行编写修复方案。
Agent 直接使用标准开发工具，获取评审反馈、行内回复、推送更新，并通常自主 Squash 与合并 PR。
持续提升的自主化水平
随测试、验证、评审、反馈处理及故障恢复等环路逐步编码进系统，仓库已跨越里程碑：Codex 可端到端驱动新特性开发。
仅需一段提示词，Agent 即可自主完成：
• 验证代码库当前状态
• 复现报告 Bug
• 录制故障过程视频
• 实现修复方案
• 操作应用验证修复效果
• 录制修复效果视频
• 开启 Pull Request
• 响应 Agent 及人类反馈
• 检测并修复构建失败
• 仅需人类判断时才上报
• 自动合并变更
该能力高度依赖本仓库特定结构与工具链，暂不具备泛化性。
熵增与垃圾回收
完全 Agent 自主权带来新挑战：Codex 会复刻仓库既有模式——包括非最优模式，长期积累导致架构偏离。
初期依赖人工清理（团队曾固定每周五投入 20% 时间“清 AI 废料”），但无法扩展。
解决方案是将“金科玉律”写入代码仓库，建立周期性清理机制。这些是具明确主张的机械化规则，确保代码库在后续 Agent 运行中持续清晰一致。实践包括：
• 优先复用共享工具包，而非手写辅助函数，集中管理不变量；
• 拒绝“运气式”数据探测，边界处必校验，或依赖强类型 SDK，杜绝 Agent 采样猜测数据形状。
定期运行 Codex 后台任务，扫描违规代码、更新质量评分、发起针对性重构 PR。因规则明确，多数 PR 可在一分钟内完成评审并自动合并。
该机制如“垃圾回收”：技术债宜小额持续偿还，远胜积压后痛苦爆发式清理。人类审美一次捕获，即终身强制执行；日常即可识别并消除不良模式，避免蔓延数天乃至数周。
我们仍在探索的领域
当前策略已在 OpenAI 内部产品落地验证，真实用户与真实需求驱动系统走向长期可维护。
长期挑战仍存：全 Agent 系统的架构连贯性在数年尺度如何演进？人类判断力在何处杠杆效应最大？如何将其沉淀为可持续复利的规则？模型能力持续增强下，系统又将如何进化？
但结论已清晰：软件构建仍需严谨纪律，只是重心从“写代码”转向“搭脚手架”。能维系代码库连贯性的工具链、抽象层与反馈循环，正变得空前重要。
当前最艰巨任务，是设计环境、反馈循环与控制系统——唯有如此，才能让 Agent 大规模构建并维护复杂可靠的软件。
随着 Codex 等 Agent 承担软件生命周期越来越多环节，这些问题将愈发关键。希望这些早期实践，助你厘清投入重点，更纯粹地创造产品。