直接答案
AGENTS.md 是持久仓库指导，不是百科全书；只保留每次相关任务都值得加载的规则，并用嵌套文件缩小作用域。
这篇内容解决什么问题
创建和维护适合 Codex CLI 的 AGENTS.md
把 AGENTS.md 用作持久工程约定
一次性任务要求应留在当前提示词，跨任务始终有效的仓库事实才进入 AGENTS.md。典型内容包括权威构建命令、目录边界、编码规范、验证步骤和禁止触碰的生成文件。
它用于指导模型决策，不替代格式化器、权限策略或 CI。必须强制执行的规则应由测试、lint、沙箱或 hook 提供机械保障。
从可执行的最小模板开始
好的规则具体、短小且可以验证。不要写“保持高质量”这类无法执行的口号，应写明目录、命令和判断标准。
以下模板只示范结构。替换为仓库真实命令后，再交给团队审查。不存在的命令会持续误导每一个任务。
# Repository Guide
## Scope
- Work only in the module named by the task.
- Do not edit generated files under `dist/`.
## Commands
- Install: `<project-install-command>`
- Test: `<project-test-command>`
- Typecheck: `<project-typecheck-command>`
## Conventions
- Follow patterns in the nearest existing module.
- Keep API changes backward compatible unless explicitly approved.
## Verification
- Run the narrow test first, then the required repository checks.
- Report commands run and any checks that could not be completed.用嵌套文件表达目录级规则
仓库根文件描述全局约定，子目录中的 AGENTS.md 只补充该子树特有规则。离目标文件更近的指导用于更具体的范围，避免在根文件堆积前端、后端、移动端的全部细节。
发生冲突时应先消除文档矛盾，而不是期待模型猜测团队意图。将相互冲突的命令留在不同层级会导致任务表现不稳定。
find .. -name AGENTS.md -print
git status --short
git log -n 5 -- AGENTS.md记录高价值事实，不复制整份文档
每条内容都应回答“如果不加载这条，Codex 是否很可能犯错”。长篇 API 参考、偶尔使用的发布流程和某一类专项任务，适合链接到文档或整理为按需加载的 Skill。
对构建和测试命令说明适用范围，例如前端修改只运行什么、共享协议修改还需运行什么。这样既避免每次执行全部检查，也不会漏掉跨模块契约。
- 仓库结构与模块所有权。
- 安装、构建、测试、lint 的权威命令。
- 公共 API、数据库和依赖变更的审批边界。
- 秘密、生成文件和迁移文件的处理规则。
- 完成任务时必须提供的验证证据。
用只读任务验证指导是否清晰
修改 AGENTS.md 后，不要立即交给大任务。让 Codex 在只读模式概括适用规则、计划运行的命令和需要审批的动作，能够快速暴露歧义。
验证的是理解结果，不要要求模型输出隐藏系统提示或内部上下文。它只需用自己的话说明将遵循哪些仓库约定。
codex -C /path/to/repo -s read-only "阅读适用于 frontend 模块的 AGENTS.md。概括允许修改的范围、必须运行的检查和需要先询问的操作；不要修改文件。"持续清理过时和重复规则
构建系统、目录或发布流程变化时同步更新 AGENTS.md。重复规则越多，越容易出现一个位置更新、另一个位置仍旧过时。
把 AGENTS.md 纳入正常代码审查：确认命令真实可运行、作用域准确、没有密钥与机器专属路径，并记录重要规则变更的原因。
- 定期运行文档中的命令。
- 删除已经由工具自动强制的冗余描述。
- 将专项工作流迁移到 Skill。
- 将个人偏好与团队规则分开。
官方来源与核验范围
本文以公开官方文档为事实依据；命令和配置可能随客户端版本变化，执行前请同时核对对应来源。
查看技术核验方法