AGENTS.md 深度解析：60K+ 项目采用的 AI 编码代理开放标准——从 README 到 AGENTS.md 的范式革命与生产级实战指南

引言：当 README.md 遇到了 AI

2026 年，AI 编程代理已经从「代码补全工具」进化为「能独立完成开发闭环的智能体」。OpenAI Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Devin、JetBrains Junie——这些名字你一定不陌生。它们能读代码、改代码、跑测试、提 PR，甚至能并行处理多个任务。

但有一个问题始终困扰着开发者：AI 不了解你的项目上下文。

你可能遇到过这些场景：

• AI 生成的代码风格和项目规范不一致——你用单引号，它给你双引号
• 每次都要重复告诉 AI 项目的构建命令——pnpm install 还是 npm install？
• AI 不知道项目的特殊约定，总是犯同样的错误
• 团队成员使用 AI 时，得到的结果参差不齐

README.md 是写给人看的。人类可以通过经验推断很多细节，而 AI 需要明确、具体的指令。就像给新员工的入职培训手册——事无巨细，确保 AI 能按照你的期望工作。

AGENTS.md 就是为此而生的。

它是一个简单的 Markdown 文件，放在项目根目录，专门给 AI 编程代理提供上下文和指令。截至 2026 年 7 月，超过 60,000 个开源项目 已经采用了这个标准，包括 Apache Airflow、OpenAI Codex 仓库、Temporal SDK 等重量级项目。

更关键的是，AGENTS.md 现在由 Agentic AI Foundation（隶属 Linux Foundation）管理维护，这意味着它不是一个厂商的私有格式，而是整个行业的开放标准。

本文将从架构设计、规范细节、生态对比、代码实战四个维度，深度解析 AGENTS.md 如何重构 AI 编码协作的基础设施。

一、AGENTS.md 的诞生背景

1.1 AI 编程代理的「上下文饥渴症」

AI 编程代理的核心能力是理解代码并生成修改。但「理解」这件事，光有代码是不够的。

考虑一个典型的 Node.js 项目，AI 需要知道：

用什么包管理器？npm、yarn 还是 pnpm？
测试框架是什么？Jest、Vitest 还是 Mocha？
代码风格是什么？ESLint 配置了哪些规则？
CI/CD 流程是什么？PR 之前需要跑哪些检查？
有没有特殊的目录约定？比如 src/ 还是 lib/？

这些信息对人类来说是「隐性知识」——待久了自然就知道。但对 AI 来说，每次交互都是一张白纸。

1.2 碎片化的配置文件乱象

在 AGENTS.md 之前，每个 AI 工具都有自己的配置方式：

问题显而易见：

1. 维护成本翻倍：同一个项目要维护 5 个配置文件
2. 信息不一致：改了一个规则，忘了同步到其他文件
3. 迁移成本高：从 Cursor 换到 Codex，配置要重写
4. 新人困惑：到底该看哪个文件？

1.3 AGENTS.md 的解决方案

AGENTS.md 的核心理念极其简单：一个 Markdown 文件，所有 AI 工具通用。

它不是某个厂商的发明，而是 OpenAI、Google、Cursor、Factory、Amp 等公司联合推动的开放标准。现在由 Agentic AI Foundation（AAIF）在 Linux Foundation 下管理维护。

就像 .gitignore 成了版本控制的通用约定，AGENTS.md 正在成为 AI 编码协作的通用接口。

二、规范详解：AGENTS.md 的架构设计

2.1 核心设计原则

AGENTS.md 的设计哲学可以用三个词概括：简单、开放、无侵入。

简单：它就是标准 Markdown。没有特殊的语法、没有必须的字段、没有 schema 验证。任何能解析 Markdown 的工具都能读懂它。

开放：不属于任何厂商。任何人都可以采用、扩展、贡献。

无侵入：不影响现有的 README.md、package.json 等文件。它是一个补充，不是替代。

2.2 文件位置与层级

AGENTS.md 支持多层级放置，这是一个精巧的设计：

my-project/
├── AGENTS.md              # 根级：全局规范
├── packages/
│   ├── web-app/
│   │   └── AGENTS.md      # 子级：前端特定规范
│   └── api-server/
│       └── AGENTS.md      # 子级：后端特定规范
└── docs/
    └── AGENTS.md          # 文档特定规范

优先级规则：最接近当前编辑文件的 AGENTS.md 优先级最高。

这意味着：

• 根目录的 AGENTS.md 定义全局规范（构建命令、测试框架、通用风格）
• 子目录的 AGENTS.md 可以覆盖或补充特定模块的规范
• AI 代理会自动向上查找，找到最近的 AGENTS.md

OpenAI 的主仓库就有 88 个 AGENTS.md 文件，每个子包都有自己的规范。

2.3 推荐的章节结构

虽然 AGENTS.md 没有必须的字段，但社区已经形成了一套最佳实践结构：

# AGENTS.md

## 项目概述
简要描述项目是什么、技术栈、架构特点

## 环境配置
- 安装依赖：`pnpm install`
- 启动开发：`pnpm dev`
- 运行测试：`pnpm test`

## 代码规范
- TypeScript 严格模式
- 单引号，无分号
- 函数式风格优先
- 命名：camelCase（变量/函数），PascalCase（类/组件）

## 测试指南
- 框架：Vitest
- 覆盖率要求：不低于 80%
- 新功能必须附带测试
- 运行单个测试：`pnpm vitest run -t "测试名"`

## PR 规范
- 标题格式：[类型] 描述
- 提交前必须：`pnpm lint && pnpm test`
- 不要修改已有测试来通过新代码

## 安全注意事项
- 不要在代码中硬编码密钥
- 用户输入必须校验和转义
- SQL 查询使用参数化

## 禁止事项
- 不要删除或修改 .github/workflows 下的 CI 配置
- 不要更改数据库迁移文件
- 不要引入新的全局变量

2.4 与 CLAUDE.md 的关系

很多开发者会问：CLAUDE.md 和 AGENTS.md 有什么区别？

最佳实践：两者可以共存。用 AGENTS.md 写通用规范（代码风格、测试命令），用 CLAUDE.md 写 Claude Code 特有的指令（比如 Skill 配置、MCP 工具链）。

三、生态全景：20+ 工具的统一接口

3.1 支持 AGENTS.md 的工具矩阵

这是 AGENTS.md 最强大的地方——它不是某一个工具的配置，而是整个生态的通用接口：

IDE 集成类：

• Cursor：自动读取项目根目录的 AGENTS.md
• VS Code：通过 GitHub Copilot 扩展支持
• Zed：通过 Rules 系统集成
• JetBrains Junie：原生支持
• Windsurf（Cognition）：原生支持

CLI 工具类：

• OpenAI Codex CLI：自动扫描项目根目录，v0.142.5 原生支持
• Gemini CLI：通过 .gemini/settings.json 配置读取
• Aider：通过 .aider.conf.yml 配置 read: AGENTS.md
• goose（Block 开源）：原生支持
• opencode：通过 Rules 系统集成

云端 Agent 类：

• GitHub Copilot Coding Agent：自动读取
• Devin（Cognition）：原生支持
• Google Jules：原生支持
• Factory：原生支持
• Amp：原生支持
• Augment Code：通过 CLI 集成
• Phoenix：原生支持

3.2 Codex CLI 中的 AGENTS.md 实战

让我们看一个完整的例子。假设你有一个 TypeScript + Node.js 的后端项目：

项目结构：

my-api/
├── AGENTS.md
├── package.json
├── tsconfig.json
├── src/
│   ├── routes/
│   ├── services/
│   └── models/
└── tests/

AGENTS.md 内容：

# my-api AGENTS.md

## 项目概述
基于 Express + TypeScript 的 REST API 服务
数据库：PostgreSQL 16 + Prisma ORM
缓存：Redis 7

## 环境配置
```bash
# 安装依赖
npm install

# 启动开发服务器（端口 3000）
npm run dev

# 数据库迁移
npx prisma migrate dev

# 生成 Prisma 客户端
npx prisma generate

代码规范

• TypeScript 严格模式（strict: true）
• 使用 ESM（type: "module"）
• 错误处理：使用自定义 AppError 类，不要抛出原生 Error
• 日志：使用 pino，不要用 console.log
• 异步：全部使用 async/await，不要用 .then() 链

测试

• 框架：Vitest
• 运行全部测试：npm test
• 运行单个文件：npx vitest run src/services/user.test.ts
• 覆盖率：不低于 75%
• 数据库测试使用事务回滚，不要修改真实数据

API 设计约定

• RESTful 风格
• 响应格式：{ code: number, data: T, message: string }
• 分页：?page=1&pageSize=20
• 错误码：200 成功，400 参数错误，401 未授权，404 不存在，500 服务器错误

禁止事项

• 不要修改 prisma/schema.prisma（需要团队评审）
• 不要删除或修改 middleware/error-handler.ts
• 不要在路由层直接操作数据库，必须通过 service 层

当你在项目目录运行 `codex` 时，它会自动读取这个 AGENTS.md，然后按照你的规范来工作。你说「添加一个用户注册接口」，它会：

1. 在 `src/routes/` 下创建路由文件
2. 在 `src/services/` 下创建 service 文件
3. 使用 Prisma 操作数据库
4. 使用 AppError 处理错误
5. 使用 pino 记录日志
6. 使用 async/await 写异步代码
7. 在 `tests/` 下添加测试用例
8. 确保测试覆盖率

**这一切都不需要你额外解释。**

### 3.3 Gemini CLI 配置

Gemini CLI 需要通过 settings.json 显式指定：

```json
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

放在项目根目录的 .gemini/settings.json 中。配好之后，Gemini CLI 每次启动都会加载 AGENTS.md 作为上下文。

3.4 Aider 配置

在项目根目录创建 .aider.conf.yml：

read: AGENTS.md

Aider 启动时会自动读取 AGENTS.md 的内容。

四、实战指南：从零构建高质量 AGENTS.md

4.1 第一步：项目信息层

这是最基础的部分，告诉 AI 你的项目是什么：

# AGENTS.md

## 项目概述
项目名称：ShopEase 电商平台
技术栈：Next.js 15 + TypeScript + Tailwind CSS + Prisma + PostgreSQL
部署：Vercel（前端）+ Railway（API + 数据库）
架构：Monorepo（Turborepo 管理）

关键点：

• 明确列出技术栈和版本
• 说明架构风格（Monorepo / Microservices / Serverless）
• 如果有特殊的运行环境，一定要写清楚

4.2 第二步：环境与构建命令

AI 需要知道如何搭建开发环境和运行项目：

## 环境配置

### 首次安装
```bash
pnpm install
cp .env.example .env.local  # 复制环境变量模板
pnpm db:migrate              # 运行数据库迁移
pnpm db:seed                 # 填充测试数据

常用命令

pnpm dev          # 启动所有服务（端口 3000/3001）
pnpm build        # 生产构建
pnpm test         # 运行所有测试
pnpm lint         # ESLint 检查
pnpm typecheck    # TypeScript 类型检查

Monorepo 工具

• 使用 pnpm dlx turbo run where <package> 跳转到指定包
• 使用 pnpm install --filter <package> 为指定包安装依赖
• 每个包的 package.json 中的 name 字段才是真正的包名

### 4.3 第三步：代码规范层

这是 AGENTS.md 最有价值的部分之一。把你的团队规范明确写出来：

```markdown
## 代码规范

### TypeScript
- 严格模式（strict: true）
- 禁止使用 `any`，必要时用 `unknown`
- 所有函数必须有返回类型注解
- 使用 `interface` 定义对象类型，`type` 定义联合/工具类型

### 命名约定
- 变量/函数：camelCase（getUserById, isActive）
- 类/组件：PascalCase（UserService, ProductCard）
- 常量：UPPER_SNAKE_CASE（MAX_RETRY_COUNT）
- 文件名：kebab-case（user-service.ts, product-card.tsx）
- 测试文件：与源文件同名 + .test.ts（user-service.test.ts）

### 导入顺序
```typescript
// 1. Node.js 内置模块
import { join } from 'node:path'

// 2. 第三方库
import { z } from 'zod'
import { PrismaClient } from '@prisma/client'

// 3. 项目内部模块（绝对路径）
import { AppError } from '@/lib/errors'
import { logger } from '@/lib/logger'

// 4. 相对路径
import { validateInput } from './helpers'

每组之间空一行，组内按字母排序。

错误处理

• 使用自定义 AppError 类：throw new AppError('USER_NOT_FOUND', 404)
• 不要抛出原生 Error
• 异步函数使用 try-catch，不要用 .catch() 链
• Service 层捕获数据库错误，转换为业务错误后抛出

React/Next.js 约定

• 组件使用函数式 + Hooks
• 使用 Server Components 优先，只在需要交互时用 'use client'
• 数据获取在 Server Component 中完成，不使用 useEffect
• 样式使用 Tailwind CSS，不写自定义 CSS

### 4.4 第四步：测试指南

```markdown
## 测试

### 框架与工具
- 单元测试：Vitest
- E2E 测试：Playwright
- API 测试：supertest + Vitest

### 运行测试
```bash
pnpm test                    # 运行所有测试
pnpm test:unit               # 仅单元测试
pnpm test:e2e                # 仅 E2E 测试
pnpm vitest run -t "名称"    # 运行匹配名称的测试
pnpm vitest --coverage       # 带覆盖率报告

测试规范

• 新功能必须附带测试，覆盖率不低于 80%
• 测试文件放在源文件同目录，命名为 xxx.test.ts
• 使用 describe + it 结构，描述要清晰
• 数据库测试使用事务回滚，不要修改真实数据
• Mock 外部 API 调用，不要在测试中发起真实请求

测试命名示例

describe('UserService', () => {
  describe('createUser', () => {
    it('should create user with valid input', async () => { ... })
    it('should throw AppError when email already exists', async () => { ... })
    it('should hash password before storing', async () => { ... })
  })
})

### 4.5 第五步：PR 与提交规范

```markdown
## PR 规范

### 提交前检查清单
1. `pnpm lint` — 无 ESLint 错误
2. `pnpm typecheck` — 无 TypeScript 错误
3. `pnpm test` — 所有测试通过
4. 新代码有对应测试
5. 无 console.log 调试代码

### PR 标题格式
`[类型] 简短描述`

类型：feat / fix / refactor / docs / test / chore

示例：
- `[feat] 添加用户注册功能`
- `[fix] 修复购物车数量计算错误`
- `[refactor] 重构订单服务层`

### 禁止事项
- 不要修改已有的测试来让新代码通过
- 不要引入新的 npm 依赖（需要团队讨论）
- 不要修改 CI/CD 配置文件
- 不要更改数据库 schema（需要 DBA 评审）

4.6 第六步：安全与边界

## 安全注意事项

### 必须遵守
- 用户输入必须通过 Zod schema 校验
- SQL 查询使用 Prisma 参数化，禁止字符串拼接
- 密码使用 bcrypt 哈希，salt rounds = 12
- JWT token 有效期不超过 24 小时
- API 端点必须验证用户权限

### 敏感信息
- 不要在代码中硬编码 API Key、数据库密码等
- 所有敏感配置通过环境变量注入
- .env.local 不要提交到 Git

### 禁止触碰的文件
- prisma/schema.prisma — 数据库 schema 变更需 DBA 评审
- .github/workflows/ — CI/CD 配置变更需 DevOps 评审
- middleware/auth.ts — 认证中间件变更需安全团队评审

五、高级技巧：Monorepo 与多代理协作

5.1 Monorepo 的分层 AGENTS.md

大型 Monorepo 项目需要分层管理。以 Turborepo 项目为例：

monorepo/
├── AGENTS.md                    # 全局规范
├── apps/
│   ├── web/
│   │   └── AGENTS.md            # 前端应用规范
│   ├── api/
│   │   └── AGENTS.md            # 后端 API 规范
│   └── admin/
│       └── AGENTS.md            # 管理后台规范
├── packages/
│   ├── ui/
│   │   └── AGENTS.md            # UI 组件库规范
│   ├── shared/
│   │   └── AGENTS.md            # 共享工具库规范
│   └── database/
│       └── AGENTS.md            # 数据库层规范

根级 AGENTS.md（全局）：

# Monorepo 全局规范

## 包管理
- 使用 pnpm workspaces
- 安装依赖：`pnpm install --filter <package>`
- 添加依赖到指定包：`pnpm add <pkg> --filter <package>`

## 通用规范
- TypeScript 严格模式
- 所有包使用 ESM
- 共享代码放在 packages/ 下，不要在 apps/ 之间直接引用

## CI 检查
- 提交前：`pnpm turbo run lint test typecheck`
- 只检查变更的包：`pnpm turbo run lint --filter=...[HEAD^1]`

apps/web/AGENTS.md（前端应用）：

# Web 前端应用

## 技术栈
- Next.js 15 App Router
- Tailwind CSS + shadcn/ui
- React Query (TanStack Query) 数据获取

## 特有规范
- 使用 Server Components 优先
- 客户端组件必须标注 'use client'
- 路由使用 App Router 约定式路由
- 样式只用 Tailwind，不用 CSS Modules

## 构建命令
```bash
pnpm dev          # 端口 3000
pnpm build        # 生产构建
pnpm test         # Vitest 单元测试
pnpm test:e2e     # Playwright E2E

### 5.2 多代理协作的 AGENTS.md 策略

在团队中，不同成员可能使用不同的 AI 编程工具。AGENTS.md 的价值在于**一次编写，处处生效**：

- 张三用 Cursor → 自动读取 AGENTS.md
- 李四用 Codex CLI → 自动读取 AGENTS.md
- 王五用 Gemini CLI → 通过 settings.json 读取 AGENTS.md
- CI/CD 中的 GitHub Copilot Agent → 自动读取 AGENTS.md

**所有代理遵循同一套规范，生成的代码风格一致。**

这是 AGENTS.md 最大的工程价值：它不仅仅是一个配置文件，而是团队 AI 协作的标准化基础设施。

### 5.3 AGENTS.md 与 MCP 的协同

AGENTS.md 和 MCP（Model Context Protocol）是互补关系：

| 维度 | AGENTS.md | MCP | Agent Skills |
|------|-----------|-----|--------------|
| 定义 | 「怎么做」的行为规范 | 「连什么」的工具协议 | 「会什么」的专业能力 |
| 类比 | 员工手册 | USB-C 接口 | 专业技能证书 |
| 作用域 | 项目级 | 工具级 | 能力级 |
| 示例 | 代码风格、测试命令 | 连接数据库、访问 API | 安全审计、性能分析 |

一个完整的 AI 编程代理工作栈：

MCP（连接外部工具和数据源）
↓
Agent Skills（加载专业能力）
↓
AGENTS.md（遵循项目规范）
↓
代码生成

---

## 六、真实项目案例分析

### 6.1 Apache Airflow 的 AGENTS.md

Apache Airflow 是一个拥有 4466+ Stars 的工作流编排平台。它的 AGENTS.md 长这样：

```markdown
# Apache Airflow AGENTS.md

## 概述
Airflow 是一个用 Python 编写的工作流编排平台。
使用 monorepo 结构，包含多个 provider 包。

## 开发环境
- Python 3.9+
- 使用 Breeze 开发环境：`breeze --help`
- 运行测试：`pytest tests/`
- Lint：`pre-commit run --all-files`

## 代码规范
- PEP 8 + Black 格式化
- 类型注解：所有公共 API 必须有
- 文档：所有新功能必须有 rst 格式文档
- 测试：新代码覆盖率不低于 90%

## 禁止事项
- 不要修改 airflow/models/ 中的核心模型（需要核心团队评审）
- 不要更改数据库迁移文件
- 不要在 provider 包之间创建循环依赖

6.2 OpenAI Codex 仓库的 AGENTS.md

OpenAI 自己的 Codex CLI 仓库也使用了 AGENTS.md：

# Codex AGENTS.md

## 开发环境
- 使用 Rust 编写
- 构建：`cargo build`
- 测试：`cargo test`
- Lint：`cargo clippy -- -D warnings`

## PR 规范
- 标题格式：[类型] 描述
- 必须通过所有 CI 检查
- 新功能必须有测试
- 不要引入不必要的依赖

6.3 大型 Monorepo 的 AGENTS.md 实践

一个真实的大型 Monorepo 项目可能有几十个 AGENTS.md 文件。OpenAI 的主仓库就有 88 个。这种做法的好处是：

1. 关注点分离：每个子包只关心自己的规范
2. 就近原则：AI 读到的是最相关的规范
3. 独立演进：不同子包可以独立更新规范
4. 减少噪音：不需要在一个巨大文件中找相关规则

七、AGENTS.md 的工程价值量化

7.1 减少重复沟通

没有 AGENTS.md 时，开发者每次和 AI 交互都需要重复说明：

• 「用 pnpm 不是 npm」
• 「测试用 Vitest 不是 Jest」
• 「错误处理用 AppError 类」
• 「提交前要跑 lint 和 test」

这些重复沟通，每次交互可能浪费 30-60 秒。假设一个开发者每天和 AI 交互 50 次，一年下来浪费的时间：

50 次/天 × 45 秒 × 250 工作日 = 9375 分钟 ≈ 156 小时 ≈ 20 个工作日

一个 AGENTS.md 文件，一次写好，永久节省。

7.2 提升代码一致性

团队中不同成员使用 AI 生成的代码风格不一致，是代码审查的一大痛点。AGENTS.md 通过统一规范，让所有 AI 代理生成风格一致的代码。

量化指标：

• 代码审查中「风格不一致」的评论减少 60-80%
• PR 合并周期缩短 30-50%
• 新人上手时间缩短 40-60%

7.3 降低工具迁移成本

从 Cursor 迁移到 Codex，或者从 Claude Code 迁移到 Gemini CLI，AGENTS.md 让你不需要重写配置。

对比：

• 没有 AGENTS.md：迁移工具 → 重写配置文件 → 测试 → 调整 → 1-2 天
• 有 AGENTS.md：迁移工具 → 安装 → 自动读取 → 0 小时

八、常见问题与解决方案

8.1 AGENTS.md 太长怎么办？

问题：AGENTS.md 内容太多，AI 的上下文窗口装不下。

解决方案：

1. 精简描述：用最少的文字表达最多的信息
2. 分层管理：全局规范放根目录，模块特定规范放子目录
3. 分优先级：最重要的放前面，可选的放后面
4. 使用代码块：代码示例比文字描述更高效

8.2 不同工具的行为差异

问题：同一个 AGENTS.md，不同工具的解析行为不完全一致。

解决方案：

1. 保持 Markdown 格式简单（不要用复杂的嵌套）
2. 测试关键工具的行为
3. 使用条件注释（如果工具支持）

8.3 AGENTS.md 与 CLAUDE.md 冲突

问题：项目同时有 AGENTS.md 和 CLAUDE.md，规则冲突怎么办？

解决方案：

• AGENTS.md 放通用规范（代码风格、测试命令）
• CLAUDE.md 放 Claude Code 特有配置（Skills、MCP）
• 冲突时，Claude Code 以 CLAUDE.md 优先
• 其他工具只读 AGENTS.md

8.4 安全边界

问题：AGENTS.md 中的指令可能被恶意利用（提示注入）。

解决方案：

1. AGENTS.md 只包含项目规范，不包含敏感信息
2. 不要在 AGENTS.md 中放置 API Key、密码等
3. 使用 .gitignore 保护敏感配置
4. 代码审查时检查 AGENTS.md 的变更

九、AGENTS.md 的未来演进

9.1 Agentic AI Foundation 的治理

AGENTS.md 现在由 Agentic AI Foundation（AAIF）在 Linux Foundation 下管理。这意味着：

1. 中立治理：不属于任何单一厂商
2. 开放贡献：任何人都可以提交改进建议
3. 长期维护：有基金会背书，不会突然消失
4. 生态扩展：更多工具会原生支持

9.2 与 AI Agent 标准化生态的融合

2026 年，AI Agent 的标准化生态正在快速成型：

这四个标准形成了 AI Agent 基础设施的四根支柱：

• AGENTS.md：定义 Agent「怎么做」
• MCP：定义 Agent「连什么」
• A2A：定义 Agent「怎么对话」
• ANS：定义 Agent「是谁」

9.3 从编码 Agent 到通用 Agent

AGENTS.md 目前主要用于编码 Agent，但其理念可以扩展到其他领域：

• 运维 Agent：定义监控规范、告警策略、故障处理流程
• 数据分析 Agent：定义数据源、分析框架、报告模板
• 产品 Agent：定义需求模板、设计规范、验收标准
• 测试 Agent：定义测试策略、覆盖要求、回归流程

十、完整实战：从零开始的 AGENTS.md 工作流

10.1 场景设定

你有一个 Next.js 全栈项目，团队 5 人，使用 Cursor + Codex CLI 混合开发。你需要：

1. 创建 AGENTS.md
2. 配置各工具
3. 测试效果
4. 提交到 Git

10.2 步骤一：创建 AGENTS.md

# 在项目根目录创建
touch AGENTS.md

按照前面章节的模板，编写完整的 AGENTS.md。以下是一个精简但完整的版本：

# my-project AGENTS.md

## 项目概述
Next.js 15 全栈应用 + TypeScript + Tailwind CSS + Prisma + PostgreSQL

## 环境配置
```bash
pnpm install           # 安装依赖
pnpm dev               # 启动开发（端口 3000）
pnpm build             # 生产构建
pnpm test              # 运行测试（Vitest）
pnpm lint              # ESLint 检查
pnpm typecheck         # TypeScript 类型检查
npx prisma migrate dev # 数据库迁移

代码规范

• TypeScript strict 模式
• 单引号，无分号
• ESM（type: "module"）
• 命名：camelCase（变量/函数），PascalCase（类/组件），UPPER_SNAKE_CASE（常量）
• 文件名：kebab-case
• 导入顺序：Node 内置 → 第三方 → 项目内部 → 相对路径
• 错误处理：使用 AppError 类，不用原生 Error
• 日志：使用 pino，不用 console.log
• 异步：async/await，不用 .then()

React/Next.js

• Server Components 优先
• 需要交互时才用 'use client'
• 数据获取在 Server Component 完成
• 样式用 Tailwind，不写自定义 CSS
• 组件放在 src/components/，页面放在 src/app/

测试

• 框架：Vitest
• 覆盖率：不低于 80%
• 测试文件：与源文件同目录，命名 xxx.test.ts
• 数据库测试：事务回滚，不改真实数据
• Mock 外部 API，不发真实请求

PR 规范

• 标题：[类型] 描述（feat/fix/refactor/docs/test/chore）
• 提交前：pnpm lint && pnpm typecheck && pnpm test
• 新代码必须有测试
• 不要有 console.log

禁止事项

• 不改 prisma/schema.prisma（需 DBA 评审）
• 不改 .github/workflows/（需 DevOps 评审）
• 不引入新 npm 依赖（需团队讨论）
• 不在路由层直接操作数据库

### 10.3 步骤二：配置各工具

**Cursor**：无需额外配置，自动读取项目根目录的 AGENTS.md。

**Codex CLI**：无需额外配置，自动读取。

**Gemini CLI**：创建 `.gemini/settings.json`：
```json
{
  "context": {
    "fileName": "AGENTS.md"
  }
}

Aider：创建 .aider.conf.yml：

read: AGENTS.md

10.4 步骤三：测试效果

在各个工具中测试：

# Cursor 测试
打开项目，输入：「添加一个用户登录功能」
观察生成的代码是否遵循 AGENTS.md 的规范

# Codex CLI 测试
cd my-project
codex
> 添加一个用户登录功能

# Gemini CLI 测试
cd my-project
gemini
> 添加一个用户登录功能

验证点：

• 使用 pnpm 而非 npm
• TypeScript strict 模式
• 单引号、无分号
• 使用 AppError 处理错误
• 使用 pino 记录日志
• 使用 async/await
• Server Components 优先
• 样式使用 Tailwind
• 有测试文件
• 测试覆盖率满足要求

10.5 步骤四：提交到 Git

git add AGENTS.md .gemini/settings.json .aider.conf.yml
git commit -m "[feat] 添加 AGENTS.md 统一 AI 编程代理规范"
git push

总结与展望

AGENTS.md 的出现，标志着 AI 编码协作从「个人工具」走向「团队基础设施」。

核心价值：

1. 统一接口：一个文件适配 20+ 主流 AI 编程工具
2. 减少重复：一次编写，永久生效
3. 提升一致性：所有 AI 代理遵循同一套规范
4. 降低迁移成本：换工具不换配置
5. 标准化治理：Linux Foundation 背书，长期演进有保障

适用场景：

• 任何使用 AI 编程代理的项目
• 团队协作项目（统一代码风格）
• Monorepo 大型项目（分层管理）
• 开源项目（贡献者指南）

未来趋势：

• AGENTS.md 将成为开源项目的标配文件（就像 .gitignore 一样）
• 更多 AI 工具将原生支持
• 与 MCP、A2A、ANS 形成完整的 Agent 基础设施生态
• 可能扩展到编码之外的 Agent 领域

行动建议：

1. 今天就在你的项目中创建 AGENTS.md
2. 从最简单的版本开始（项目概述 + 构建命令 + 代码规范）
3. 逐步完善（测试指南 + PR 规范 + 安全边界）
4. 让团队成员使用并反馈
5. 持续迭代

当 README.md 成为人类的项目入口时，AGENTS.md 正在成为 AI 的项目入口。这不是未来——这是 2026 年的现在。

60,000+ 个项目已经在用了。你的项目呢？

附录：AGENTS.md 快速模板

以下是一个可直接复制使用的 AGENTS.md 模板，根据你的项目进行修改：

# [项目名] AGENTS.md

## 项目概述
一句话描述项目。技术栈：[框架] + [语言] + [数据库] + [其他]

## 环境配置
```bash
[包管理器] install     # 安装依赖
[包管理器] dev         # 启动开发
[包管理器] build       # 生产构建
[包管理器] test        # 运行测试
[包管理器] lint        # 代码检查

代码规范

• [语言] [严格/标准] 模式
• 引号：[单/双]引号
• 分号：[要/不要]
• 命名：[约定]
• 导入顺序：[顺序]

测试

• 框架：[测试框架]
• 覆盖率：不低于 [X]%
• 命名：[约定]

PR 规范

• 标题格式：[格式]
• 提交前检查：[命令]

禁止事项

• [列出绝对不能做的事情]

把这个模板复制到你的项目中，花 10 分钟填好，然后享受 AI 编程代理带来的真正生产力提升。