AGENTS.md：给 Codex 写项目级持久规则

适用场景

这篇手册适合想让 Codex 在一个项目里长期遵守固定约定的用户。比如每次修改后都要运行 pnpm lint，文档站文章必须写 source，不要改动某个目录，或者 PR 说明必须包含验证结果。

OpenAI 官方文档说明，AGENTS.md 可以为 Codex 提供项目级自定义说明。Codex 会在工作时读取这些说明，并按靠近当前文件的规则执行。

步骤 1：判断规则是否应该写进 AGENTS.md

不是所有要求都适合写进 AGENTS.md。

适合写进去的内容：

• 项目运行命令。
• 测试、lint、build 的验证方式。
• 内容 frontmatter 要求。
• 代码风格和文件组织约定。
• 不要修改的目录或生成物。
• 完成任务前必须检查的清单。

不适合写进去的内容：

• 当前这一次任务的临时要求。
• 账号、密钥、token、客户数据。
• 过期的偏好。
• 太抽象的口号，例如“写高质量代码”。

判断方法很简单：如果这条规则未来很多任务都要遵守，适合写进 AGENTS.md；如果只服务当前任务，写在提示词里。

步骤 2：把 AGENTS.md 放在正确位置

最常见的位置是项目根目录：

your-project/
├─ AGENTS.md
├─ package.json
└─ src/

如果某个子目录有特殊规则，可以在子目录里再放一个 AGENTS.md：

your-project/
├─ AGENTS.md
└─ content/
   ├─ AGENTS.md
   ├─ news/
   └─ tutorials/

Codex 会优先使用离目标文件更近的说明。也就是说，content/AGENTS.md 可以覆盖或补充根目录规则，适合写内容目录专属规范。

步骤 3：写清楚项目命令

AGENTS.md 里最有价值的内容之一是验证命令。不要只写“运行测试”，要写具体命令和适用场景。

示例：

# AGENTS.md

## 验证

- 修改前端页面后运行 `pnpm lint`。
- 修改路由、内容读取或 SEO 后运行 `pnpm build`。
- 如果只改 Markdown/MDX 内容，至少检查 frontmatter 是否包含必填字段。

这样 Codex 不需要猜测项目用 npm、pnpm 还是 yarn，也不容易漏掉构建检查。

步骤 4：写清楚内容和文件规则

对于内容站，AGENTS.md 可以直接写文章规范：

## 内容规范

- 资讯文章放在 `content/news`。
- 教程文章放在 `content/tutorials`。
- 使用手册文章放在 `content/manual`。
- 每篇文章必须包含 `title`、`description`、`date`、`updated`、`category`、`tags`、`source`、`status`。
- 没有官方软件截图时，不要生成意向图或概念图。

这种规则非常适合当前项目，因为它能让 Codex 每次写文章时都记住结构和发布要求。

步骤 5：写清楚边界和安全要求

如果项目里有不能动的文件或敏感目录，也应该写清楚：

## 边界

- 不要修改 `.env`、密钥文件或本地数据库。
- 不要删除用户已有内容。
- 不要回滚未明确要求回滚的 Git 改动。
- 下载外部资源前，优先确认来源是否官方。

这类规则能减少误改和越界操作。

步骤 6：保持 AGENTS.md 简短可维护

AGENTS.md 不是越长越好。太长会让规则难以执行，也容易包含过期信息。

建议结构：

# AGENTS.md

## 项目定位

## 开发命令

## 内容规范

## 验证要求

## 禁止事项

每段都写可执行规则，不写泛泛而谈的价值观。

常见错误

不要把当前任务完整需求复制到 AGENTS.md。任务结束后它会变成噪音。

不要写密钥、账号、客户信息和内部隐私数据。

不要让根目录和子目录规则互相矛盾。如果确实需要覆盖，要在子目录说明里写清楚原因。

不要长期不维护。项目脚本或目录变了，AGENTS.md 也要同步更新。

小结

AGENTS.md 是 Codex 项目级协作质量的底座。写好项目定位、命令、内容规范、验证要求和禁止事项，就能让 Codex 在每次任务里更稳定地遵守团队约定。