Appearance
Codex AGENTS.md 怎么写：项目规则与最佳实践
AGENTS.md 是给 Codex 读取的项目说明文件。它不负责描述某一个临时任务，而是保存项目中反复适用的规则：代码结构、测试命令、风格约定、禁止操作和完成标准。
把稳定规则写进 AGENTS.md，可以减少你每次重复解释项目背景的时间，也能让 Codex 在不同任务中保持一致的工作方式。
AGENTS.md 适合写什么
适合写长期有效的项目事实：
- 项目启动、测试、类型检查和构建命令
- 主要目录的职责和不能跨越的边界
- 命名、格式化、错误处理和日志约定
- 哪些文件不能修改，哪些操作必须先确认
- 完成任务前必须运行的验证
- 如何处理敏感数据、密钥和生产配置
不适合写当天的临时需求、某一次任务的完整提示词或已经过期的版本信息。
一个实用的文件结构
可以从下面的结构开始：
text
# Project instructions
## Overview
说明项目入口和主要模块。
## Commands
列出安装、开发、测试、类型检查和构建命令。
## Code rules
说明目录边界、命名和错误处理约定。
## Verification
说明完成任务前必须运行什么。
## Safety
说明密钥、生产数据和破坏性操作的限制。文件不需要写得很长。优先记录 Codex 无法从代码中稳定推断、但每次任务都需要遵守的规则。
根目录和子目录的规则
大型仓库可以在根目录放通用规则，再在子目录放更具体的规则。例如：
- 根目录：包管理器、通用测试和 Git 约定
frontend/AGENTS.md：组件、样式和浏览器测试要求services/payments/AGENTS.md：支付模块的安全和审计规则
越靠近当前文件的规则，通常越适合描述该目录的细节。不要在不同文件里重复写同一条规则，否则未来修改时容易出现冲突。
把命令写成可执行的事实
不要只写“运行测试”。写出仓库真实使用的命令，例如 npm test、npm run typecheck 或 npm run build。
同时写清楚哪些命令只适用于某个目录、哪些测试必须在数据库或容器启动后运行。错误的命令会让 Codex 产生虚假的完成感。
明确修改边界
好的规则会直接告诉 Codex：
- 业务代码在
src/，生成文件在dist/，不要手动编辑生成文件。 - API 返回结构有兼容要求，修改前先检查调用方。
- 新增依赖前必须说明理由，不要自动替换包管理器。
- 数据库迁移和权限变更需要先给出计划。
这些规则比“请小心修改”更有用，因为它们可以在 diff 中被检查。
让验证成为完成标准
可以在文件中写：
完成代码修改后，运行受影响模块的测试、类型检查和构建。汇报每条命令的结果；如果命令失败，区分本次修改造成的失败和已有失败。
验证规则应和仓库实际脚本一致。不要把不存在的命令写进 AGENTS.md，也不要要求每个小改动都运行耗时数小时的全量流程。
安全规则必须具体
安全部分至少应该说明：
- API Key 只从环境变量或密钥管理系统读取。
- 不要读取、打印或提交真实用户数据。
- 不要自动执行删除数据库、修改权限或发布生产的操作。
- 需要破坏性操作时先展示计划和影响范围。
不要把真实密钥、内部域名或生产账号写入 AGENTS.md。这个文件会进入仓库，默认应该按可公开阅读的项目文档处理。
常见写法错误
把 AGENTS.md 写成超长提示词
过度冗长会掩盖真正重要的约束。删掉 Codex 可以从代码或 package.json 中直接看到的内容。
写互相矛盾的规则
例如一处要求使用 npm，另一处要求使用 pnpm。选择项目实际使用的包管理器，并在根目录统一说明。
只写风格，不写验证
格式化规则很重要，但测试、构建、接口兼容和安全边界更应该出现在文件里。
从网上复制陌生项目的规则
不同仓库的目录、命令和风险完全不同。复制前逐条验证，不要把别人的路径和命令直接带进项目。
如何验证 AGENTS.md 生效
新建或修改后，给 Codex 一个只读任务：让它总结当前目录适用的规则和验证命令，但不要改文件。
如果总结遗漏了关键规则，检查文件位置、标题结构和是否存在更近目录的规则。然后给一个小任务，观察它是否真的执行了规定的测试和边界。
你也可以在任务中明确要求：先读取适用的 AGENTS.md，再说明本次任务会遵守哪些规则。这样更容易发现上下文没有加载的问题。
和提示词、Skills 的区别
AGENTS.md：项目级长期规则。- 提示词：当前任务的目标、上下文和约束。
- Skills：可以跨项目复用的完整工作流、资源和脚本。
- MCP：把外部工具和上下文接入 Codex。
它们可以配合使用，但不要把同一条规则复制到所有位置。项目事实放在 AGENTS.md，一次性目标放在提示词，跨项目流程才适合沉淀为 Skill。
FAQ
AGENTS.md 必须放在项目根目录吗？
根目录适合放全局规则，子目录也可以放更具体的规则。关键是文件位置要和它负责的代码范围一致。
AGENTS.md 会自动被 Codex 读取吗？
Codex 支持读取适用的 AGENTS.md 指令，但具体加载范围和优先级会随产品形态和版本变化。任务开始时让 Codex 总结当前适用规则，可以帮助你确认它确实看到了文件。
可以把 API Key 写进 AGENTS.md 吗？
不可以。只写变量名、密钥来源和安全要求，不写真实凭据。
文件应该写多长？
以“每条规则都能影响任务决策”为标准。一个清晰的几百字文件通常比几千字的重复说明更有用。