把 Codex 放进一个真实仓库后，最先遇到的问题通常不是模型不会写代码，而是它不知道团队如何写代码。入口在哪里、哪些目录是生成产物、测试应该跑哪一组、什么操作必须先确认，这些信息如果只存在于成员记忆里，代理就只能边猜边做。AGENTS.md 的价值，是把这类长期有效的协作约定变成仓库的一部分。
上下文不是越多越好
一次性任务中的目标和验收条件应该留在提示词里；跨任务稳定存在的规则才适合进入 AGENTS.md。如果把产品需求、临时排期和大段架构历史全部塞进去，关键约束反而容易被噪声淹没。
一个实用的判断标准是：下个月换一项任务，这条说明是否仍然成立？如果答案是肯定的，它可能属于仓库指南；如果只服务当前需求，就应该留在当前会话。凭据、内部地址和个人数据则不应该进入任何会被提交的指令文件。
理解指令的作用域
Codex 会在开始工作前查找 AGENTS.md。全局目录可以保存个人通用偏好，仓库根目录承载团队级约定，子目录则可以覆盖局部规则。代理从项目根目录向当前工作目录逐层组合指令，离目标文件更近的说明优先级更高。同一目录存在 AGENTS.override.md 时，它用于替代该层的普通指南。
这种分层适合大型仓库。例如根文件要求所有改动通过格式化和安全检查，services/payments/AGENTS.md 再补充支付服务的集成测试命令。局部文件只描述差异，不必复制根文件全文。这样既减少重复，也避免两份规则长期漂移。
写入真正能执行的信息
一份有效的仓库指南至少回答四类问题：
- 代码、测试、配置和生成文件分别放在哪里；
- 如何安装依赖、启动项目、构建并运行最小相关测试；
- 命名、格式、模块边界和兼容性有哪些硬约束；
- 完成任务前必须检查什么，以及哪些动作不能擅自执行。
以这个 Hugo 博客为例，最有用的信息不是“保持高质量”，而是下面这种可以直接采取行动的说明：
- 文章源文件放在 `content/`，生成站点位于 `public/`。
- PaperMod 位于 Git 子模块中；优先使用 `layouts/` 做本地覆盖。
- 本地预览运行 `hugo server -D`，提交前运行 `hugo --minify`。
- 检查生成的 `public/`，不要提交无关构建变化。
反过来，“写出优雅代码”“测试要充分”这类口号缺少判定方式。把它们改成具体命令、可观察结果或明确禁止项，Codex 才能据此决定下一步。
还要区分指令与工具配置。AGENTS.md 说明团队希望工作怎样完成；模型、沙箱、审批策略和外部工具连接等运行设置属于 .codex/config.toml；需要反复执行且包含固定步骤的专项流程，更适合封装成 skill。把不同职责拆开，能让指南保持短小，也避免修改写作规则时意外改变运行权限。
把指南当成可维护的工程资产
不要试图第一次就覆盖全部边界。先记录最常用的目录、命令和完成标准，然后观察代理反复出现的错误：是否选错测试范围，是否修改了生成文件，是否忽略兼容要求。只有当问题确实重复时，再加入一条短而明确的规则。
修改指南后，应在新的 Codex 会话中验证，因为指令链通常在一次运行开始时加载。可以让 Codex 概括当前生效的说明，再给它一个小任务，检查它是否选择了正确目录和验证命令。对于子目录规则，还要分别从仓库根目录和目标子目录验证，确保覆盖关系符合预期。
最后保留人工检查：指南是否仍与真实脚本一致，是否引用了已经删除的命令，是否把建议误写成强制规则。过期但语气坚定的文档，比没有文档更危险。
实践清单
- 从仓库结构、构建命令、测试入口和禁止操作开始；
- 用可执行命令与可观察结果代替抽象口号；
- 根目录写共享规则，子目录只补充局部差异；
- 不保存秘密，也不混入一次性需求；
- 用真实任务验证，并根据重复失误持续精简更新。
下一篇：从模糊需求到可验证补丁