9. 用AGENTS与配置文件教会Codex理解项目

来源：Codex

预计阅读时间：45 分钟
本篇目标：把 TaskFlow 的结构、测试方式和安全约束固化下来，并通过一次新会话验证它们是否真的生效。

前面几篇里，我们反复告诉 Codex：

• TaskFlow 只使用 Python 标准库；
• 测试必须使用临时目录；
• 不能读写真实 data/tasks.json；
• 修改后要先跑局部测试，再跑完整测试；
• CLI 行为变化时要同步 README。

如果这些要求每次都由你重写，时间久了总会漏掉一两条。AGENTS.md 的作用，就是把“这个仓库中应该长期遵守的工作方式”放进项目，让 Codex 在开始任务前自动读取。

配置文件解决的是另一类问题：Codex 用什么沙箱模式、什么审批策略、哪些功能开启。两者一个管“在项目里怎样做事”，一个管“Codex 以什么运行方式开始工作”。

一、README、AGENTS.md 和 config.toml 分别管什么

文件	主要读者	适合放的内容	不适合放的内容
README.md	项目使用者	安装、功能、命令示例、数据格式	Agent 的内部工作约定
AGENTS.md	Codex 等开发 Agent	项目结构、验证命令、持续约束、完成标准	API Key、短期临时任务、大段用户手册
config.toml	Codex 运行时	模型、推理强度、沙箱、审批、功能开关等	项目业务规则和敏感凭据

一个实用的判断方法是：

• 用户需要知道的，写进 README；
• Codex 每次开工都应遵守的，写进 AGENTS.md；
• Codex 应该以什么权限和功能运行，写进 config.toml；
• 只对当前一次任务有效的，直接写在本次提示词里。

官方建议也是保持 AGENTS.md 简短、准确，从重要规则开始，再根据反复出现的问题逐步增加。参考：Codex best practices。

二、用 /init 建立初稿，但不直接照单全收

在 TaskFlow 根目录启动 Codex，然后输入：

/init

/init 会根据当前目录快速生成一份初始 AGENTS.md。它是一个起点，不是项目规则的最终答案。

生成后先不要急着提交，让 Codex 说明它是从哪些文件推断出项目命令和结构的。它能看见当前仓库里有什么，却不一定知道我们前面特别在意的数据安全和验收顺序。

可以继续输入：

请审查刚生成的 AGENTS.md，暂时不修改。

请核对：
1. 项目结构是否与当前仓库一致；
2. 测试命令是否已经实际运行验证；
3. 是否写明测试使用临时目录；
4. 是否保护真实 data/tasks.json；
5. 是否保留 Python 标准库约束；
6. 是否写清了修改后的验收方式；
7. 是否有空泛、重复或无法执行的句子。

对每个问题给出证据和修订建议。

三、为 TaskFlow 写一份足够用、但不臃肿的 AGENTS.md

可以把下面的版本作为核对基准，再按你的实际文件名调整：

# TaskFlow 项目协作指南

## 项目概况

TaskFlow 是一个使用 Python 3.11+ 标准库开发的命令行任务管理器，不依赖第三方库。

保持实现简单，并确保现有 JSON 数据仍然兼容。

## 重要文件和目录

- `taskflow.py`：CLI 入口和核心功能
- `tests/`：unittest 测试
- `samples/`：不含敏感信息的示例输入
- `README.md`：面向用户的命令和使用说明

## 验证方式

- macOS、Linux、WSL2：`python3 -m unittest discover -s tests -v`
- Windows：`py -m unittest discover -s tests -v`
- 修改后先运行相关测试，再运行完整测试。
- 修改 CLI 行为后，使用临时数据运行受影响的命令，并记录退出码。
- 不要只根据 Codex 的完成报告判断结果，必须检查实际输出和 Diff。

## 项目约束

- 除非任务明确改变这一约定，否则只使用 Python 标准库。
- 自动测试必须使用临时目录。
- 测试和调试不得读取或覆盖真实的 `data/tasks.json`。
- 日常开发任务不得访问网络或安装依赖。
- 除非已经制定并测试迁移方案，否则必须兼容旧任务数据。
- 不得提交密钥、个人绝对路径、运行数据或缓存文件。
- 不要进行与当前任务无关的重构。

## 完成标准

- 请求的功能已经实现，重要错误场景有测试覆盖。
- 相关测试和完整测试全部通过。
- 用户可见的 CLI 行为发生变化时，已经同步更新 `README.md`。
- 最终报告列出修改的文件、运行的命令、实际结果和仍然存在的限制。

这份文件里没有“写出优雅代码”“遵循最佳实践”这类句子，因为它们无法直接验收。“测试使用临时目录”和“CLI 变化同步 README”则是可以观察的行为。

把它交给 Codex 时，不要让它不加判断地整段覆盖：

请用下面的内容作为核对基准，修订仓库根目录的 AGENTS.md。

先根据当前项目确认文件名、命令和目录是否真实存在。保留初稿中已经准确的项目信息，删除重复或空泛内容。不要把示例中与当前仓库不符的路径照抄进去。

<粘贴上面的基准内容>

修订后说明删除、保留和新增了什么，以及依据是什么。

四、理解 AGENTS.md 的发现顺序

Codex 可以同时加载多层项目指令。官方文档描述的核心顺序是：

1. 先读取 Codex 主目录中的全局指导，默认位于 ~/.codex；
2. 再从项目根目录向当前工作目录逐层查找；
3. 同一目录中优先检查 AGENTS.override.md，然后是 AGENTS.md；
4. 越靠近当前工作目录的指导越具体，会出现在合并后的更后面。

官方详细说明：Custom instructions with AGENTS.md。

对 TaskFlow 来说，刚开始只需要根目录的一份 AGENTS.md：

taskflow/
├── AGENTS.md
├── taskflow.py
├── README.md
├── samples/
└── tests/

不要因为支持分层，就立即在每个目录放一份。只有当子目录确实存在不同的构建或审查规则时，再增加更具体的指导。否则重复规则很容易日后不一致。

AGENTS.override.md 更适合明确的临时覆盖或特殊目录约束，不要把它当成“更高级的默认文件”到处使用。

五、不要假设它生效了，开新会话验证

AGENTS.md 的意义是影响新的工作过程。因此，修改完成后退出当前 Codex，在 TaskFlow 根目录重新启动。

先让它总结当前指令：

请只读取当前会话已加载的项目指导，不要修改文件。

请列出：
1. 你发现的指令文件及所在层级；
2. TaskFlow 的完整测试命令；
3. 对真实数据的保护规则；
4. 修改 CLI 后的文档要求；
5. 当前任务的完成标准。

还可以从终端做一次只读验证：

codex --ask-for-approval never "Summarize the current project instructions and their sources. Do not modify files."

官方文档也使用这类方式检查指令是否被加载。注意，--ask-for-approval never 只是说不弹出审批，不是赋予 Full Access；命令仍然受当前沙箱和配置约束。

如果它没有说出 TaskFlow 的临时目录和数据保护规则，检查：

• 文件名是否真的是 AGENTS.md；
• 文件是否位于仓库根目录到当前目录的路径上；
• 是否存在更近的 AGENTS.override.md；
• 启动 Codex 时是否位于你以为的项目目录；
• 修改后是否新开了会话。

六、用一个小任务测试行为，不只是复述规则

能复述 AGENTS.md 不等于工作时一定会遵守。继续给它一个边界清楚的小任务：

为 import-csv 增加一个“CSV 只有表头、没有数据行”的测试。

请自行根据项目指导决定使用什么测试目录、需要运行哪些验证，以及是否需要更新 README。不要读写真实任务数据。

观察它是否会：

• 使用临时目录；
• 不安装新依赖；
• 先运行相关测试，再运行完整测试；
• 在结尾报告实际运行的命令和结果；
• 根据用户可见行为是否改变，判断 README 是否需要修改，而不是机械地每次都改。

如果它遗漏了某一条，先判断是指令写得不清楚，还是本次执行偏离。只有当一个要求对后续任务都有价值时，才应该补进 AGENTS.md。

七、什么时候应该修订 AGENTS.md

适合加入的内容：

• Codex 已经重复犯过的错误；
• 评审中反复出现的同一条要求；
• 真实可运行的构建、测试和 lint 命令；
• 仓库特有的数据、兼容性或安全约束；
• 可以明确检查的完成标准。

不适合加入的内容：

• 只用一次的具体功能需求；
• 一大段代码实现细节；
• 与当前仓库无关的个人偏好；
• “保证高质量”“仔细思考”之类无法验收的口号；
• 密钥、令牌、账号密码和敏感内部地址；
• 已经过时的目录或命令。

规则越多不代表效果越好。如果一份 AGENTS.md 已经让新成员都很难找到测试命令，Codex 同样会被无关信息干扰。

八、加入最小项目配置

Codex 的个人默认配置通常放在：

~/.codex/config.toml

仓库特定配置可放在：

.codex/config.toml

官方参考：Sample configuration。

对 TaskFlow 的日常开发，一份小配置就足够：

sandbox_mode = "workspace-write"
approval_policy = "on-request"

它表示：Codex 可以在工作区内完成日常开发，需要超出边界时再请求审批。

配置文件不需要追求“把所有可用字段都写上”。字段越多，未来过时或互相冲突的可能性越高。在增加当前版本的其他配置项之前，先查阅官方配置参考或使用 codex --help。

还要注意两个边界：

• 不要把 API Key 或其他秘密写进会提交到 Git 的 .codex/config.toml；
• 不要因为项目里放了一份高权限配置，就对一个陌生仓库不加检查地使用。

九、用“文件发现”和“实际行为”做双重验收

最终验收不应该只问“你看到 AGENTS.md 了吗”，而应该包含两层。

第一层：它加载了哪些规则

让新会话列出指令来源和关键规则。如果来源不对，先解决目录和文件发现问题。

第二层：它真的按规则工作了吗

用一个小任务检查临时目录、测试顺序、README 判断和最终报告。如果行为与文字不一致，规则就还不算真正落地。

完成后输入：

/diff

确认没有密钥、个人绝对路径和与仓库不符的命令，再按实际变更提交：

git add AGENTS.md .codex/config.toml
git commit -m "add Codex project guidance"

如果验证小任务还改了测试或 README，先在 Diff 中确认这些改动，再把实际需要的文件加入提交。

十、一份可复用的项目指导检查清单

新建或审查 AGENTS.md 时，可以问：

• 文件中的目录和命令是否真实存在？
• 测试命令是否已经实际运行过？
• 哪些是项目长期约束，哪些只是当前任务？
• 规则是否可以被观察和验收？
• 是否正在重复 README、CI 或其他文档的大段内容？
• 是否有过时命令、本机路径或敏感信息？
• 更具体的子目录规则是否真有必要？
• 是否可以通过一个小任务验证它确实生效？

本篇小结

AGENTS.md 不是越长越好。它应该记录真实、持续、可执行的项目规则；config.toml 则负责 Codex 的运行默认值。新会话能复述规则，只是第一步；它能在真实任务中正确使用临时目录、运行测试并保护数据，才说明项目指导真正发挥了作用。

下一篇，我们会把 TaskFlow 升级到 2.0，并学会怎样用计划、目标、恢复和上下文整理管理一项更长的工作。