AGENTS.md——跨工具配置开放标准，怎么写

你换了一个 AI 编程工具，第一件事是什么？重新告诉它你的项目结构、构建命令、代码规范、测试跑法……上周刚给 Claude Code 写的那份说明，这次用 Codex 又得重写一遍。这种重复不是能力问题，是配置碎片化的结构性问题。

AGENTS.md 就是为了解决这个问题而出现的：在仓库根目录放一个标准化的项目说明文件，让所有支持该标准的 AI 工具都能自动读取，你只写一次。

---

AGENTS.md 是什么

AGENTS.md 是一个开放标准，定义了 AI 编程工具应该在哪里查找项目说明、说明文件的推荐结构是什么。

类比一下：你进新公司，HR 会给你一份"新人入职文档"——告诉你代码放哪里、怎么启动本地环境、提 PR 有哪些规范。这份文档你只写一次，所有新人（包括 AI 工具）都读这同一份。AGENTS.md 就是你仓库里的那份"新人入职文档"，只不过读者主要是 AI。

支持情况：截稿 2026-06，Claude Code、OpenAI Codex 已明确支持 AGENTS.md；Cursor 等工具有自己的配置格式（.cursor/rules），部分工具会同时读多种配置。以各官方文档为准。

和"没有 AGENTS.md"有什么区别

不用 AGENTS.md 时，你有几种替代方案：

1. 每次手动告诉工具：在对话开始时粘贴项目背景。麻烦，而且容易忘。
2. 在 README 里写：README 是给人类看的，AI 工具不一定主动去读；而且 README 里混入大量工具说明会让文档难以维护。
3. 每个工具各自配置：CLAUDE.md、.cursor/rules、.codex……配置越来越多，改了一处其他地方不同步。

AGENTS.md 的价值不是"多一份文件"，而是为多工具提供一个公认的单一事实来源。

---

放在哪里

放仓库根目录，文件名 AGENTS.md（全大写）。

大多数工具会在启动时自动检测这个路径。如果你有 monorepo，可以在子包目录也放一份——工具通常会先找当前目录，再往上找父目录。

your-project/
├── AGENTS.md          ← 放这里
├── src/
├── tests/
├── package.json
└── README.md

---

该写什么内容

一份有用的 AGENTS.md，核心是让工具在不问你的情况下能自己做对事情。以下是几类最有价值的内容：

1. 项目结构说明

告诉工具代码在哪里、各目录是干什么的。不需要列举每个文件，说清楚主要模块就够：

## 项目结构

- `src/` — 主要业务逻辑
- `src/api/` — HTTP 接口层
- `src/core/` — 核心计算，无副作用的纯函数
- `tests/` — 测试文件，结构镜像 src/
- `scripts/` — 构建和部署脚本，不属于主应用代码

2. 构建与测试命令

这是最高频用到的。工具在帮你改完代码后，需要知道怎么验证改动有没有引入问题：

## 构建与测试

# 安装依赖
npm install

# 本地开发
npm run dev

# 构建
npm run build

# 跑全量测试
npm test

# 跑单个测试文件
npm test -- tests/core/utils.test.ts

3. 代码规范与约定

工具如果不知道你的规范，生成的代码风格会和现有代码不一致，review 时要花时间统一：

## 代码规范

- TypeScript 严格模式，禁止 any
- 函数优先：优先用函数式风格，避免不必要的 class
- 错误处理：不要 catch 后 console.log 了事，向上 throw 或返回 Result 类型
- 命名：变量 camelCase，常量 UPPER_SNAKE_CASE，类型 PascalCase
- 注释：逻辑复杂时写注释，描述"为什么"而不是"做了什么"

4. 禁区与高风险区域

有些文件或目录是不能随便改的，提前告诉工具：

## 禁区

- `src/legacy/` — 遗留代码，暂时冻结，不要修改，也不要引用里面的内容
- `.env` / `.env.production` — 不要读取或修改
- `database/migrations/` — 已执行的迁移文件不能改，新增迁移用 `npm run db:migrate:create`

5. 常见任务流程

把最频繁的工作流描述清楚，让工具能自主完成而不需要你一步步引导：

## 常见任务

### 新增一个 API 接口
1. 在 `src/api/routes/` 下新建路由文件
2. 在 `src/api/handlers/` 下实现处理逻辑
3. 在 `src/api/index.ts` 注册路由
4. 在 `tests/api/` 下补对应测试
5. 跑 `npm test` 确认通过

### 修一个 bug
1. 先写能复现 bug 的测试
2. 修代码让测试通过
3. 跑全量测试确认没有回归

---

完整可抄模板

下面是一份适合中小型 Node.js / TypeScript 项目的 AGENTS.md 模板，直接复制到你的仓库根目录，按项目实际情况修改：

# 项目说明（AGENTS.md）

本文件供 AI 编程工具自动读取，提供项目背景、规范和操作指引。

## 项目概述

这是一个 [项目一句话描述]。

技术栈：Node.js + TypeScript + [你的框架]  
主要语言：TypeScript  
测试框架：[Jest / Vitest / 其他]

## 目录结构

- `src/` — 主要源代码
  - `api/` — 接口定义和路由
  - `core/` — 核心业务逻辑（无副作用）
  - `utils/` — 通用工具函数
- `tests/` — 测试，结构镜像 src/
- `scripts/` — 构建、部署、数据库脚本
- `docs/` — 文档（人类阅读用）

## 构建与测试

# 安装
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 单元测试
npm test

# 测试 + 覆盖率
npm run test:coverage

# 类型检查（不编译）
npm run type-check

# Lint
npm run lint

## 代码规范

- **TypeScript**：严格模式（strict: true），不允许 any，用 unknown 代替
- **函数式优先**：优先纯函数和不可变数据；class 只在必要时用
- **错误处理**：用自定义 Error 类或 Result<T, E> 类型，不吞错误
- **命名**：
  - 变量/函数：camelCase
  - 类型/接口：PascalCase
  - 常量：UPPER_SNAKE_CASE
  - 文件：kebab-case
- **导入顺序**：Node 内置 → 第三方 → 内部模块（用绝对路径 `@/`）
- **测试**：每个功能对应测试，测试文件名 `*.test.ts`，描述用中文

## 禁区

以下内容**不要修改**：

- `src/legacy/` — 遗留模块，已冻结，待下个大版本移除
- `*.env*` 文件 — 不要读取、修改或在代码里硬编码敏感信息
- `database/migrations/` — 已执行的迁移文件，只增不改

## 常见任务

### 新增功能
1. 在对应目录下创建新文件
2. 写测试（先写测试是首选）
3. 实现功能，让测试通过
4. `npm run type-check && npm test` 全通过
5. 提 commit，信息格式：`feat: [功能描述]`

### 修 bug
1. 先写能复现的失败测试
2. 改代码让测试通过
3. 跑全量测试确认没有回归

### 提 PR 前
- `npm run lint` 无 error
- `npm test` 全通过
- commit 信息清晰，不用"fix"、"update"这类无信息的词

## 其他说明

- API 文档在 `docs/api.md`
- 数据库变更流程见 `docs/database.md`
- 生产部署由 CI/CD 自动处理，不要手动 push 到 main

---

和 CLAUDE.md、.cursor/rules 的关系

AGENTS.md 不是要替代这些工具专属的配置文件，它们的分工是：

文件	用途	读者
AGENTS.md	跨工具共享的项目说明（工具中立）	所有支持该标准的 AI 工具
CLAUDE.md	Claude Code 专属的行为配置和项目记忆	仅 Claude Code
.cursor/rules	Cursor 专属的规则（AI 响应风格、禁止行为等）	仅 Cursor

实践建议：把所有工具都需要知道的内容（项目结构、命令、规范）放 AGENTS.md；把工具特有的行为配置（比如 Claude Code 的权限设置、Cursor 的 AI 回复风格）放各自专属文件。

CLAUDE.md 和 .cursor/rules 在功能上有重叠，下一节（4.2 CLAUDE.md 与 Cursor Rules——项目记忆怎么组织）会专门讲如何拆分和互补，避免重复维护。

---

怎么维护，不让它变成遗忘角落

AGENTS.md 最常见的死亡方式：写完就扔，过了三个月命令全过时，工具跑错命令还没人发现。

几条防腐经验：

1. 和 README 一起改 如果你的工作流里有"改 README 的情况"，AGENTS.md 通常也要跟着改。把这两个文件心理上绑在一起，能减少遗漏。

2. CI 里跑一遍 AGENTS.md 里的命令 AGENTS.md 里写了 npm test 跑测试，那 CI 也应该跑同样的命令。如果 CI 还在跑，说明 AGENTS.md 里的命令没过时。

3. 不要写成百科全书 AGENTS.md 越长，工具真正能利用的有效信息密度越低。500 行的 AGENTS.md，工具可能只能有效处理前 150 行的信息。只写工具最需要知道的，其他信息链接到对应文档里。

4. 版本变了就改 换了主要依赖版本（比如从 Node 18 升 20、换了测试框架），立刻更新 AGENTS.md 里的命令和说明。不同步的配置比没有配置更危险。

这些维护习惯跟上下文工程和 token 管理有直接关系——写太长、太过时的上下文，本质上是在用噪音淹没有效信号。

---

故障排查表

症状	可能原因	处理方式
工具改代码时用了错误的构建命令	AGENTS.md 里的命令已过时，或工具没读到文件	确认文件在根目录且文件名全大写；更新命令；确认工具版本支持 AGENTS.md（查官方文档）
工具修改了"禁区"里的文件	禁区描述不够具体，或工具没读到对应段落	把禁区说明提到文件靠前位置；用更明确的路径而非模糊描述（"src/legacy/auth.ts" 比 "一些旧文件" 清晰）
每次工具响应都要重新解释项目背景	该工具可能不支持 AGENTS.md，或读取路径不对	查官方文档确认该工具的配置文件格式；必要时用工具专属配置（如 CLAUDE.md）
AGENTS.md 和 CLAUDE.md 内容重复，改一处漏改另一处	两个文件职责没分清	将共享内容（命令、结构）只保留在 AGENTS.md；CLAUDE.md 只放 Claude Code 专属的配置
工具理解的项目结构和实际不符	AGENTS.md 描述滞后于代码重构	重构后立刻更新 AGENTS.md；可以让工具帮你检查"AGENTS.md 里的描述和实际文件结构是否一致"

---

常见问题

Q：AGENTS.md 和 README.md 有什么区别，能合并吗？

不建议合并。README 的主要读者是人类开发者，重点是项目介绍、功能说明、安装指引；AGENTS.md 的主要读者是 AI 工具，重点是让工具能自主完成任务所需的操作细节。两者的结构优化方向不同——README 重可读性，AGENTS.md 重可操作性。

Q：项目很小，用得着 AGENTS.md 吗？

如果你的项目只有你一个人、只用一个工具，价值确实有限。AGENTS.md 的价值在于多工具并用或团队共用 AI 工具的场景。哪怕是个人项目，如果你频繁在 Claude Code 和 Codex 之间切换，写一份 AGENTS.md 会省掉相当多的重复解释。

Q：AGENTS.md 里可以写中文吗？

可以。主流 AI 工具对中文理解没有障碍。如果团队里有需要阅读这个文件的非中文母语成员，可以用中英双语。纯中文团队直接写中文即可。

Q：该怎么处理 monorepo 的情况？

在仓库根目录放一份 AGENTS.md 描述整体结构和公共约定；在各子包目录可以放各自的 AGENTS.md 描述该包的特定规范。工具通常会合并读取。以各工具官方文档的 monorepo 支持说明为准（截稿 2026-06）。

Q：AGENTS.md 里能不能描述 AI 的行为方式，比如"回复要简洁"？

可以写，但这类内容和工具专属配置（CLAUDE.md、.cursor/rules）重叠。更推荐的做法是：工具中立的操作约定放 AGENTS.md，AI 行为风格的配置放工具专属文件。下一节讲 CLAUDE.md 和 .cursor/rules 的组织方式会展开这个话题。

---

进一步延伸

AGENTS.md 是让工具"知道该做什么"的基础。要让工具"做得更规范"，还需要：

• 4.2 CLAUDE.md 与 .cursor/rules——项目记忆怎么组织：工具专属配置怎么和 AGENTS.md 配合
• 4.3 上下文工程：管好 token，防止漂移：上下文太长时如何保持 AI 工具的有效性
• 4.4 SDD——规格驱动开发：Specify → Plan → Implement：用文档驱动 AI 完成复杂任务的方法论

还有工具页可以查各工具的具体配置方式：Claude Code 工具页、Cursor 工具页。

回到起点巩固全局观：AI 编程教程大全。

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。