AGENTS.md 入门：让项目规则稳定生效

当你反复提醒 Codex 使用某条命令、不要修改某个目录或遵守同一种代码风格时，这些信息就适合沉淀为项目规则。AGENTS.md 的作用，是让长期有效的协作约定跟随代码库，而不是散落在每次对话里。

适合写入哪些内容

• 项目主要目录及各自职责；
• 安装、启动、测试和构建命令；
• 代码风格、命名和文件组织约定；
• 不得提交密钥、不得修改生成文件等安全边界；
• 任务完成前必须执行的验收步骤。

哪些内容不应该写进去

临时需求、一次性的页面文案、个人账号信息、密钥和经常变化的业务决定都不适合成为长期规则。规则文件越长，并不代表越有效；过时和互相冲突的规定反而会降低执行质量。

第一版保持短而明确

可以从四个小节开始：项目结构、常用命令、开发约定、完成标准。每一条尽量写成可执行的句子，例如“搜索文件优先使用 rg”“修改 PHP 文件后运行语法检查”“不要覆盖工作区中与当前任务无关的改动”。

按目录设置更具体的规则

大型项目往往包含前端、后端、移动端或基础设施等不同区域。顶层规则负责全局约定，子目录中的规则可以补充该区域特有的命令和注意事项。这样既保持总体一致，也避免把所有细节塞进一个文件。

怎样验证规则确实有效

1. 让 Codex 先概括它读取到的关键项目规则；
2. 安排一个会用到这些规则的小任务；
3. 检查它是否使用指定命令并遵守文件边界；
4. 发现歧义后修改规则，再用新任务复核。

AGENTS.md 不是写完就不再变化的说明书，而是一份随着项目经验逐渐完善的协作契约。只有稳定、重复、对结果有影响的要求，才值得保留。

推荐的维护方式

规则变更应与代码一起审查；删除已经失效的命令；出现事故或高频返工时，判断能否增加一条清晰规则。最终目标不是约束越多越好，而是让团队和 Codex 都能更快进入正确的工作方式。