AGENTS.md 中文指南：让 Codex 正确理解你的仓库规则

AGENTS.md 是什么

AGENTS.md 是给代码智能体读取的项目说明。它适合保存会反复影响任务的规则：构建命令、目录边界、测试要求、代码风格、部署限制和安全注意事项。

它不是项目 README 的替代品。README 面向所有使用者，AGENTS.md 更关注“智能体在这个目录里工作时必须怎么做”。

推荐的最小结构

# 项目工作规则

## 项目结构
- `src/`：应用代码
- `tests/`：自动化测试

## 常用命令
- 安装：`npm install`
- 检查：`npm run check`
- 测试：`npm test`

## 修改约束
- 不改生成文件
- 不提交 `.env` 或密钥
- 保留用户已有的未提交修改

## 完成标准
- 相关测试通过
- 没有新增类型错误
- 最终说明列出改动和验证结果

一开始不要写成几十页的规章。只保留能改变行动的规则，并让命令可直接执行。

作用域怎么理解

仓库根目录的 AGENTS.md 通常影响整个项目；子目录可以放更具体的文件，用于覆盖或补充局部规则。把前端、后端或基础设施的特殊要求放在对应目录，比把所有内容堆在根文件更容易维护。

当前任务中的直接要求仍然最具体。如果临时需求与仓库长期规则冲突，应先明确冲突，而不是悄悄选择一种解释。

应该写什么，不该写什么

适合写入：

• 真实可用的安装、测试、格式化和构建命令；
• 哪些目录由生成器维护；
• 数据库、部署和权限操作的安全边界；
• 项目独有的命名和架构约定；
• 完成任务前必须验证的检查项。

不适合写入：密钥、账号 ID、临时故障记录、已经失效的命令，以及无法验证的口号式要求。

如何验证规则是否有效

给 Codex 一个只读任务，让它复述当前目录适用的关键规则，并指出来源文件。然后再给一个小改动，观察它是否运行了指定检查、避免了禁止目录，并在结果里报告验证情况。

可以从最小 AGENTS.md 模板复制一份，再按仓库事实删改。