AGENTS.md

是什么

它是什么#

AGENTS.md 是给代理看的项目说明书。它适合写搜索方式、编辑规则、测试命令、敏感路径、完成报告格式和团队约定。

完整发现链：CODEX_HOME 默认是 ~/.codex。Codex 先在其中读取全局规则：有 AGENTS.override.md 时优先使用它，否则读取 AGENTS.md；然后从项目根（通常是 Git 根）沿目录逐级走到当前工作目录，每一层都按 AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames 的顺序选择一个文件并累计内容。越靠近当前目录的项目规则越具体。

项目规则默认最多累计 32 KiB，由 project_doc_max_bytes 控制；需要兼容其他项目说明文件时，可在 project_doc_fallback_filenames 配置候选文件名。超过上限的后续内容不会继续加入，因此根层规则应简洁，把模块细则放在更近的目录。

何时使用

什么时候用 / 不用#

当你连续两次纠正同一类行为，就该写入 AGENTS.md。不要把一次性任务要求、临时实验参数、个人口令、私有 token 或只对当前线程有效的决策写进去。

示例

可复制示例#

## Repository Expectations
- Preserve unrelated dirty worktree changes.
- Use rg for search and apply_patch for manual edits.

## Verification
- Run the narrowest relevant test first.
- Report changed files, commands, failures, and residual risk.

apply_patch 是 Codex 在内部进行精确文本编辑的一种方式示例；用户不需要在 Desktop UI 里寻找名为 “apply_patch” 的按钮。你只需描述希望修改的文件、范围和边界。

层级

如何设计 AGENTS.md 层级#

把 AGENTS.md 想成项目里的操作协议。根目录写全局原则，子目录写局部规则。越靠近文件的规则越具体，但不应该互相矛盾。

检查清单

写 AGENTS.md 的检查清单#

• 搜索方式推荐 rg、rg --files，说明不要用慢搜索扫全仓库。
• 编辑方式可以约定 Codex 内部使用 apply_patch 做精确编辑，避免无关格式化和改动用户未授权文件；这不是要求用户点击某个 UI 按钮。
• 测试命令列出最窄测试、完整测试、构建、lint 和浏览器检查方式。
• 敏感路径标注 .env、证书、生产配置、数据目录、生成产物。
• 完成证据要求最终报告包括改动、验证、风险、未完成项、链接或 commit。

反模式

不要把这些写进 AGENTS.md#

AGENTS.md 应该稳定、可复用、能被未来任务理解。不要写口令、一次性实验参数、临时聊天决定、过期路径、个人偏好吐槽，或者会让 Codex 永久误解项目边界的含糊规则。

坏例子：
- 永远不要改后端。
- 有问题自己决定。
- token 是 sk-...

好例子：
- 默认不要改 backend/public_api，除非用户明确要求。
- 发现需求冲突时停止并报告，不要猜测。
- 不要读取或提交 .env、certs/、private_data/。

真实实例

真实实例：历史复合案例#

请求：在不破坏既有工作的前提下修改一个静态指南。角色：主线程解释规则层级、划定写域并整合验证；执行者只处理分配页面；独立 reviewer 检查真实 diff 和脱敏结果。

写域与证据：
- 允许：目标 HTML、对应静态检查
- 只读：共享资源、生成上下文、Git 状态
- 禁止：环境文件、证书、凭据、私人数据和无关 dirty 文件

验证：目标 diff、最窄检查、全站链接/锚点、浏览器抽样
重要恢复：若生成索引与 live 文件不一致，则以 live repo 为准并记录漂移
结果：既有 dirty 修改保持不动，公开提交只含批准范围
停止条件：规则矛盾、敏感路径风险、写域扩大或验证无法执行

生成上下文只保存结构提示，不发布源会话、人员、机器或私人路径。完整 Goal、Worktree、review、授权与 receipt 见 团队协作历史复合案例；该摘录是多个可核验片段的教学组合。