AGENTS.md 与配置

为什么仓库需要“给 Agent 的说明书”

新人会从 README、脚本和 CI 猜出项目约定；Agent 也面临同样问题，但时间更短、操作更快。AGENTS.md 把最关键的执行知识放到约定入口：

• 安装、测试、构建命令；
• 哪些目录可改、哪些是生成物；
• 代码风格和测试要求；
• 仓库特有的风险与验收标准；
• 子目录中的例外。

发现与覆盖顺序

官方文档描述的核心顺序是：

1. 先读取 Codex home 中的全局指令，优先 override，找不到再用 base；
2. 从项目根目录走到当前工作目录；
3. 每个目录最多取一个候选指令文件；
4. 越接近当前目录的内容越靠后，因此能覆盖更宽泛规则；
5. 总大小受配置上限约束，官方默认值为 32 KiB。

flowchart TB
G["~/.codex/AGENTS.override.md<br/>或 ~/.codex/AGENTS.md"] --> R["repo/AGENTS.md"]
R --> P["repo/packages/AGENTS.md"]
P --> C["repo/packages/api/AGENTS.override.md"]
C --> U["当前用户请求"]
U --> X["本轮 Context"]

官方文档 完整规则见官方 AGENTS.md 指南。

公开实现与文档对应：它解析项目根，向下走到 cwd，并从 override、默认文件和配置的 fallback 列表中选择候选。

一份有效的 AGENTS.md

# Repository instructions

- Package manager: pnpm. Do not create npm or yarn lockfiles.
- Before editing, run `git status --short` and preserve unrelated changes.
- Source lives in `packages/core/src`; `dist/` is generated and must not be edited.
- For core changes, run `pnpm --filter @acme/core test` and `pnpm typecheck`.
- Database migrations require explicit user approval.
- Keep public API changes backward compatible; document unavoidable breaks.

它有效，是因为每条都能改变行动选择或验收方式。相比之下，“写优雅代码”“多思考”几乎不可验证。

指令优先级不是简单文件排序

需要区分三类东西：

如果 AGENTS.md 写“可以访问任意密钥”，它不会自动突破沙箱。反过来，即使沙箱允许写入，指令仍可能要求不要修改某目录——这是行为约束而不是技术隔离。

Configuration：运行时选择

Codex 的配置覆盖模型、审批、沙箱、工具、MCP、特性与界面等。公开源码通过 ConfigBuilder 和 config loader 解析多层来源。

官方配置参考是变化最快的权威入口：Configuration reference。

教学示意

# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[projects."/path/to/repo"]
trust_level = "trusted"

常见失败

• 规则过长：真正关键命令被背景描述淹没；
• 规则冲突：根目录要求 A，子目录又模糊要求 B；
• 命令失真：CI 已迁移，AGENTS.md 仍写旧脚本；
• 把秘密写进去：指令会进入模型上下文，不应存凭据；
• 用指令代替权限：仅写“不要访问网络”不能取代网络沙箱；
• 覆盖范围误判：在错误 cwd 启动，导致预期子目录规则未加载。

维护方法

把 AGENTS.md 当成可测试的运行手册：

1. 新人或 Agent 是否能按它完成安装和目标测试；
2. CI 命令变化时同步更新；
3. 子目录只写差异，不重复整份根规则；
4. 定期删除失效背景；
5. 把不可违反的边界落实到权限、lint 或 CI。

准备好这些概念后，可以正式进入 源码模块地图。