# AGENTS.md 配置指南

`AGENTS.md` 之于 Codex，如同 `CLAUDE.md` 之于 Claude Code。它是一个 Markdown 文件，放在项目中告诉 AI 编程助手：这个项目有什么规范、应该怎么写代码、哪些事情不能做。

如果你已经在用 Claude Code 的 `CLAUDE.md`，那么 `AGENTS.md` 的概念对你来说应该很熟悉。两者的理念一致，但在格式和细节上有一些差异。本文将详细介绍 `AGENTS.md` 的配置方法，并帮助你在两个工具之间高效复用项目规范。

---

> **它已经不只是 Codex 的文件了。** 2026-03，Anthropic、OpenAI、Google、AWS、Microsoft、
> Salesforce 共同成立 **Agentic AI Foundation（AAIF）**，把三份开放规范作为共同基础：
> **MCP**（工具与上下文层）、**AGENTS.md**（agent 行为规范）、**Goose**（参考实现）。
> 也就是说，写一份 `AGENTS.md` 现在能被越来越多的工具直接读取，而不只是 Codex。

## AGENTS.md vs CLAUDE.md

在深入 `AGENTS.md` 之前，先了解它与 `CLAUDE.md` 的异同：

| 对比项 | AGENTS.md（Codex） | CLAUDE.md（Claude Code） |
|--------|---------------------|--------------------------|
| 所属工具 | OpenAI Codex CLI | Anthropic Claude Code |
| 文件格式 | Markdown | Markdown |
| 加载层级 | 全局 / 仓库根 / 子目录（三级） | 全局 / 项目根 / 子目录（三级） |
| 全局位置 | `~/.codex/AGENTS.md` | `~/.claude/CLAUDE.md` |
| 覆盖机制 | 子目录可覆盖父级规则 | 子目录可追加/覆盖规则 |
| 写作风格 | 偏向简洁列表，指令式 | 支持详细解释，对话式也可 |
| 社区采用 | 快速增长，已有大量开源项目采用 | 广泛采用，生态成熟 |
| 版本控制 | 推荐提交到仓库 | 推荐提交到仓库 |
| 互认性 | 不读取 CLAUDE.md | 不读取 AGENTS.md |

> **关键点**：两者互不读取。如果你同时使用两款工具，需要分别维护 `AGENTS.md` 和 `CLAUDE.md`。但好消息是，核心内容可以复用。

---

## 基础配置

### 文件位置

在项目根目录创建 `AGENTS.md`：

```
your-project/
  AGENTS.md          ← 仓库级配置
  src/
  tests/
  package.json
```

### 基本语法

`AGENTS.md` 就是标准的 Markdown 文件。Codex 会在启动时读取并遵循其中的指令。最常用的格式是**无序列表**：

```markdown
# AGENTS.md

- All code should be written in TypeScript with strict mode enabled
- Use Prettier for formatting, ESLint for linting
- Tests use Vitest, placed in `__tests__/` directories
- Run `npm run lint && npm test` before completing any task
- Never modify files in the `vendor/` directory
- API responses must follow the standard envelope format: `{ code, data, message }`
```

你也可以使用标题来组织不同类别的规则：

```markdown
# AGENTS.md

## 代码规范
- 使用 TypeScript strict 模式
- 变量命名使用 camelCase，类型使用 PascalCase
- 每个函数不超过 50 行

## 测试要求
- 单元测试覆盖率目标：80%
- 测试文件与源文件同名，后缀 `.test.ts`
- Mock 外部依赖，不发起真实网络请求

## 禁止事项
- 不要使用 `any` 类型
- 不要直接操作 DOM（使用 React 状态管理）
- 不要在循环中使用 `await`（使用 `Promise.all`）
```

### 语言选择

`AGENTS.md` 的内容可以用**中文**或**英文**编写。Codex 对两种语言都能正确理解。但考虑到团队协作：

- **个人项目**：用你习惯的语言
- **团队项目**：建议用英文（保持与代码一致）
- **国内团队**：中文也完全没问题

---

## 分层配置

`AGENTS.md` 支持三级配置，从全局到具体目录逐层细化：

### 第一层：全局配置

位置：`~/.codex/AGENTS.md`

适用于你所有项目的通用规范：

```markdown
# 全局 AGENTS.md

## 通用规范
- 代码注释使用英文
- Git commit message 遵循 Conventional Commits
- 所有密码、密钥、token 不得硬编码在源码中
- 生成代码前先阅读相关的现有代码，保持风格一致
- 如果不确定某个改动的影响，先在注释中说明，不要自行决定

## 输出偏好
- 优先使用项目已有的依赖库，不随意引入新依赖
- 错误处理要完整，不要吞掉异常
- 日志输出要有意义，包含上下文信息
```

### 第二层：仓库级配置

位置：项目根目录 `AGENTS.md`

针对特定项目的规范：

```markdown
# AGENTS.md

## 项目简介
这是一个 React + Node.js 全栈电商项目，使用 TypeScript 开发。

## 技术栈
- 前端：React 19 + TailwindCSS + Zustand
- 后端：Node.js + Fastify + Prisma
- 数据库：PostgreSQL 16
- 测试：Vitest + Playwright

## 代码规范
- 组件文件使用 PascalCase：`UserProfile.tsx`
- 工具函数使用 camelCase：`formatDate.ts`
- API 路由使用 kebab-case：`/api/user-orders`
- 数据库字段使用 snake_case：`created_at`

## 项目结构
- `src/components/` - React 组件
- `src/pages/` - 页面组件
- `src/api/` - 后端 API 路由
- `src/lib/` - 共享工具库
- `prisma/` - 数据库 schema 和迁移

## 运行命令
- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm test` - 运行所有测试
- `npm run lint` - 代码检查
- `npx prisma migrate dev` - 执行数据库迁移
```

### 第三层：子目录配置

位置：任意子目录的 `AGENTS.md`

针对特定模块的额外规范，**叠加在上层规则之上**：

```
your-project/
  AGENTS.md                  ← 项目级规则
  src/
    components/
      AGENTS.md              ← 组件目录规则
    api/
      AGENTS.md              ← API 目录规则
```

例如 `src/components/AGENTS.md`：

```markdown
# 组件规范

- 所有组件必须是函数组件（不用 class 组件）
- Props 必须有 TypeScript 接口定义
- 每个组件必须有 displayName
- 样式使用 TailwindCSS，不要写内联 style
- 复杂组件拆分为子组件，单文件不超过 200 行
- 通用组件放在 `ui/` 子目录
```

例如 `src/api/AGENTS.md`：

```markdown
# API 规范

- 所有端点必须有请求参数校验（使用 Zod schema）
- 统一错误格式：`{ code: number, message: string, details?: any }`
- 数据库操作必须在事务中执行
- 敏感操作必须记录审计日志
- 分页接口统一使用 cursor-based pagination
```

### 覆盖优先级

当多级 `AGENTS.md` 存在冲突时，**就近原则**生效：

```
全局（~/.codex/AGENTS.md）
  ↓ 被仓库级覆盖
仓库根（项目/AGENTS.md）
  ↓ 被子目录覆盖
子目录（项目/src/api/AGENTS.md）← 最高优先级
```

实际行为：

- 子目录 `AGENTS.md` 的规则优先于上级
- 上级没有被覆盖的规则仍然有效
- 多级规则是**叠加**关系，不是完全替换

---

## 实战模板

以下是几个经过实战验证的模板，可以直接复制到你的项目中。

### 前端 React 项目

```markdown
# AGENTS.md

## 项目信息
React 19 + TypeScript + TailwindCSS 前端项目。

## 代码规范
- 使用函数组件 + Hooks，禁止 class 组件
- 状态管理使用 Zustand，不要引入 Redux
- 样式使用 TailwindCSS，不写 CSS 文件
- 使用 `@/` 路径别名引用 src 下的模块
- 组件 Props 定义为 interface，命名为 `{组件名}Props`

## 文件命名
- 组件文件：PascalCase（`UserAvatar.tsx`）
- Hook 文件：camelCase + use 前缀（`useAuth.ts`）
- 工具文件：camelCase（`formatDate.ts`）
- 常量文件：camelCase（`apiEndpoints.ts`）

## 组件规范
- 每个组件导出 Props 类型和组件本身
- 使用 `React.memo` 包装纯展示组件
- 事件处理函数命名为 `handle{事件名}`
- 避免在 render 中创建新对象或函数

## 测试
- 使用 Vitest + React Testing Library
- 测试文件放在 `__tests__/` 目录
- 优先测试用户行为，而非实现细节
- 运行命令：`npm test`

## 依赖管理
- 添加新依赖前检查现有依赖是否已能满足需求
- 优先使用轻量级库
- 所有依赖必须有 TypeScript 类型定义
```

### 后端 Python/FastAPI 项目

```markdown
# AGENTS.md

## 项目信息
Python 3.12 + FastAPI + SQLAlchemy 后端服务。

## 代码规范
- 类型注解：所有函数参数和返回值必须有类型注解
- 异步优先：IO 操作一律使用 async/await
- 文档字符串：所有公开函数使用 Google 风格 docstring
- 导入排序：标准库 → 第三方 → 本地模块（用 isort 管理）

## 项目结构
- `app/api/` - API 路由（按功能分 router）
- `app/models/` - SQLAlchemy 数据模型
- `app/schemas/` - Pydantic 请求/响应模型
- `app/services/` - 业务逻辑层
- `app/core/` - 配置、安全、依赖注入
- `tests/` - 测试文件，镜像 app 目录结构
- `alembic/` - 数据库迁移

## 编码规范
- 路由函数命名：`get_users`、`create_order`（动词_名词）
- Service 层方法命名：与路由函数对应
- 数据模型字段使用 snake_case
- 所有数据库操作通过 Service 层，路由层不直接操作 ORM
- 敏感数据（密码、token）不能出现在日志和响应中

## 错误处理
- 业务异常使用自定义 Exception 类
- 统一异常处理器返回标准格式：`{"code": int, "message": str}`
- 数据库操作包裹在 try/except 中，捕获 IntegrityError 等
- 不要使用 bare except

## 测试
- 框架：pytest + pytest-asyncio + httpx
- 使用 fixture 管理测试数据库和客户端
- 运行：`pytest -v --cov=app`
- 最低覆盖率目标：80%

## 环境管理
- 使用 .env 文件管理配置，通过 pydantic-settings 加载
- 不同环境的配置差异通过环境变量覆盖
- 绝不在代码中硬编码数据库连接字符串、密钥等
```

### 全栈项目

```markdown
# AGENTS.md

## 项目信息
全栈 Web 应用：前端 Next.js 15 + 后端 API Routes + PostgreSQL。
Monorepo 结构，使用 Turborepo 管理。

## 目录结构
- `apps/web/` - Next.js 前端
- `apps/api/` - 独立 API 服务（Node.js + Fastify）
- `packages/ui/` - 共享 UI 组件库
- `packages/types/` - 共享 TypeScript 类型
- `packages/utils/` - 共享工具函数
- `packages/db/` - 数据库 schema（Drizzle ORM）

## 通用规范
- 语言：TypeScript strict 模式
- 格式化：Prettier（配置已在根目录）
- Lint：ESLint（配置已在根目录）
- 提交前运行：`turbo lint test`

## 前端规范（apps/web/）
- 使用 App Router，不用 Pages Router
- Server Components 优先，Client Components 只在必要时使用
- 数据获取使用 Server Actions 或 Route Handlers
- 样式使用 TailwindCSS
- 图片使用 next/image 组件

## API 规范（apps/api/）
- RESTful 设计，URL 使用 kebab-case
- 请求校验使用 Zod
- 返回格式：`{ success: boolean, data?: T, error?: string }`
- 认证使用 JWT，中间件统一校验
- 限流规则写在路由装饰器中

## 数据库规范（packages/db/）
- 使用 Drizzle ORM，schema 定义在 `schema/` 目录
- 迁移命令：`pnpm db:migrate`
- 命名：表名复数（`users`），字段 snake_case
- 所有表必须有 `created_at` 和 `updated_at`
- 软删除使用 `deleted_at` 字段

## 共享包规范
- packages 之间通过 workspace 引用
- 共享类型定义在 `packages/types/` 中
- 不在 packages 中引用 apps 的代码
```

---

## 高级技巧

### 与 CLAUDE.md 并存

如果你的项目同时使用 Codex 和 Claude Code，可以在项目中同时维护两个配置文件：

```
your-project/
  AGENTS.md          ← Codex 读取
  CLAUDE.md          ← Claude Code 读取
  src/
  ...
```

**核心规范可以共享**。两个文件的大部分内容（技术栈、命名规范、目录结构等）是相同的，只有工具特定的指令不同。

推荐的做法是：

1. 先写好一份核心规范
2. 分别复制到 `AGENTS.md` 和 `CLAUDE.md`
3. 根据各自工具的特性微调格式

或者更优雅的方式，在两个文件的开头互相引用：

```markdown
# AGENTS.md

> 本项目同时使用 Codex 和 Claude Code。核心规范见下文。
> Claude Code 用户请参考 CLAUDE.md。

## 核心规范
（共享内容）
```

### 团队协作最佳实践

#### 提交到版本控制

`AGENTS.md` 应该提交到 Git 仓库，让团队成员共享相同的 AI 编码规范：

```bash
git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"
```

#### 代码审查中包含 AGENTS.md

修改 `AGENTS.md` 时应该像修改代码规范一样进行 Code Review：

```markdown
<!-- PR 描述 -->
## 改动说明
更新 AGENTS.md：
- 新增 API 分页规范（cursor-based）
- 明确禁止在组件中直接调用 fetch
- 添加日志格式要求
```

#### 渐进式完善

不需要一次写完所有规范。推荐的做法：

1. **第一天**：写基本的技术栈和命名规范（10-20 行）
2. **第一周**：根据 Codex 的实际表现补充规则
3. **持续迭代**：遇到 Codex 做得不好的地方，就往 `AGENTS.md` 加一条规则

### 常见的有效指令

以下类型的指令在 `AGENTS.md` 中效果最好：

```markdown
## 高效指令（Codex 遵循度高）

- 明确的格式要求：使用 PascalCase 命名组件文件
- 明确的禁止事项：不要使用 any 类型
- 运行命令：完成后运行 npm test 确认通过
- 文件位置规范：测试文件放在 __tests__ 目录
- 依赖限制：不要引入新的 npm 包，使用现有依赖
```

```markdown
## 低效指令（建议避免）

- 过于模糊：写好的代码
- 主观判断：使用最佳实践
- 超出范围：考虑用户体验（AI 无法运行 UI）
- 矛盾指令：优先性能 + 优先可读性（需要明确优先级）
```

### 条件性规则

你可以为不同文件类型或目录设置不同规则：

```markdown
## 文件类型规则

### *.test.ts 文件
- 每个 describe 块不超过 10 个 test
- 使用 factory 函数创建测试数据，不要硬编码
- 异步测试必须有超时设置

### *.api.ts 文件
- 必须有请求参数校验
- 必须有错误处理
- 返回值必须有类型注解

### migrations/*.sql 文件
- 不要直接修改，使用 ORM 迁移工具生成
```

---

## 从 CLAUDE.md 迁移

如果你已有 `CLAUDE.md`，转换为 `AGENTS.md` 非常简单。两者都是 Markdown 格式，核心内容可以直接复用。

### 迁移步骤

**第一步：复制基础内容**

```bash
cp CLAUDE.md AGENTS.md
```

**第二步：调整 Claude Code 特有的引用**

将 `CLAUDE.md` 中 Claude Code 特有的概念替换为 Codex 的对应概念：

| CLAUDE.md 中的写法 | AGENTS.md 中的写法 |
|--------------------|--------------------|
| "当 Claude 修改文件时..." | "当修改文件时..." |
| "使用 `/compact` 压缩上下文" | （删除，Codex 无此命令） |
| "通过 `@` 引用文件" | （删除，Codex 使用不同的引用方式） |
| "Hook: PostToolUse..." | "完成任务后运行..." |
| "子代理处理..." | "使用 Cloud Exec..." |

**第三步：精简格式**

Codex 更偏好简洁的列表式指令。如果 `CLAUDE.md` 中有大段解释性文字，可以精简为要点：

迁移前（`CLAUDE.md` 风格）：

```markdown
## 代码风格

在本项目中，我们遵循 Google TypeScript 风格指南。所有变量名
使用 camelCase，类名使用 PascalCase。特别注意，枚举值使用
全大写 SNAKE_CASE。导入语句需要按以下顺序排列：首先是 Node.js
内置模块，然后是第三方包，最后是本地模块。每组之间空一行。
```

迁移后（`AGENTS.md` 风格）：

```markdown
## 代码风格
- 遵循 Google TypeScript 风格指南
- 变量名：camelCase
- 类名：PascalCase
- 枚举值：SCREAMING_SNAKE_CASE
- 导入顺序：内置模块 → 第三方包 → 本地模块（组间空行）
```

**第四步：添加 Codex 特有指令**

```markdown
## Codex 特定配置
- 完成所有文件修改后，运行 `npm run lint && npm test` 验证
- 如果测试失败，自动修复并重新运行
- 不要修改 .env 和 .env.local 文件
```

### 迁移对照表

| 概念 | CLAUDE.md 写法 | AGENTS.md 写法 |
|------|---------------|----------------|
| 项目描述 | 自由格式段落 | 简要列表或段落 |
| 代码规范 | Markdown 列表 | Markdown 列表（相同） |
| 禁止事项 | "不要做 X" | "Never do X" 或 "不要做 X" |
| 运行命令 | "请运行 `npm test`" | "Run `npm test`" 或直接列出 |
| 文件结构 | 代码块展示目录树 | 代码块展示目录树（相同） |
| 工具配置 | settings.json 引用 | config.toml 引用 |

### 维护两份文件

如果需要长期同时维护 `AGENTS.md` 和 `CLAUDE.md`，建议：

1. **指定一个为"主版本"**：通常是你更常用的工具对应的文件
2. **修改主版本后同步到另一个**：可以写个简单脚本自动化
3. **工具特有的规则分开管理**：通用规范放在文件前半部分，工具特有规则放在末尾

---

## 调试与验证

### 确认 AGENTS.md 生效

最简单的验证方式是给 Codex 一个会触发规则的任务：

```bash
# 假设 AGENTS.md 要求使用 TypeScript
codex "创建一个 hello world 函数"

# 如果 AGENTS.md 生效，Codex 会生成 .ts 文件而非 .js 文件
```

### 规则不生效的排查

1. **文件位置**：确认 `AGENTS.md` 在项目根目录或对应的子目录
2. **文件名**：必须是 `AGENTS.md`（大写，非 `agents.md`）
3. **格式问题**：确保 Markdown 格式正确（列表前有空行等）
4. **规则冲突**：检查多级 `AGENTS.md` 是否有矛盾指令
5. **指令太模糊**：尝试用更具体的描述替换

---

## CLAUDE.md 与 AGENTS.md 如何选

同时维护两份配置文件听起来很自然，但**两份会逐渐分叉**：你在 `AGENTS.md` 里加了一条规则，却忘了同步到 `CLAUDE.md`，于是两个工具的行为开始不一致。下面这套决策建议能帮你避开这个坑。

### 先看你用几个工具

- **只用 Claude Code（单工具）**：直接写 `CLAUDE.md` 就够了。Claude Code 原生读取 `CLAUDE.md`，还会叠加全局 memory 与路径级规则（嵌套 `CLAUDE.md` / `.claude/rules`），不需要再额外维护 `AGENTS.md`。
- **团队多工具协作（Claude Code + Codex / Cursor / Copilot / Cline / Gemini / Aider / Zed 等）**：把 `AGENTS.md` 作为**唯一事实来源**。除 Claude Code 外的大多数工具都读取 `AGENTS.md`，而 Claude Code 默认只读 `CLAUDE.md`。

### 多工具团队的推荐做法：薄 CLAUDE.md 引用 AGENTS.md

不要维护两份完整且会分叉的副本。把共享规范集中写在 `AGENTS.md`，再用一份**很薄的 `CLAUDE.md`** 把它引入，让 Claude Code 同时获得团队共享规则与 Claude 专属补充：

```markdown
# CLAUDE.md

@AGENTS.md

## Claude Code 专属补充
- 用 `/model` 在 Sonnet 4.6 / Opus 4.8 之间按任务切换
- 复杂改动先 `/plan` 再执行
- 任务切换时用 `/clear`，长会话到逻辑断点用 `/compact`
```

这样共享规范只有一处来源（`AGENTS.md`），`CLAUDE.md` 仅保留 Claude Code 独有的指令，从根本上避免双份分叉。

### 快速决策表

| 场景 | 维护什么 | 说明 |
|------|---------|------|
| 只用 Claude Code | 仅 `CLAUDE.md` | 原生读取，无需 `AGENTS.md` |
| 只用 Codex / 其它工具 | 仅 `AGENTS.md` | 这些工具不读 `CLAUDE.md` |
| 多工具团队 | `AGENTS.md`（事实来源）+ 薄 `CLAUDE.md`（`@AGENTS.md`） | 单一来源，避免分叉 |

> 关于 `CLAUDE.md` 的分层、模板与上下文控制，详见 [CLAUDE.md 配置指南](/docs/usage/claude-md)。

---

## 下一步

- [Codex 快速上手](/docs/getting-started/codex-quick-start) -- 安装和配置 Codex
- [Codex vs Claude Code 深度对比](/docs/getting-started/codex-vs-claude-code) -- 两者差异全面对比
- [Hooks 系统](/docs/advanced/hooks) -- Claude Code 的事件钩子（类似概念）
- [命令行技巧](/docs/usage/cli-tips) -- 提升 AI 编程效率的实用技巧