为什么你需要 AGENTS.md？
每次和 Codex 开启新对话，它都像是「失忆的新员工」——不知道项目规范、不清楚怎么跑测试、每次都要从头解释一遍你的代码风格。
写一遍 AGENTS.md，把它当作 Codex 的「项目入职便签」，以后每次对话它都自动读取，省去重复交代。
一句话总结：AGENTS.md = 给 Codex 看的长期记忆文件。
三级层级：从全局到局部
Codex 启动时会按顺序合并多个 AGENTS.md，越靠近当前目录的文件优先级越高（后面的会覆盖前面的）。
| 层级 | 路径 | 作用范围 |
|---|---|---|
| 全局 | ~/.codex/AGENTS.md |
所有项目通用规则 |
| 项目级 | <项目根>/AGENTS.md |
团队共享规范 |
| 子目录级 | <项目>/backend/AGENTS.md |
仅该模块生效 |
建议：先配全局（你的个人偏好），再配项目（团队规范），最后按需配子目录。
模板：直接抄这个
在项目根目录新建 AGENTS.md，填入以下内容（按实际情况修改）：
# 项目规范
## 项目简介
这是一个基于 Next.js + TypeScript 的个人博客系统，使用 Tailwind CSS 做样式。
## 常用命令
- 安装依赖：`npm install`
- 本地开发：`npm run dev`（访问 http://localhost:3000）
- 运行测试：`npm test`
- 类型检查：`npm run typecheck`
- 构建生产包：`npm run build`
## 代码规范
- 组件用 PascalCase 命名（`PostCard.tsx`）
- Hook 用 camelCase，以 use 开头
- 禁止在组件内直接写长 SQL 拼接，用 parameterized query
- 新增功能必须补充或更新测试
## 安全边界
- 不读取或提交 `.env`、密钥和私有凭据
- 修改数据库迁移前先说明影响范围
## 验收标准
完成一个改动后，请：
1. 列出修改的文件
2. 说明验证命令和结果
3. 标注未验证项和剩余风险
三个实用技巧
技巧 1：用 /init 快速生成初稿
在 Codex CLI 中输入 /init，它会自动扫描项目并生成一份基础 AGENTS.md，你再按需修改即可。比自己从零写省事很多。
技巧 2：让 Codex 犯过的错误不再犯
如果 Codex 在某个问题上反复出错，不要只口头纠正——把结论加进 AGENTS.md，例如：
## 常见坑点
- Post.status 字段：0=正常 1=禁用 2=删除，不要用 Boolean 类型
- calculateDiscount() 有历史遗留问题，不要动，折扣逻辑在 DiscountStrategy 里
技巧 3：内容多了就拆文件
当 AGENTS.md 太长时，把详细内容拆成独立文件，在主文件里引用：
## 参考文档
- 代码审查标准：参见 [code_review.md](./code_review.md)
- 架构说明：参见 [architecture.md](./architecture.md)
Codex 会在需要时按需读取，避免上下文被无关内容撑大。
完整文件结构示例
my-project/
├── AGENTS.md # 项目级规范（团队共享）
├── backend/
│ └── AGENTS.md # 后端子目录特有规则
├── frontend/
│ └── AGENTS.md # 前端子目录特有规则
└── code_review.md # 代码审查标准（被 AGENTS.md 引用）
来源：本文根据今日头条创作者「你的壶掉了」2026-07-21 发布的《新手也能看懂的 Codex 保姆级教程》改写，原文地址：https://www.toutiao.com/a7664857931644469786。AGENTS.md 配置方法综合自 OpenAI 官方文档及 Duke University OIT 最佳实践指南。
资料最后核对日期：2026-08-15 · 内容整理自 CodexGuide 社区公开教程