AGENTS.md：写给 AI 编程搭档的项目说明

为什么需要 AGENTS.md

每个新对话都是新的上下文。Codex 并不知道项目使用什么命令、哪些目录不能改、代码需要遵循什么风格，也不知道完成后应该运行哪些检查。

AGENTS.md 是一份放在项目中的 Markdown 说明，可以把这些规则集中写下来。README 主要帮助人理解项目，AGENTS.md 更像是给 coding agent 阅读的项目操作手册。

放在哪里

普通项目最常见的做法，是在仓库根目录创建 AGENTS.md。大型仓库还可以在子目录继续放置更具体的规则：根目录写通用要求，前端、后端或数据库目录分别写自己的局部规则。

规则越靠近当前工作目录，越适合描述该区域的特殊要求。文件名和大小写要保持准确，内容也应尽量精简。

建议写哪些内容

优先写 AI 在动手前必须知道、并且能够执行或验证的规则：项目结构、常用命令、代码风格、测试方式、禁止修改的文件和最终交付要求。

# AGENTS.md

- 前端代码位于 src/，公共组件放在 src/components/
- 使用 TypeScript，不新增 any
- 不修改 .env、密钥文件和生产配置
- 修改后运行 npm test 和 npm run build
- 最终列出修改文件、验证结果和已知风险

全局规则和项目规则要分开

个人通用偏好可以放在全局规则中，例如回复语言、常用验证习惯；只属于当前仓库的命令、目录和边界则应保留在项目里。

团队共同认可的规则可以提交到版本控制。个人路径、本机工具和临时限制不适合直接进入团队仓库，应留在本地配置或覆盖文件中。

保持简短并持续更新

AGENTS.md 不是越长越好。过多背景介绍会挤占上下文，也容易让真正重要的规则被忽略。每一条内容都应该回答一个实际问题：AI 需要做什么、不能做什么、怎样证明已经完成。

当团队流程改变时，要同步更新规则；已经失效的命令和限制应及时删除。