如果你经常在同一个项目里使用 Codex，不要每次都重复“不要乱加依赖”“改后跑测试”。这些规则应该写进 AGENTS.md。

AGENTS.md 适合放什么

它适合放稳定的项目约定，例如：

• 项目启动和测试命令
• 后端、前端、文档分别怎么验证
• 代码风格和目录边界
• 哪些文件不能随便改
• 部署、数据库、权限相关的注意事项
• 最终回复需要说明什么

它不适合放一次性需求。比如“今天把按钮改成蓝色”应该写在当前任务里，不应该写进项目规矩。

一个可直接用的模板

# AGENTS.md

## 项目概况

这是一个 <项目类型>。主要目录：

- `client/`: 前端
- `server/`: 后端
- `docs/`: 文档

## 常用命令

- 前端检查：`npm run lint`
- 后端测试：`go test ./...`
- 构建：`npm run build`

## 修改规则

- 不要新增依赖，除非先说明必要性。
- 不要做无关重构。
- 修改共享逻辑时必须补测试。
- 不要提交或打印密钥、token、私钥内容。

## 交付要求

完成后请说明：

- 改了哪些文件；
- 如何验证；
- 有哪些未完成或风险。

多目录项目怎么写

大型项目可以在根目录放总规则，再在子目录放更具体的规则。比如：

AGENTS.md
client/AGENTS.md
server/AGENTS.md

根目录写全局边界，client/AGENTS.md 写前端命令，server/AGENTS.md 写后端测试和数据库规则。

让规则具体，不要空泛

空泛规则：

- 写高质量代码。

具体规则：

- 改 Go 代码后运行 `go test ./...`。
- 改 React 组件后运行 `npm run lint` 和 `npm run build`。
- 不要把页面文案写死在组件里，优先使用现有 i18n 文件。

Codex 更容易执行后者。

常见坑

第一，AGENTS.md 不要写成公司制度全集。太长会稀释重点。

第二，不要把互相冲突的规则写进去。比如一处说“必须新增测试”，另一处说“不要改测试”。

第三，规则变了要更新文件。过时的项目说明会让 Codex 反复做错。

官方来源

• https://developers.openai.com/codex/concepts/customization
• https://developers.openai.com/codex/learn/best-practices