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

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 规范
• 修改完成后的验证流程

例如：

# 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. 项目定位

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

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

2. 目录职责

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

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

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

3. 常用命令

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

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

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

4. 修改规则

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

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

5. 安全边界

这是非常重要的一部分：

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

6. 提交规范

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

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

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

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

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

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

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

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

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

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

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

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

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

方案一：两份完整文件

AGENTS.md
CLAUDE.md

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

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

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

推荐使用这种方式：

# CLAUDE.md

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

此时：

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

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

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

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

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

更适合的拆分方式是：

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

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

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

以一个前后端项目为例：

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 能够持续遵守的规则。

推荐的实践是：

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

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

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

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