SERIES · 随想
2026-03-10 · 14 min read · by GUMP
基于 OpenAI 于 2026 年 2 月 11 日 发布的文章 Harness engineering: leveraging Codex in an agent-first world，作者为 Ryan Lopopolo。文中记录了一次真实工程实验：团队以“0 行人工手写代码”为约束，从空仓库起步，用 Codex 产出应用代码、测试、CI、文档、可观测性和内部工具；约五个月后，仓库规模达到约百万行代码、约 1500 个 PR，平均每名工程师每天约 3.5 个 PR。
Next in Series
No next post yet
这篇文章真正讨论的，不是“怎么把提示词写得更花”，而是：当 agent 成为主要代码产能后，工程团队的核心工作会从写代码，转向搭环境、立约束、建反馈回路。 原文一句话可以概括为：人负责定方向、拆目标、做判断；agent 负责执行、生成、修复和迭代。
把 Harness Engineering 理解成一句话：
不是提升 agent 的“写代码能力”，而是构建一整套让 agent 能稳定、可靠、可验证地产出代码的工程操作系统。
按原文经验，这套“操作系统”主要由四部分组成：
环境（能跑、能看、能测）、知识（仓库内可读的系统说明）、约束（lint、结构测试、边界规则）、闭环（评审、反馈、修复、清理机制）。这是我基于全文内容提炼出的工作定义。
原文最核心的组织变化是：工程师不再亲手补每一段实现，而是描述任务、运行 agent、让它开 PR，再持续把失败暴露出来并反馈回系统。遇到问题时，不是问“为什么它这次没写好”，而是问“缺了什么能力、上下文、工具或约束，怎么把它补成 agent 能长期使用的机制”。
文中明确说，随着代码吞吐提高，瓶颈很快从“写代码”变成“人工 QA 能力”。因此，他们没有继续把压力堆到人身上，而是让 UI、日志、指标和追踪都对 Codex 可见，让 agent 自己去复现、验证、排查和迭代。
OpenAI 团队踩过“大而全 AGENTS.md”的坑，结论是：给 agent 一张地图，不要给它一本 1000 页说明书。 他们把短小的 AGENTS.md 当作目录，把真正的知识沉到结构化 docs/、架构文档、产品规格、执行计划、质量评分和技术债记录中，并用 CI/lint 机械检查这些知识是否新鲜、完整、互相链接。
原文强调，完全由 agent 生成的代码库，首先要为 Codex 的可理解性 优化。对 agent 来说，运行时上下文里看不到的东西，等于不存在。Slack 讨论、Google Docs、人口头知识，若没有回写进仓库，就不会参与后续推理。
这篇文章不是靠“细致提示词”来控制每个实现细节，而是靠强边界、清分层、硬规则。每个业务域采用固定层级，依赖方向受限，跨领域能力通过显式接口进入，再辅以自定义 lint、结构测试和“带修复提示的错误信息”，让 agent 在边界内自由发挥。
文中仓库采用“尽量少阻塞”的 merge 策略：PR 要短命，flaky test 往往通过后续 run 修掉，而不是无限卡住。作者特别说明，这种做法在低吞吐团队里可能不负责任，但在 agent 吞吐远高于人类注意力 的场景下，等待往往比纠正更贵。
原文承认，agent 会复制仓库中已存在的模式，好的坏的都会复制。团队一度每周花 20% 时间清理 “AI slop”，后来改成把“黄金原则”编码进仓库，再用周期性后台任务扫描偏差、更新质量分、自动发起小型重构 PR，把清熵从“集中大扫除”变成“持续垃圾回收”。
在这套模式里，工程师的新职责只剩四件事：
原文里，工程师几乎完全通过 prompt 与系统交互：描述任务，运行 agent，让它开 PR，再让 agent 自己做本地 review、请求其他 agent review、吸收反馈并循环迭代。人类 review 可以有，但越来越不是主路径。
原文中，Codex 之所以能做更多事，不是因为“天生更聪明”，而是因为团队把环境补齐了：
git worktree 独立启动这意味着 agent 不只是“会写代码”，而是拥有了观察系统、验证系统、修复系统的能力。
原文的仓库知识体系，本质上是一个“面向 agent 的知识库”。可抽象成四类文档：
重点不是文档多，而是可搜索、可链接、可验证、可版本化。
文中非常清楚的一点是：文档只能解释，规则才会长期生效。
因此，要把“团队品味”从口头意见变成：
而且，原文还特别提到：这些自定义 lint 的报错信息会故意写成带修复建议的形式，让 agent 在出错时就能拿到 remediation context。
下面是按原文抽象出来的“最小可用版”：
AGENTS.md # 只放导航，不放百科全书
ARCHITECTURE.md # 业务域、层级、依赖规则
docs/
design-docs/ # 设计决策与原则
product-specs/ # 产品需求与验收标准
exec-plans/
active/ # 正在进行的执行计划
completed/ # 已完成计划与复盘
references/ # 工具/框架/外部系统参考
QUALITY_SCORE.md # 质量分级与缺口
RELIABILITY.md # 稳定性要求
SECURITY.md # 安全要求
TECH_DEBT.md # 技术债与偏差记录这不是原文逐字复制，而是根据原文展示的仓库知识布局整理出的实用模板。原文确实包含 AGENTS.md、ARCHITECTURE.md、design docs、execution plans、product specs、references、quality/reliability/security 一类文档。
只写四类内容：
不要在这里塞大量规则细节。原文对“大一统 AGENTS.md”的批评非常直接：它会挤占上下文、让重点失焦、迅速腐化，而且难以校验。
这就是原文“端到端 feature autonomy”的工程化改写。
原文明确写到，Codex 已能完成“复现 bug、录制失败视频、修复、验证、录制修复视频、开 PR、处理反馈、修 build、合并”这条链路。
这就是文中所谓“garbage collection”机制。
用下面 7 个问题判断团队是否真正进入了 agent-first 工程模式：
AGENTS.md 是不是又膨胀成百科全书了？这些问题不是原文逐条列出的清单，而是我依据全文主张整理出的管理检查项。原文最强调的就是：可读性、结构性、硬约束、持续清理。
这篇文章对应的五个典型误区是：
文中团队之所以跑通，不是因为“agent 会写代码”这件事本身，而是因为他们把上面这些点都改造成了系统能力。
原文并没有把这套方法包装成万能答案。作者明确提醒：Codex 之所以能做到端到端完成新功能，强依赖于这个仓库特定的结构、工具链和投入，不能轻易外推。作者也坦言，他们还在观察 fully agent-generated codebase 在多年尺度上的架构一致性，以及人类判断究竟应该在哪些环节最有杠杆。
这篇文章最大的启发不是“Codex 会写很多代码”，而是：当 agent 成为主要产能后，工程学的核心对象会从“代码”转向“让 agent 稳定地产出正确代码的系统”。