AGENTS.md 怎么写：为 Codex 建立项目级开发规则

AGENTS.md 的价值不是把所有项目文档复制一遍，而是把代理执行任务时必须知道的规则放在离代码最近的位置。它应当简短、可操作、可验证，并随仓库变化及时更新。

## 应该写入哪些内容

- 项目目录与主要模块的职责。 - 推荐的搜索、构建、测试和格式化命令。 - 代码风格、命名规则和架构边界。 - 禁止修改的文件、生成文件和敏感配置。 - 数据库迁移、依赖更新和部署操作的审批要求。 - 完成任务前必须提供的验证证据。

不要把密码、Token、内网地址或生产密钥写入 AGENTS.md。需要环境变量时，只记录变量名、用途和获取流程。

## 把规则写成可执行语句

“注意代码质量”无法直接验证，可以改成“修改 Java 代码后执行指定测试，并报告失败用例”。“不要破坏配置”也过于模糊，可以明确为“未经请求不得修改 application.yml；新增配置使用环境变量占位”。

规则应说明动作、范围和验收结果。这样代理遇到冲突时能做出一致判断，代码审查者也能判断是否遵守。

## 根目录与子目录如何分工

根目录文件保存整个仓库通用规则；特殊模块可以在更近的目录放补充说明。子目录规则应聚焦本模块，不要复制根规则。若两处规则可能冲突，应写清优先级和适用范围，并通过实际任务验证。

## 推荐结构

1. 项目概览：技术栈、主要入口和模块边界。 2. 工作方式：允许的工具、搜索方式和修改原则。 3. 验证命令：单元测试、构建、静态检查和手工检查。 4. 安全限制：敏感信息、生产环境和破坏性操作。 5. 交付格式：变更摘要、测试结果和剩余风险。

## 常见错误

- 内容过长，真正重要的规则被淹没。 - 命令已经失效，却没有随项目升级更新。 - 只描述风格，不提供测试和验收方式。 - 把临时任务要求写成永久规则。 - 规则要求修改生成物，却没有说明生成来源。

## 上线前验证

选择一个小任务，让 Codex先复述它读取到的关键规则，再完成修改和测试。检查它是否避开禁止文件、使用正确命令并给出证据。若结果不一致，优先改进规则的具体程度，而不是继续增加泛泛说明。