AGENTS.md 怎么写：让 Codex 按项目规则工作

TL;DR：AGENTS.md 应该写什么

AGENTS.md 是给 Codex 读取的项目协作规则。最有价值的内容不是口号，而是项目命令、目录边界、代码约定、测试方式、提交要求和敏感文件清单。

一份可直接改写的规则模板

# 项目协作规则

## 开始前
- 先阅读 README、现有测试和最近的变更
- 先给出计划，确认范围后再修改文件

## 常用命令
- 安装：npm install
- 开发：npm run dev
- 检查：npm run typecheck
- 测试：npm test

## 修改边界
- 不要修改密钥、生产配置和生成目录
- 每次任务保持改动小且可回滚
- 完成后说明验证命令和未解决风险

怎么让规则真正生效

把根目录规则写成所有任务都需要遵守的约束，把子目录规则写成局部约定。不要把会频繁变化的价格、额度或临时环境状态写死在规则文件里。每次修改规则后，先让 Codex 复述它理解到的约束。

常见报错与解决

| 问题 | 原因 | 建议 | | --- | --- | --- | | Codex 没有遵守规则 | 文件位置不在工作目录层级 | 将规则放在项目根目录或对应子目录 | | 规则互相冲突 | 多个 AGENTS.md 约束不一致 | 合并重复规则，明确局部规则的范围 | | 规则太长 | 重要命令被大量说明淹没 | 保留可执行命令和验收要求 |

FAQ：AGENTS.md 的维护方式

可以只写一份 AGENTS.md 吗？

可以。项目变大后，再按前端、后端或文档目录增加局部规则。

能把 API Key 写进 AGENTS.md 吗？

不能。规则文件会进入代码仓库，任何密钥都应使用环境变量或安全凭证管理。

AGENTS.md 会替代人工代码审查吗？

不会。它能减少重复沟通，但生产改动仍需要人工看 diff、测试结果和权限影响。