AGENTS.md 项目说明

AGENTS.md 是写给 Codex 看的项目说明书。Codex 每次开始工作前都会先读它，所以那些你每次都要重复交代的事，比如"用 pnpm 不用 npm"、"改完要跑 lint"，写进去一次就够了。

快速生成复制本节链接

在项目根目录启动 Codex，输入：

/init

Codex 会扫描项目，生成一份 AGENTS.md 草稿。一定要自己过一遍，删掉不准确的内容，补上团队约定，再提交到仓库。

加载顺序复制本节链接

Codex 每次启动时（TUI 里是每个会话开始时）会按下面的顺序组装说明：

示例复制本节链接

全局偏好（~/.codex/AGENTS.md）复制本节链接

适用于你打开的所有项目：

# ~/.codex/AGENTS.md

## 工作约定
- 用中文回复，代码注释保持英文。
- 安装依赖优先用 pnpm。
- 增加新的生产依赖前先问我。

项目说明（仓库根目录 AGENTS.md）复制本节链接

# AGENTS.md

## 项目概况
- Next.js 16 + TypeScript，源码在 src/，文档在 content/。

## 常用命令
- 安装依赖：pnpm install
- 本地开发：pnpm dev
- 检查：pnpm lint && pnpm typecheck

## 约定
- 提交 PR 前必须通过 lint 和类型检查。
- 不要修改 src/generated/ 下的文件，它们由脚本生成。

子目录覆盖复制本节链接

某个子模块有特殊规则时，在那个目录里放 AGENTS.override.md。同一目录里有 override 文件时，普通的 AGENTS.md 会被忽略：

# services/payments/AGENTS.override.md

## 支付服务规则
- 用 make test-payments 代替 npm test。
- 不要改动密钥轮换相关代码。

写好 AGENTS.md 的建议复制本节链接

• 写 Codex 自己看代码推断不出的东西：构建和测试命令、团队约定、不能碰的目录、提交信息格式。
• 短而具体：每条规则都应该可执行。"代码要优雅"没用，"函数超过 50 行要拆分"有用。
• 大项目按目录拆分：把只跟某个模块有关的规则放到那个模块的目录里，既不占其他任务的上下文，也更省额度。
• AGENTS.override.md 不要提交：它适合临时覆盖。团队共享的规则放在 AGENTS.md 里。

代码审查规则复制本节链接

如果你用 Codex 在 GitHub 上审查 PR，可以在 AGENTS.md 里加一个 ## Code Review Rules 小节，告诉它重点检查什么：

## Code Review Rules

### 数据库迁移
- 迁移脚本必须可回滚；只加不删的字段变更可以放行。

详见云端任务与 GitHub。

使用其他文件名复制本节链接

如果仓库里已经有类似的说明文件（比如 TEAM_GUIDE.md），可以把它加进备用列表：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

改完后重启 Codex 才会生效。

检查是否生效复制本节链接

在仓库根目录运行：

codex --ask-for-approval never "Summarize the current instructions."

Codex 应该按优先级顺序复述全局和项目里的说明。如果内容不对：

• 什么都没读到：确认你在正确的目录里，文件不是空的。
• 读到的内容不对：检查上层目录或 ~/.codex 里有没有 AGENTS.override.md。
• 内容被截断：调大 project_doc_max_bytes，或者把内容拆到子目录里。
• 改了不生效：Codex 每次启动时重新读取，重启一下即可，没有缓存需要清理。

参考资料复制本节链接

• Custom instructions with AGENTS.md（官方）
• Project instructions discovery（官方）
• AGENTS.md 规范网站