解密 Codex Harness 设计：仓库为系统记录、AGENTS.md 为索引页——learn-harness-engineering 视角下的极简 harness 范式

在 OpenAI 的四个主流 Agent 产品中，Codex 是最彻底贯彻 harness 工程原理的一个——它把「仓库即系统记录（repository as the system of record）」推到极致：AGENTS.md 只做索引页，环境用 git worktree 物理隔离，反馈回路全部写进仓库约定。本文结合开源仓库 learn-harness-engineering 中的课程框架（五子系统模型）与真实工程示例，逐层拆解 Codex 的指令、上下文、工具、环境与反馈五个子系统，并给出可直接迁移到你项目中的五条设计要点。

一句话定位：当工程师从「写代码」变为「设计 harness」

Codex 的设计哲学可以浓缩为一句话：仓库是系统记录（source of truth），AGENTS.md 只是一页索引，工程价值在于环境设计、意图表达与反馈回路构建。

据原文档引述的 OpenAI「Harness Engineering」一文，OpenAI 团队在短短几周内用 Codex 交付了一个最终超过一百万行代码的产品，且全部由 Codex 编写。这个实验回答了一个根本问题：当工程师的角色从「亲自写代码」转向「设计 harness」时，系统该如何组织？Codex CLI 本身是一个用 Rust 编写的开源单体二进制（github.com/openai/codex 为原文档引用的外部仓库），但它对 harness 领域的主要贡献并不在精巧的扩展点上，而在conventions（约定）与context engineering（上下文工程）。

这一点与本仓库的课程主线完全呼应：本仓库的 Leçon 02 · Ce que signifie réellement harness 明确指出「如果它不是模型权重，它就是 harness」，并建立了「指令 / 工具 / 环境 / 状态 / 反馈」五子系统框架——Codex 正是这一框架最忠实的实践样本之一。

指令子系统：AGENTS.md 是索引页，不是百科全书

这是 Codex 对 harness 理论最具影响力的贡献。原文档直接转述了「Harness Engineering」一文的核心段落：

一个巨型单一指令文件难以进行机械化的控制——覆盖度、新鲜度、归属权与交叉链接——最终必然与现实脱节。因此我们不再把 AGENTS.md 当作百科全书，而是当作索引页（page d'index）。代码库的知识存放在结构化的文档中，由 AGENTS.md 指向它们。

这一理念与本仓库 Leçon 04 · Répartir les instructions entre fichiers 的主题严丝合缝：巨型指令文件会因「lost in the middle」效应、优先级模糊（Priority Ambiguity）、指令膨胀（Instruction Bloat）而失效。Codex 给出的直接答案是：

• 将 AGENTS.md 控制在约 100 行以内——原文建议接近该上限时就把内容迁往docs/；
• 其余内容拆分到docs/目录，按需读取（progressive disclosure）；
• 这就是「给地图，不给手册（donner la carte, pas le manuel）」原则的权威出处。

与之配套的第二个原则是强制执行不变式（invariants），而不微管理实现（don't micromanage the implementation）。AGENTS.md 只应包含不可违反的硬约束与验证命令；具体如何实现交给模型自行决策。这正是 Leçon 02 中「约束而不微管理（contraindre sans micromanager）」的课程概念的工程化落地。

仓库内的真实范例

本仓库的实践项目恰好示范了这种「索引页 + 主题文档」的结构。以 projects/project-01/solution/AGENTS.md 为例：

## Startup Rules 1. Read this file completely. It defines the boundaries and conventions for this project. 2. Read `docs/ARCHITECTURE.md` to understand the Electron layer structure. 3. Read `docs/PRODUCT.md` to understand the feature requirements. 4. Run `bash init.sh` to verify the project builds cleanly. ... 5. Read `feature_list.json` to see the current state of all features.

该文件只保留启动顺序、四层架构边界（main / preload / renderer / services）、约定（TypeScript strict、named exports）与「Definition of Done」，而架构细节、产品需求分别存放在docs/ARCHITECTURE.md、docs/PRODUCT.md中按需加载——正是「索引页 + docs/ 拆分」的直观例证。

上下文子系统：Write-Select-Compress-Isolate 四策略

Codex 的上下文工程可概括为四条策略，该框架由社区在「context engineering」成为独立学科后归纳并应用到 Codex（原文档引用自 Daniel Vaughan 的 Context Engineering for Codex CLI 系列文章）：

• Write（写到外部）：把上下文持久化到窗口之外——结论写进文档、状态写进文件，而不是留在对话里。这是「仓库即系统记录」原则的直接体现。
• Select（挑选进入的）：只把必要的 token 载入窗口——AGENTS.md 只给出路径，文件按需读取，而不是把整个仓库一次性注入。
• Compress（压缩）：只保留真正重要的内容。Codex 提供自动压缩（compaction）与手动命令/compact，并允许通过compact_prompt自定义压缩提示词。
• Isolate（隔离）：把上下文按不同边界切分。subagent 隔离任务上下文，例如一个前端 subagent 永远看不到后端数据库 schema。

此外，Codex 有一个非常细腻的环境上下文设计细节。根据原文档引述的社区源码分析 codex-harness-internals：build_environment_update_item在环境变化时只产出发生变化的字段——CWD、git 分支、文件系统差异——而不是每一轮都重新拼装整套系统上下文。这是「从上下文中剔除重复 token」的典型实现，与 Select / Compress 策略互为表里。

工具与环境：git worktree 物理隔离 + 内核级 subagent

Codex 依赖两个 harness 层面的基础机制：

1. 用 git worktree 实现环境隔离

「Harness Engineering」一文的 Environment 部分指出：每个任务都运行在独立的 git worktree中，并配有一整套本地可观测性栈——日志、指标、追踪——从而在隔离环境中验证每一次变更。这是 Leçon 07 · Définir des limites de tâche claires 中「清晰界定 Agent 的每个任务」原则的物理实现：任务边界不是靠指令「请求」出来的，而是由环境隔离强制出来的。此时环境子系统从「配置管理」升级为「严格隔离」。

2. 内核级 subagent

spawn_agent与wait_agent是 Codex 的原生工具：模型显式创建 subagent，为它分配独立的会话历史与工具集，然后等待其结果。subagent 继承父级 AGENTS.md 指令，但工作在自己的独立上下文中；其配置位于.codex/agents/*.toml，可指定不同的模型与指令。这正是「上下文隔离」与 Leçon 12 · Laisser un handoff propre à la fin de chaque session 中 handoff 思想的直接实现——每个 subagent 都是一个边界清晰的工作单元，不会污染主循环。

仓库内的对应实践：单功能并发策略

本仓库 projects/project-03/solution/AGENTS.md 的「One-Feature-at-a-Time Policy」正是任务边界控制的工程化模板：

1. Pick exactly one feature from `feature_list.json` with status "not-started". 2. Implement only that feature. Do not touch code unrelated to the chosen feature. 3. Verify the feature works by running `npm run check` ... 4. Update `feature_list.json` -- set status to "pass" and add evidence. 5. Commit the change with a message referencing the feature ID. 6. Only then move to the next feature.

并通过feature_list.json（见 projects/project-03/solution/feature_list.json）以机器可读格式记录每个功能的状态与验证证据——这是「外部化 scope surface」的落地形态，与 Codex 把边界写进运行时机制的理念同源。

反馈子系统：把验证命令写进约定，让验证路径成为 harness 默认组件

OpenAI 的实践首要强调：把验证命令显式写进 AGENTS.md，让「如何确认工作是正确的」成为仓库的一部分。在 Codex 的工程流程中，测试、CI、文档与可观测性配置全部由 Codex 生成，它们共同构成「可执行的验证路径」。面对强大但不可靠的模型，答案不是指望它自我约束，而是把验证路径做成 harness 的默认组件。

审批策略（approval policies）与 plan mode 提供另一种反馈：先产出计划、在执行高风险操作前请求人类批准，从而把「任务边界」与「人类决策权」固化进运行时控制。这与 Leçon 07 的「完成证明（Completion Evidence）必须是可执行的」论断一致——「curl 返回 201」才算完成，而不是「代码看起来没问题」。

与课程五子系统框架的对照

这张表可以直接对照 Leçon 02 的五子系统框架逐项阅读。

减法哲学：Codex 与 Claude Code 的路线对照

将 Codex 与 Claude Code 对比极具启发性：Claude Code 走「加法」路线，把记忆、权限、subagent 集成进内核，构建完整的 Agent 运行时；Codex 走「减法」路线，保持内核尽可能精简，把更多责任移交给仓库约定与上下文工程。这正是社区常说「Codex 的 harness 哲学比它的代码更有价值」的原因。

五条可直接借鉴的设计

1. 把 AGENTS.md 当作索引页：控制在约 100 行内，指向 docs/ 中的细节，使覆盖度、新鲜度等可以机械化检查。
2. 只声明不变式，不微管理实现：只写硬约束与验证命令，其余交给模型。
3. 用 worktree 隔离环境：用环境强制任务边界，而不是在指令里请求边界。
4. 只传输环境上下文的变化：每一轮只输出变化的字段（CWD、分支、文件系统差异），不重复整套系统上下文。
5. 用 subagent 隔离上下文：同时隔离任务与上下文，让子任务不污染主循环。

参考来源说明

原文档中每一项论断都锚定于以下来源（均为原文档引用，此处保留出处描述，不附外链）：

• OpenAI「Harness Engineering」：AGENTS.md 索引页与约 100 行建议、执行不变式 / 不微管理、worktree 隔离 + 可观测性栈、验证命令内嵌约定、百万行产品案例、approval policies 与 plan mode——本文核心论断的主来源。
• OpenAI「AGENTS.md」官方规范：AGENTS.md 作为跨工具标准约定。
• Codex CLI 开源仓库：Rust 写的单体二进制。
• Context Engineering for Codex CLI（社区）：Write-Select-Compress-Isolate 框架、/compact与compact_prompt、spawn_agent/wait_agent与.codex/agents/*.toml配置。
• codex-harness-internals（社区源码分析）：build_environment_update_item增量环境上下文等实现细节。

关联课程（本仓库内可继续深入）：Leçon 03 · 让仓库成为唯一事实来源 ｜ Leçon 04 · 拆分指令文件 ｜ Leçon 07 · 清晰界定任务边界 ｜ Leçon 12 · 会话结束时留下干净状态。