写好 AGENTS.md：让项目规则真正生效

01 · 先确认规则应该放在哪里

进入你真正要修改的 Git 项目根目录。项目规则放在根目录 AGENTS.md；只有所有项目都适用的偏好才考虑个人目录。写之前先查找已有规则，避免覆盖。Codex 会沿目录读取规则，较深目录可以补充更具体的要求。

git rev-parse --show-toplevel
ls -la AGENTS.md AGENTS.override.md 2>/dev/null

02 · 编写短而可验证的约束

下面是一个前端项目示例，请先核对 package.json 确实存在这些脚本，再写入文件。规则要指向真实操作，不要只写“保证质量”。已有 AGENTS.md 时合并相关内容，不要整份替换。

# 项目规则

- 使用当前 React / TypeScript 技术栈，不新增 UI 框架。
- 只修改本次任务相关文件。
- 不修改支付、订单接口、环境变量与生产凭据。
- 修改前检查 package.json，复用已有脚本。
- 提交前运行 npm run typecheck 与 npm run build。
- 报告实际执行的检查；未执行的检查明确说明。

03 · 用小任务检查加载

从项目目录启动新的 Codex 会话，先让它只读检查规则与脚本。要求它报告实际读取的路径；回答不准确时检查启动目录、文件名以及更深目录中的覆盖规则，而不是不断追加重复指令。

codex "先不要修改文件。读取适用的 AGENTS.md，列出规则路径、项目技术栈和可运行的检查命令。"

04 · 把局部规则放回局部目录

如果后台与前台使用不同验证命令，可以在对应目录补充 AGENTS.md，只写差异。不要把临时任务记录、订单号、账号资料或密钥写进规则。文件应能被团队长期阅读；任务完成日志交给版本记录。

常见问题