这是一篇由原始材料转换而来的阅读页，保留了源文件的主要结构，并补充了可追溯的来源说明与链接。

Harness Engineering（OpenAI 版）：把 Codex 变成可持续交付的软件工程系统

这份目录基于 OpenAI 官方技术博客《工程技术：在智能体优先的世界中利用 Codex》： https://openai.com/zh-Hans-CN/index/harness-engineering/

同时参考了 Anthropic Engineering《Effective harnesses for long-running agents》： https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

目标不是只让 agent “跑起来”，而是把它变成一个 可持续交付、可审计、可扩展、可收敛 的工程系统（harness）。

如果说 Anthropic 的重点是“跨 context window 的换班交接”，那么 OpenAI 这篇的重点更像是：

人类不再主要写代码，而是设计 环境、约束、反馈回路、知识地图与控制系统，让 Codex 持续地产出高质量结果。

1. 两篇文章的差异：OpenAI 版多了什么

Anthropic 版核心

• Initializer + Coding 两阶段
• init.sh / feature_list.json / progress.md
• 每次只做一个小增量
• 交接与 git 历史是外置记忆

OpenAI 版新增的关键层

OpenAI 文章把 harness 从“会话接力协议”升级成了“仓库操作系统”：

1. 地图，而不是 1000 页说明书 - AGENTS.md 只做目录与入口，不做百科全书 - 真实知识放进结构化 docs/，并持续维护

2. 计划是一等工件（Plan as Artifact） - 小任务用轻量计划 - 复杂任务用 exec plan，包含进度、决策、验证与回滚

3. 约束必须机械化（Mechanized Invariants） - 架构边界、命名、日志、文件大小、层次依赖，尽量交给 lint / CI / 结构测试 - 不依赖“人记得”或“review 时顺手发现”

4. 反馈回路直接喂给 agent - UI 可读：DOM snapshot / screenshot / 浏览器自动化 - 系统可读：日志 / metrics / traces - 环境可隔离：git worktree / 临时实例 / 临时观测栈

5. 文档治理（doc gardening）常态化 - 文档新鲜度、交叉链接、覆盖率要被 CI 和后台 agent 检查 - 让仓库中的知识长期可信

2. OpenAI 风格 harness 的最小骨架

一个成熟的 Codex harness，至少应当包含：

• AGENTS.md
• 短、稳、像目录

• 只定义规则、流程、关键入口、去哪看更多细节

• docs/

• 真正的知识库（系统记录）

• 包括 architecture / product / ops / runbooks / plans / debt 等

• init.sh

• 启动 + 冒烟测试 + 环境健康检查

• feature_list.json

• 用户可感知的端到端功能清单

• plans/

• 执行计划与复杂任务的决策记录

• progress.md

• 会话交接日志

• tools/ 或 scripts/

• agent 可调用的可靠脚本入口

• lint/CI/structural tests

• 把“工程品味”编码成自动约束

3. 我从 OpenAI 文章提炼出的 7 条经验

经验 1：Agent 不是缺“努力”，而是缺“环境”

早期进展慢，不是 Codex 不能写，而是环境没有把： - 目标 - 路径 - 验证 - 约束 - 反馈

组织成 agent 可消费的形式。

经验 2：大而全 AGENTS.md 通常会腐烂

AGENTS.md 越大，越像噪音。 更好的做法是： - 保持短小（目录/地图） - 把真实知识放在 docs/ - 用交叉链接与质量检查维持其可导航性

经验 3：计划必须版本化

复杂工作不应只存在于 prompt 或聊天历史。 应把： - 目标 - 假设 - 决策 - 当前状态 - 下一步

作为仓库内工件提交。

经验 4：让 agent 看到 UI / 日志 / 指标，能力会陡增

如果 agent 只能看代码，它只能“猜测”系统行为。 如果它还能看： - 浏览器状态 - DOM / screenshot - 日志 / traces / metrics

那它就能真正进入“闭环调试”。

经验 5：要机械化地强制边界，而不是口头提倡好习惯

“请注意架构分层”通常没用。 “违反分层就 lint fail / CI fail”才有用。

经验 6：高吞吐时代，等待成本比纠错成本更高

当 agent 产出速度远高于人类注意力，很多流程要从“减少错误”转向“快速修正 + 自动清理 + 后台治理”。

经验 7：人的价值上移到系统设计

人不再主要写代码，而是： - 设计抽象 - 设计反馈回路 - 设计约束 - 设计知识布局 - 设计自动修复与清理机制

4. 我设计的 4 套项目框架（OpenAI 风格）

本目录给出四套可复用框架：

1. framework-agent-product/ - 用于从 0 到 1 的 agent-first 新产品 - 强调 docs 地图、exec plans、worktree、UI 验证、PR 闭环

2. framework-long-running/ - 用于长时间连续编码 / 跨多 session 接力 - 是 Anthropic“交接制”的增强版

3. framework-bug-factory/ - 用于缺陷复现、修复、回归验证 - 强调日志/trace/截图/复现视频/回归脚本

4. framework-doc-garden/ - 用于知识库、规范库、架构文档持续维护 - 强调文档健康度、交叉链接、新鲜度、废弃扫描

5. 读后感（我的判断）

5.1 OpenAI 的文章更“体系化”

Anthropic 那篇很适合回答： - 为什么长任务 agent 会失忆？ - 为什么需要 progress / feature list / init.sh？

OpenAI 这篇则更进一步回答： - 如果整个仓库都由 agent 主导，系统应该怎么设计？ - 如何让 agent 不依赖人脑中的隐性知识？ - 如何把“工程品味”变成自动执行的约束与反馈？

5.2 最有价值的点：把仓库当作 agent 的全部世界

文章里有个判断我非常认同：

对 agent 来说，运行时上下文里看不到的东西，就等于不存在。

这意味着： - Slack 讨论、口头共识、Google Docs、脑海经验 - 如果没沉淀进 repo - 对 agent 来说就是黑洞

这会倒逼团队把“隐性知识”不断仓库化。

5.3 对真实团队的启发

我认为未来软件团队的分工会越来越像： - 人：定方向、定约束、定验收、定风险容忍度 - Agent：实现、验证、回归、修复、整理、审查、清理

因此，harness engineering 很可能会变成独立的工程职能，就像过去的平台工程、DevEx、测试基础设施一样。

6. 落地建议（给真实项目）

如果你准备在真实仓库里实践，我建议分三步走：

第一步：先补最小接力骨架

• AGENTS.md
• init.sh
• feature_list.json
• progress.md

第二步：把“知识”从大 prompt 搬进 repo

• 建 docs/architecture
• 建 docs/product
• 建 docs/runbooks
• 建 plans/

第三步：把“要求”机械化

• lint
• structural tests
• CI rules
• doc freshness / cross-link checks
• 后台 doc-gardening / cleanup agent

7. 目录说明

• AGENTS.md：英文版 agent 操作地图
• AGENTS-cn.md：中文版说明
• templates/：模板工件
• framework-agent-product/：新产品交付框架
• framework-long-running/：长任务接力框架
• framework-bug-factory/：缺陷修复工厂框架
• framework-doc-garden/：文档花园治理框架
• notes.md：读后感、总结、个人判断

8. 结论

Anthropic 教会我们：要会交接。 OpenAI 教会我们：要把整个工程系统设计成 agent 可持续工作的环境。

前者解决“别失忆”，后者解决“如何长期高质量地产出”。

对我来说，真正的关键结论是：

智能体时代的软件工程，竞争力不再只是“谁会写 prompt”，而是“谁会设计 harness”。