当工程师的工作，从写代码转向设计agent的工作环境

基于 OpenAI 于 2026 年 2 月 11 日 发布的文章 Harness engineering: leveraging Codex in an agent-first world，作者为 Ryan Lopopolo。文中记录了一次真实工程实验：团队以“0 行人工手写代码”为约束，从空仓库起步，用 Codex 产出应用代码、测试、CI、文档、可观测性和内部工具；约五个月后，仓库规模达到约百万行代码、约 1500 个 PR，平均每名工程师每天约 3.5 个 PR。

一、到底讲了什么

这篇文章真正讨论的，不是“怎么把提示词写得更花”，而是：当 agent 成为主要代码产能后，工程团队的核心工作会从写代码，转向搭环境、立约束、建反馈回路。 原文一句话可以概括为：人负责定方向、拆目标、做判断；agent 负责执行、生成、修复和迭代。

二、定义卡：什么是 Harness Engineering

把 Harness Engineering 理解成一句话：

不是提升 agent 的“写代码能力”，而是构建一整套让 agent 能稳定、可靠、可验证地产出代码的工程操作系统。

按原文经验，这套“操作系统”主要由四部分组成：

环境（能跑、能看、能测）、知识（仓库内可读的系统说明）、约束（lint、结构测试、边界规则）、闭环（评审、反馈、修复、清理机制）。这是我基于全文内容提炼出的工作定义。

三、七条核心原则

1. 人类不再主要写代码，而是负责 steering

原文最核心的组织变化是：工程师不再亲手补每一段实现，而是描述任务、运行 agent、让它开 PR，再持续把失败暴露出来并反馈回系统。遇到问题时，不是问“为什么它这次没写好”，而是问“缺了什么能力、上下文、工具或约束，怎么把它补成 agent 能长期使用的机制”。

2. 真正的瓶颈是人类时间与注意力

文中明确说，随着代码吞吐提高，瓶颈很快从“写代码”变成“人工 QA 能力”。因此，他们没有继续把压力堆到人身上，而是让 UI、日志、指标和追踪都对 Codex 可见，让 agent 自己去复现、验证、排查和迭代。

3. 仓库是唯一可信来源

OpenAI 团队踩过“大而全 AGENTS.md”的坑，结论是：给 agent 一张地图，不要给它一本 1000 页说明书。 他们把短小的 AGENTS.md 当作目录，把真正的知识沉到结构化 docs/、架构文档、产品规格、执行计划、质量评分和技术债记录中，并用 CI/lint 机械检查这些知识是否新鲜、完整、互相链接。

4. 优先追求 agent 可读性，不是人类审美

原文强调，完全由 agent 生成的代码库，首先要为 Codex 的可理解性 优化。对 agent 来说，运行时上下文里看不到的东西，等于不存在。Slack 讨论、Google Docs、人口头知识，若没有回写进仓库，就不会参与后续推理。

5. 用约束守住架构，不用微操守住风格

这篇文章不是靠“细致提示词”来控制每个实现细节，而是靠强边界、清分层、硬规则。每个业务域采用固定层级，依赖方向受限，跨领域能力通过显式接口进入，再辅以自定义 lint、结构测试和“带修复提示的错误信息”，让 agent 在边界内自由发挥。

6. 高吞吐环境需要不同的合并哲学

文中仓库采用“尽量少阻塞”的 merge 策略：PR 要短命，flaky test 往往通过后续 run 修掉，而不是无限卡住。作者特别说明，这种做法在低吞吐团队里可能不负责任，但在 agent 吞吐远高于人类注意力 的场景下，等待往往比纠正更贵。

7. 熵增不是例外，而是默认状态

原文承认，agent 会复制仓库中已存在的模式，好的坏的都会复制。团队一度每周花 20% 时间清理 “AI slop”，后来改成把“黄金原则”编码进仓库，再用周期性后台任务扫描偏差、更新质量分、自动发起小型重构 PR，把清熵从“集中大扫除”变成“持续垃圾回收”。

四、团队操作系统：一套可落地的结构

模块 A：角色重构

在这套模式里，工程师的新职责只剩四件事：

定目标
拆任务
设约束
验结果

原文里，工程师几乎完全通过 prompt 与系统交互：描述任务，运行 agent，让它开 PR，再让 agent 自己做本地 review、请求其他 agent review、吸收反馈并循环迭代。人类 review 可以有，但越来越不是主路径。

模块 B：环境建设

原文中，Codex 之所以能做更多事，不是因为“天生更聪明”，而是因为团队把环境补齐了：

应用能按 git worktree 独立启动
agent 能通过 Chrome DevTools Protocol 驱动 UI
能读取 DOM 快照、截图、页面状态
能直接查日志、指标、追踪
能直接使用标准开发工具
单个任务可持续运行六小时以上

这意味着 agent 不只是“会写代码”，而是拥有了观察系统、验证系统、修复系统的能力。

模块 C：知识建设

原文的仓库知识体系，本质上是一个“面向 agent 的知识库”。可抽象成四类文档：

架构地图：业务域、分层、依赖方向
产品规格：用户流程、需求、验收标准
执行计划：复杂工作如何拆解、进度如何记录、决策如何沉淀
质量与债务记录：哪些区域不稳、哪些规则已知会漂移

重点不是文档多，而是可搜索、可链接、可验证、可版本化。

模块 D：控制建设

文中非常清楚的一点是：文档只能解释，规则才会长期生效。

因此，要把“团队品味”从口头意见变成：

lint 规则
结构测试
依赖方向检查
日志与命名规范
文件大小限制
平台可靠性约束

而且，原文还特别提到：这些自定义 lint 的报错信息会故意写成带修复建议的形式，让 agent 在出错时就能拿到 remediation context。

五、可直接照着搭的最小模板

1. 仓库结构模板

下面是按原文抽象出来的“最小可用版”：

bash

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 一类文档。

2. AGENTS.md 应该写什么

只写四类内容：

仓库总入口
关键文档索引
架构边界摘要
常见任务去哪里找依据

不要在这里塞大量规则细节。原文对“大一统 AGENTS.md”的批评非常直接：它会挤占上下文、让重点失焦、迅速腐化，而且难以校验。

六、三套标准工作流

A. 新功能交付 SOP

用一句话写清目标和验收标准
让 agent 验证当前仓库状态
复杂任务先产出 execution plan
让 agent 生成代码、测试、文档和评估脚手架
让 agent 自己驱动 UI、查日志、看指标做验证
由 agent 开 PR、吃反馈、反复迭代
只有涉及判断与权衡时再升级给人

这就是原文“端到端 feature autonomy”的工程化改写。

B. Bug 修复 SOP

复现问题
记录失败证据
实施修复
驱动应用重新验证
记录修复证据
开 PR 并处理反馈
构建失败则自动补救
必要时才升级给人

原文明确写到，Codex 已能完成“复现 bug、录制失败视频、修复、验证、录制修复视频、开 PR、处理反馈、修 build、合并”这条链路。

C. 清熵/治理 SOP

定义黄金原则
周期性扫描偏差
自动更新质量分
对偏差发起小型重构 PR
尽量让 PR 小到 1 分钟内可 review
能自动合并的尽量自动合并

这就是文中所谓“garbage collection”机制。

七、管理者检查表

用下面 7 个问题判断团队是否真正进入了 agent-first 工程模式：

知识是不是还散落在会议、聊天和人口头里？
AGENTS.md 是不是又膨胀成百科全书了？
agent 能不能自己看 UI、日志、指标、追踪？
架构边界是不是已经机械化校验？
评审规则是不是还主要靠人肉记忆？
技术债有没有被做成持续清理任务？
你追求的是“人类觉得优雅”，还是“agent 读得懂、改得稳”？

这些问题不是原文逐条列出的清单，而是我依据全文主张整理出的管理检查项。原文最强调的就是：可读性、结构性、硬约束、持续清理。

八、最容易踩的坑

这篇文章对应的五个典型误区是：

把提示词当核心，不投环境和反馈回路
把知识留在仓库外
只写规范，不做自动校验
在高吞吐 agent 系统里沿用低吞吐人工流程
只顾生成代码，不做清熵和重构

文中团队之所以跑通，不是因为“agent 会写代码”这件事本身，而是因为他们把上面这些点都改造成了系统能力。

九、适用边界

原文并没有把这套方法包装成万能答案。作者明确提醒：Codex 之所以能做到端到端完成新功能，强依赖于这个仓库特定的结构、工具链和投入，不能轻易外推。作者也坦言，他们还在观察 fully agent-generated codebase 在多年尺度上的架构一致性，以及人类判断究竟应该在哪些环节最有杠杆。

十、一句话结论

这篇文章最大的启发不是“Codex 会写很多代码”，而是：当 agent 成为主要产能后，工程学的核心对象会从“代码”转向“让 agent 稳定地产出正确代码的系统”。