AGENTS.md 与 CLAUDE.md：如何为 AI 编程助手建立项目协作规范

随着 Codex、Claude Code 等 AI 编程助手逐渐进入日常开发，很多开发者会遇到一个问题：为什么 AI 每次修改代码时都需要重复说明项目结构、测试命令、代码规范和提交要求？

解决这个问题的一种简单方式，是在项目中增加专门给 AI 编程助手阅读的规则文件，例如 AGENTS.md 和 CLAUDE.md。

这些文件不是业务代码，也不是普通的 README，而是项目与 AI 助手之间的一份"协作协议"。

一、为什么需要 AI 项目规范文件？

AI 编程助手可以快速阅读和修改代码，但它并不了解项目背后的所有约束。

例如，一个项目可能有以下要求：

所有提交信息必须使用中文。
修改后必须运行类型检查、Lint 和构建。
不能提交 .env 文件。
API 修改必须同步更新前端类型。
数据库变更必须通过迁移文件完成。
修改检索逻辑后必须运行评测集。

如果这些规则只存在于团队成员的记忆中，那么每次和 AI 协作都需要重新解释。一旦遗漏，AI 可能会：

修改了不应该修改的文件。
忘记补充测试。
提交了敏感配置。
只修改后端，没有同步前端。
运行了错误的启动或构建命令。
使用不符合项目要求的提交信息。

AGENTS.md 或 CLAUDE.md 的作用，就是把这些隐含知识沉淀为项目中的明确规则。

二、AGENTS.md 是什么？

AGENTS.md 是一种面向 AI 编程 Agent 的项目协作说明文件，通常放在项目根目录，也可以放在某个子目录中。

它可以包含：

项目整体介绍
目录结构说明
安装、启动和测试命令
前后端开发规范
API 和数据结构约束
数据库迁移规范
安全和敏感文件规则
Commit 规范
修改完成后的验证流程

例如：

md 复制代码

# AGENTS.md

## 开发规范

- 所有 commit 信息使用中文。
- 修改 API 后必须同步更新前端调用方。
- 禁止提交 .env 和真实 API Key。

## 验证命令

```bash
npm run type-check
npm run lint
npm run build

复制代码

当 AI 助手在项目中工作时，它可以先读取这些规则，再开始分析和修改代码。

## 三、CLAUDE.md 是什么？

`CLAUDE.md` 是 Claude Code 约定使用的项目说明文件，作用与 `AGENTS.md` 非常接近。

它通常用于告诉 Claude Code：

- 当前项目应该如何运行。
- 哪些规则必须遵守。
- 修改哪些文件需要额外注意。
- 测试和提交应该如何执行。

示例：

```md
# Claude Code 项目规范

本项目使用 Vue 3 和 Express。

修改代码后必须执行：

```bash
npm run type-check
npm run lint
npm run build

禁止提交 .env 文件和真实密钥。

复制代码

从内容角度看，`CLAUDE.md` 和 `AGENTS.md` 可以非常相似；它们最主要的区别在于不同 AI 工具默认识别的文件名不同。

## 四、AGENTS.md 和 CLAUDE.md 的区别

| 文件 | 主要适用工具 | 作用 |
|---|---|---|
| `AGENTS.md` | Codex、OpenAI Agent 及兼容 Agent 工具 | 项目级 AI 编程规范 |
| `CLAUDE.md` | Claude Code | Claude Code 项目级规范 |
| `README.md` | 开发者和用户 | 项目介绍、安装和使用说明 |
| `docs/` 文档 | 开发者、维护者和 AI | 详细技术和业务文档 |

它们的区别主要是约定文件名和加载机制，而不是文档内容本身。

可以这样理解：

```text
README.md       → 项目怎么使用
技术文档        → 项目是怎么实现的
AGENTS.md       → Codex 等 AI 应该怎么修改项目
CLAUDE.md       → Claude Code 应该怎么修改项目

五、项目中应该写什么内容？

一份实用的 AI 协作规范不应该只是写"请保持代码整洁"，而应该尽量提供可以执行的规则。

1. 项目定位

说明项目解决什么问题、使用什么技术栈，以及主要业务流程。

md 复制代码

本项目是一个本地知识库问答系统，前端使用 Vue 3，后端使用 Express，模型使用 DeepSeek。

2. 目录职责

告诉 AI 不同目录分别负责什么。

md 复制代码

- client/：前端代码
- server/：后端代码
- knowledge/：知识库原始文档
- data/：运行时知识库数据
- docs/：技术文档

这样可以降低 AI 把业务代码写到错误目录的概率。

3. 常用命令

命令应该直接可复制执行：

md 复制代码

npm run dev
npm run type-check
npm run lint
npm run build

不要只写"运行测试"，而应该写清楚准确命令。

4. 修改规则

明确哪些修改必须同步进行：

md 复制代码

- 修改 API 返回结构时，必须更新前端类型。
- 修改数据库字段时，必须增加迁移文件。
- 修改 SSE 格式时，必须同步检查服务端和前端解析器。

5. 安全边界

这是非常重要的一部分：

md 复制代码

- 禁止提交 .env。
- 禁止在日志中打印 API Key。
- 禁止删除用户数据，除非得到明确授权。
- 不要覆盖用户未提交的修改。

6. 提交规范

如果团队要求中文提交，可以直接写在规则中：

md 复制代码

Commit 信息使用中文，描述实际完成的功能或修复内容。

六、规则文件应该放在哪里？

最常见的方式是在项目根目录放置一份：

text 复制代码

project/
├── AGENTS.md
├── README.md
├── package.json
├── client/
└── server/

如果某个子目录有特殊规则，也可以继续放置更具体的规则文件：

text 复制代码

project/
├── AGENTS.md
├── client/
│   └── AGENTS.md
└── server/
    └── AGENTS.md

例如根目录规定整个项目的通用规则，server/AGENTS.md 专门规定后端 API、数据库和测试规则。

规则可以按范围逐渐细化：

text 复制代码

根目录规则       → 整个项目通用
server 目录规则  → 后端专用
具体模块规则     → 某个模块专用

七、是否应该同时维护 AGENTS.md 和 CLAUDE.md？

如果团队只使用一种 AI 工具，维护一份文件即可。

如果同时使用 Codex 和 Claude Code，可以有两种方案。

方案一：两份完整文件

text 复制代码

AGENTS.md
CLAUDE.md

优点是每个工具都能直接读取完整规范。

缺点是两份内容可能逐渐不一致，后续维护成本较高。

方案二：一份主规范，另一份引用

推荐使用这种方式：

md 复制代码

# CLAUDE.md

本项目统一遵循根目录 `AGENTS.md` 中的开发、测试、安全和提交规范。
如需了解项目架构，请阅读 `docs/PROJECT_CONTEXT.md`。

此时：

AGENTS.md 作为主规范。
CLAUDE.md 作为 Claude Code 的入口说明。
详细技术内容放在 docs/PROJECT_CONTEXT.md。

这种结构可以避免重复维护同一套规则。

八、AGENTS.md 不应该写什么？

规则文件也不能无限膨胀。以下内容不适合全部放进 AGENTS.md：

大段业务需求说明。
完整 API 文档。
所有源代码的复制内容。
高频变化的临时任务。
真实密钥和服务器密码。
与项目无关的个人偏好。

更适合的拆分方式是：

text 复制代码

AGENTS.md                 → AI 协作规则和入口
README.md                 → 安装和基本使用
docs/PROJECT_CONTEXT.md   → 项目架构和技术细节
docs/api.md               → API 文档
docs/deployment.md        → 部署文档

AGENTS.md 只需要告诉 AI 在哪里找到更详细的信息，不需要把所有内容都重复写一遍。

九、实际项目中的推荐结构

以一个前后端项目为例：

text 复制代码

project/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── docs/
│   ├── PROJECT_CONTEXT.md
│   ├── api.md
│   └── deployment.md
├── client/
│   └── AGENTS.md
└── server/
    └── AGENTS.md

根目录 AGENTS.md 负责通用规则：

项目定位
全局命令
安全规范
测试和提交规则

前端目录规则负责：

组件规范
状态管理
API 调用方式
前端测试和构建

后端目录规则负责：

路由和服务分层
数据库迁移
错误处理
后端测试

十、以 local-ai-chat 为例

在 local-ai-chat 项目中，AGENTS.md 可以约束以下行为：

聊天服务使用 POST /api/chat 进行 SSE 流式输出。
前端必须通过 client/src/utils/sse.ts 处理 SSE 分片。
知识库检索逻辑位于 server/lib/search.ts。
修改分词、评分或分块后必须运行检索评测。
修改 API 后必须同步更新 client/src/api/。
.env 和真实 DeepSeek API Key 不得提交。
Commit 信息统一使用中文。

这些规则可以避免 AI 在后续工作中重复犯相同错误，也能让不同开发者和不同 AI 工具按照同一套项目约束工作。

十一、总结

AGENTS.md 和 CLAUDE.md 的价值，不在于它们的文件名本身，而在于把项目经验转化成 AI 能够持续遵守的规则。

推荐的实践是：

在项目根目录建立一份主要 AI 协作规范。
写清楚架构、命令、测试、安全和提交规则。
把详细技术说明放在 docs/ 中。
对前端和后端增加更具体的子目录规则。
多种 AI 工具共用一套主规范，避免内容分叉。
每次项目规则发生变化时，同步更新规范文件。

最终目标不是让 AI 记住所有代码，而是让 AI 在每次进入项目时都能快速理解：

text 复制代码

这个项目是什么？
代码应该怎么改？
改完需要验证什么？
哪些事情绝对不能做？

这正是 AI 项目规范文件最大的价值。