AGENTS.md 怎么写？让 Codex 按你的项目规则做事 ​

AGENTS.md 是 Codex 的项目工作规则文件。

Codex 开始工作前会读取 AGENTS.md，用它理解项目背景、常用命令、测试方式、代码规范和完成标准。维护好 AGENTS.md，可以让 Codex 每次都按同一套规则执行任务，减少重复解释和重复犯错。

适合谁 ​

这篇文章适合：

• 已经开始用 Codex 修改项目的人
• 希望 Codex 少犯重复错误的人
• 团队里多人协作使用 Codex 的项目负责人
• 想让 Codex 遵守固定构建、测试和 review 流程的人

这篇文章解决什么问题 ​

很多人刚开始用 Codex 时，只会在聊天框里反复提醒：

• 不要乱改无关文件
• 不要随便加依赖
• 改完记得测试
• 先告诉我你准备怎么改

这些提醒如果每次都手动说，很容易漏。AGENTS.md 的作用，就是把这些项目规则固定下来，让 Codex 每次进入项目时都能先读到。

先运行 /init ​

在 Codex 项目中，先运行：

/init

/init 可以快速生成初始 AGENTS.md。

但自动生成的文件只是起点。你应该继续手动编辑，让它符合项目真实的构建、测试、review 和发布流程。

推荐写法 ​

可以把 AGENTS.md 写成下面这样：

# AGENTS.md

## 项目说明

这是一个 Next.js + TypeScript 项目，用于 xxx。

## 常用命令

- 安装依赖：`npm install`
- 本地启动：`npm run dev`
- 类型检查：`npm run typecheck`
- Lint：`npm run lint`
- 测试：`npm test`
- 构建：`npm run build`

## 工作规则

- 修改前必须先说明影响范围和计划
- 默认最小改动
- 不要无理由新增依赖
- 不要重写无关模块
- 改业务逻辑必须补测试
- 改 UI 必须检查 loading、empty、error、mobile 状态
- 完成后必须说明测试结果和潜在风险

## 完成标准

- 相关测试通过
- lint、typecheck、build 通过
- 行为符合验收标准
- diff 可 review

示例中的 xxx 需要替换为你的真实项目说明。

每一部分怎么写 ​

项目说明 ​

项目说明要让 Codex 快速理解这个项目是什么。

建议写清楚：

• 项目技术栈
• 项目用途
• 主要业务目标
• 是否有不能随便改的模块

示例：

## 项目说明

这是一个 Next.js + TypeScript 项目，用于管理课程内容和用户订单。
前端使用 App Router，样式使用 Tailwind CSS。
默认不要进行大范围重构。

常用命令 ​

常用命令不要让 Codex 猜，直接写清楚。

## 常用命令

- 安装依赖：`npm install`
- 本地启动：`npm run dev`
- 类型检查：`npm run typecheck`
- Lint：`npm run lint`
- 测试：`npm test`
- 构建：`npm run build`

如果项目没有测试命令，可以写：

- 测试：当前项目暂未配置测试命令

工作规则 ​

工作规则是 AGENTS.md 最重要的部分。

建议写成明确、可执行的限制：

## 工作规则

- 修改前必须先说明影响范围和计划
- 默认最小改动
- 不要无理由新增依赖
- 不要修改无关文件
- 改业务逻辑必须补测试
- 完成后必须说明测试结果和潜在风险

完成标准 ​

完成标准用来告诉 Codex：任务做到什么程度才算结束。

## 完成标准

- 相关测试通过
- lint、typecheck、build 通过
- 行为符合验收标准
- diff 可 review

高级技巧：把 Codex 犯过的错写进去 ​

维护 AGENTS.md 的核心方法很简单：

Codex 每犯一次重复错误，就把对应规则补进 AGENTS.md。

如果它经常乱加依赖，就加：

如果它经常大范围重构，就加：

如果它经常改完不测试，就加：

可以继续补哪些规则 ​

AGENTS.md 不需要一次写完。你可以先写最常用的规则，再根据 Codex 的实际表现慢慢补。

常见可补充规则包括：

• 哪些目录不要动
• 哪些文件改动前必须先确认
• 是否允许新增依赖
• 是否必须保持移动端兼容
• 修改 UI 后要检查哪些状态
• 完成任务前要运行哪些命令
• 最终回复需要说明哪些内容

如果规则很多，可以按主题分组：

## 依赖规则

- 不要新增依赖，除非先获得确认
- 优先使用项目已有工具和组件

## UI 规则

- 改 UI 必须检查桌面端和移动端
- 必须处理 loading、empty、error 状态

## 验证规则

- 完成前运行相关测试
- 如果无法验证，必须说明原因和风险

常见问题 ​

AGENTS.md 是不是越长越好？ ​

不是。

AGENTS.md 要写关键规则，不要堆空话。

比如：

不要无理由新增依赖

比下面这种更有用：

请保持代码质量

因为前者具体，Codex 更容易执行。

AGENTS.md 需要一次写完吗？ ​

不需要。

它应该持续维护。每次 Codex 出现可复用的问题，就把规则补进去。

不会编程也需要写 AGENTS.md 吗？ ​

需要。

不会编程的人更应该维护 AGENTS.md，因为它可以减少你反复解释需求的成本。

你可以先写清楚：

• 这个项目是做什么的
• Codex 不要做什么
• 修改前要先说明什么
• 完成后要检查什么

下一步 ​

你可以先在自己的项目里运行 /init，生成初始 AGENTS.md。

然后把这几类内容补进去：

• 项目说明
• 常用命令
• 工作规则
• 完成标准

后面使用 Codex 时，只要发现它反复犯同一种错误，就把这条规则写进 AGENTS.md。