Codex 高级用法：工程协作工作流 · 建立受控工作区
先别急着写代码，让 Codex 读懂你的仓库
复杂任务开工前，先把跨任务稳定的项目事实、行为边界和验证方式写成仓库规则，再用一个低风险小任务检查 Codex 是否真的加载并遵守了它们。
让 Codex 修改一个函数并不难。麻烦通常出现在任务变长以后：它改对了眼前的代码，却用了仓库不接受的命令；修好了功能，却碰了不该动的生成文件；说测试通过，跑的却不是项目真正的验收入口。
这些表现很容易被归结为“模型不稳定”。小编现阶段的理解是，其中一部分问题发生得更早：仓库没有把稳定的项目事实和行为约束交代清楚，Codex 只能从文件名、常见目录和当前对话里猜。
所以复杂任务的第一步不该是继续补充一大段提示词，而是先回答一个朴素的问题：无论这次让 Codex 修 Bug、做重构还是写文档，有哪些事情它都应该提前知道？
一、一轮对话里的交代，为什么撑不起复杂任务
假设我们在任务开头说：“这是一个 Node.js 项目，修改后记得跑测试，不要碰发布脚本。”这句话在当前对话里当然有效，但它仍然只是本次任务的现场要求。
换一个任务、从另一个目录启动，或者由另一个角色接手后，这些要求是否还在，取决于它有没有再次进入有效上下文。更麻烦的是，口头交代通常混着两类信息：
- 跨任务长期有效的仓库事实，例如包管理器、主要测试命令、生成文件位置；
- 只对本次任务有效的选择，例如“这次只调查，不修改”“先比较两个方案”。
两者混在一条提示词里，短任务看不出问题。任务一长，临时选择可能被误当成永久规则，长期规则又可能在后续阶段缺席。
Codex 为这类持久项目说明提供了 AGENTS.md。按照 OpenAI 当前文档，Codex 会在开始工作前读取这类文件；在项目范围内，它通常从项目根目录向当前工作目录逐层查找，并把沿途规则组成指令链。离当前工作目录更近的文件出现在后面，因此可以覆盖更上层的指导。OpenAI：Custom instructions with AGENTS.md
这条指令链在每次 Codex 运行开始时构建一次。在 CLI/TUI 中，一次新的命令运行或新启动的 TUI 会重新构建；在桌面端验证另一层目录的规则时，应把工作区打开在目标目录并开启新任务，再检查它实际加载的规则。只在当前任务的集成终端里执行 cd，不会让已经运行的任务自动重载项目指令。
这带来一个很实用的分工：仓库级稳定约束写进项目规则，本次任务的目标和临时限制留在任务现场。AGENTS.md 不是需求文档，也不该成为聊天记录的备份。
二、仓库真正需要说明什么
一份有效的项目规则不必先追求完整。先写那些“Codex 一旦猜错，就会明显返工或越界”的信息。
2.1 项目事实要能被文件验证
技术栈、目录职责和运行入口都属于项目事实，但不要把 README 改写一遍。规则里只需要指出决定工作方式的部分，并给出可检查的路径或命令。
例如：
1## 项目事实
2
3- 应用代码位于 `src/`，集成测试位于 `tests/integration/`。
4- 使用 pnpm；依赖锁文件是 `pnpm-lock.yaml`。
5- `generated/` 由构建过程生成，不直接编辑。这里每一句都能回到磁盘验证。相比“项目采用现代化工程结构”，它们更能改变实际动作：去哪里找代码、用什么工具、哪些文件不能手改。
版本号则要谨慎。会频繁变化的依赖版本已经在清单或锁文件里，就让 Codex 读取真实文件，不要再复制到 AGENTS.md。两处同时维护，迟早会冲突。
2.2 质量标准要写成可执行入口
“保证代码质量”“充分测试”看起来正确，却没有告诉 Codex 该做什么。更有用的写法是给出仓库认可的验证命令，并说明何时使用：
1## 验证要求
2
3- 修改 TypeScript 后运行 `pnpm lint` 和相关测试。
4- 改动公共 API 时运行 `pnpm test:integration`。
5- 无法执行检查时，报告未运行的命令和具体原因，不得写成“验证通过”。第三条约束的是完成声明。命令失败、环境缺依赖和测试通过是三种不同状态；“做完了”应该能回到证据，而不是依赖一句顺滑的总结。
2.3 行为边界要说明对象和后果
禁止事项写得过宽，会让 Codex 遇到正常修改也频繁停下来；写得过虚，又拦不住真正有风险的动作。
可以把边界落到具体对象：
1## 行为边界
2
3- 不提交密钥、令牌、`.env` 内容或真实客户数据。
4- 不直接编辑 `generated/`；修改它的来源文件并重新生成。
5- 未获得明确授权，不发布包、不部署、不修改远端 Issue。
6- 保留用户已有改动；发现工作区存在无关修改时不要覆盖。这些规则没有穷举所有危险命令，而是说明受保护的资产和外部副作用。以后工具变化了，边界仍然成立。
三、最小规则清单，比“项目百科”更可靠
本系列写作项目的根目录 AGENTS.md 提供了一个可以核验的例子。它没有解释所有写作技能，而是定义了三个长期角色、固定协作顺序和交接所需字段。对于任何一篇文章，“谁负责确认、谁写、谁独立质检”都不会因为选题改变，因此值得放在仓库级入口。
换成普通代码仓库，小编建议先检查下面几类信息。它们不是固定模板，缺少某一项不会让项目规则失效；只保留确实会影响 Codex 行动的内容。
- 工作入口：项目根目录、核心源码与测试的大致位置。
- 工具约定：包管理器、构建入口，以及不能混用的工具。
- 质量证据：与改动类型对应的检查、测试或构建命令。
- 修改边界：生成文件、迁移文件、公共接口等特殊对象的处理方式。
- 安全限制：凭据、隐私数据、破坏性操作和外部写入的边界。
- 完成口径：什么证据出现后才能宣称完成，哪些未验证项必须明说。
写完后再删一遍。能从 package.json 一眼读出的普通脚本列表，不必全部复制；只对某个模块有效的要求，放到更靠近该模块的规则文件；只对本次需求有效的范围，留在任务里。
OpenAI 文档还提醒了一个容易忽略的限制：Codex 会跳过空文件，并在项目规则累计达到 project_doc_max_bytes 后停止加入更多内容，当前文档给出的默认值是 32 KiB。规则写得越长，不仅噪声越多，靠后的关键约束还可能没有进入指令链。这个数值属于产品行为，后续使用时应以官方文档和本地配置为准。
四、三种常见写法，表面完整却容易失效
4.1 把仓库所有知识都塞进去
目录树、依赖列表、业务背景、发布历史一股脑写进规则，结果通常是稳定约束被大量说明文字淹没。资料没有消失，只是放错了入口。详细架构、业务文档和故障记录可以保留原路径，让任务需要时再读取；如何设计这类分层入口，是下一篇文章要处理的问题。
4.2 复制容易变化的事实
“当前使用 Node 22”“主分支暂时冻结”“本周不要改支付模块”都有时效。前一项应优先从项目配置读取，后两项更像任务或阶段状态。把它们写成永久规则后，最大的风险不是忘记更新，而是旧信息仍以权威口吻影响新任务。
4.3 同一范围留下互相冲突的命令
根目录要求运行全部测试，子目录又要求只跑局部测试，却没有解释局部规则是否替代上层规则。Codex 虽然会让更靠近当前目录的指导覆盖上层内容，但人仍然需要把覆盖关系写清楚。
例如，子模块可以直接写：
1## 本目录验证规则
2
3- 本目录改动使用 `make test-payments`，替代根目录的 `pnpm test`。
4- 涉及共享库时，仍需追加运行根目录集成测试。这样留下的是决策条件，不是两条等待猜测的命令。
五、别靠感觉验收规则，先做一个受控小任务
规则文件存在，只能证明文件写了；它是否被发现、有没有冲突、能不能改变 Codex 的动作，还需要验证。
第一次建立规则入口时，可以选择一个低风险、结果容易检查的小任务。例如：只读分析一个模块，要求 Codex 说明它加载了哪些指令、准备使用什么验证命令、哪些路径不会修改。暂时不要拿跨模块重构做第一次试验，否则规则问题和实现问题会混在一起。
先分清验证发生在哪个操作入口。CLI/TUI 可以用 codex --cd <目标目录> ... 发起一次新运行；桌面端则把工作区打开在目标目录并开启新任务。两种做法都在验证一条新构建的指令链，而不是依赖当前任务里的终端目录变化。
一个最小验证过程可以这样做：
- 以项目根目录为工作区启动一次新运行或新任务，让 Codex 复述当前有效的项目事实、验证要求和禁止事项。
- 再以存在局部规则的子目录为目标启动另一次运行或任务，检查它能否说明规则来源和覆盖关系。
- 给出一个只读小任务，观察它是否使用正确路径，是否避免触碰受保护对象。
- 让它提出后续修改的验证命令，但先不执行写入，检查命令是否与仓库规则一致。
- 发现偏差时修改规则本身，再开启一次新运行或新任务验证。不要只在当前对话里临时纠正。
官方文档也提供了相近的 CLI 验证方式：让 Codex 概括当前指令，或者通过 codex --cd <目标目录> 列出新运行加载的指令来源；指导看起来陈旧时，应在目标目录开启新运行，使指令链重新构建。OpenAI：验证 AGENTS.md 配置
验证后留下一条短记录，后面才能判断规则修改是否有效。可以直接复制下面的格式：
1## 规则验证记录
2
3- 规则来源：根目录 `AGENTS.md`；目标子目录的规则文件（按实际文件名填写）
4- 预期行为：识别局部验证命令，并避开生成文件
5- 实际行为：填写 Codex 给出的规则来源、拟执行命令和受保护路径
6- 偏差与修改：填写遗漏或冲突，以及对规则文件做的修改；无偏差则写“无”这次验证不考察 Codex 能否逐字背诵，而是看规则有没有进入决策。例如，规则写了“不要编辑生成文件”，它在分析任务时是否找到了来源文件；规则写了“无法运行测试要明确报告”，它是否区分了“未运行”和“已通过”。
到这里，我们得到的实践产物很小：一份仓库级规则清单，加一次受控任务的验证记录。它还不能解决复杂项目里所有上下文问题，也没有替任务做计划、设门禁或分配 Agent。
但仓库已经有了一个稳定起点。以后 Codex 接到新任务，不必先猜包管理器、验证入口和不可触碰的边界；而那些会随任务变化的信息，也没有被错误地钉死在永久规则里。