---
title: 一份说明书喂两个 agent：AGENTS.md 和 CLAUDE.md
description: 「Claude Code 两个都读、内容会合并」是中文社区流传最广的说法，官方文档写的是相反的话。一个只有 AGENTS.md 的仓库会安静地不加载任何说明书——怎么验、怎么修、两份该怎么分工。
published: 2026-07-24
updated: 2026-07-24
keywords:
  - AGENTS.md
  - CLAUDE.md 区别
  - Claude Code 读不读 AGENTS.md
  - Codex AGENTS.md
  - 多个 AI 工具 共用规则
  - agent 说明书
---

# 一份说明书喂两个 agent：AGENTS.md 和 CLAUDE.md

> 我核了一遍官方文档，结论跟中文社区流传最广的那句话正好相反，而且这个错**不会报错**——它只是让你的说明书安静地没被加载。

## 传得最广的那句话是错的

搜「AGENTS.md CLAUDE.md 区别」，排在前面的中文文章基本都写着同一句：

> Claude Code 同时读取 CLAUDE.md 和 AGENTS.md，两者内容会合并。

Claude Code 官方文档的原文是：

> **Claude Code reads `CLAUDE.md`, not `AGENTS.md`.**

**读的是 CLAUDE.md，不读 AGENTS.md。** 一个字的余地都没留。

这个错之所以难发现，是因为它的表现不是报错，是**什么都没发生**：你写了一份很用心的 AGENTS.md，Claude Code 启动，一个字都没读到，然后照着它自己的默认习惯干活。看起来就像「它不听话」。

**我在写这几篇的仓库上就撞到了。** 这个项目只有 `AGENTS.md`，没有 `CLAUDE.md`——会话启动时它没有出现在加载列表里，我是后来手动读的文件。如果我没手动读，那份写了几百行的红线和判据，等于不存在。

---

## 怎么验：一条命令

```
/context
```

看 **Memory files** 那一栏。列在里面的才是真加载了的。没列出来的文件，Claude 看不见——不管它写得多好，放在多正确的目录。

排查「说明书不管用」的第一步永远是这个，不是改文案。

---

## 怎么修：两种，都一行

**一、在 CLAUDE.md 里导入**（推荐，跨平台）：

```markdown
@AGENTS.md

## Claude Code

`src/billing/` 下的改动一律先走 plan mode。
```

Claude 在会话开始时加载被导入的文件，然后接着读下面的内容。**Claude 专属的东西写在导入下面**，通用的留在 AGENTS.md 里，两边不用抄两遍。

**二、软链接**（不需要加 Claude 专属内容时）：

```bash
ln -s AGENTS.md CLAUDE.md
```

成功时没有任何输出。下一次会话跑 `/context` 确认 `CLAUDE.md` 出现在 Memory files 里。

**Windows 上建软链接要管理员权限或开发者模式**，所以在 Windows 上直接用第一种。

---

## 为什么会有两份文件

**AGENTS.md 是开放标准。** 2025 年 8 月由 OpenAI、Google、Cursor 等一起发布，现在挂在 Linux 基金会的 Agentic AI Foundation 下面，二十多个工具认它——Codex、Cursor、Aider、Copilot 等等。它的价值就是「一个名字，所有工具都认」。

**CLAUDE.md 是 Claude Code 的原生格式**，功能更全：`@path` 导入、`.claude/rules/` 目录、`paths:` frontmatter 做路径范围限定、`CLAUDE.local.md` 私有层、`claudeMdExcludes` 排除。这些在 AGENTS.md 里都没有对应物。

所以不是二选一，是**一个当共同底座，一个当 Claude 侧的扩展**。

---

## 两份怎么分工

一条线就够：**跟工具无关的进 AGENTS.md，只有 Claude Code 认的进 CLAUDE.md。**

| 进 AGENTS.md | 进 CLAUDE.md（导入之后的部分） |
|---|---|
| 项目是什么、红线、口径 | plan mode 用在哪些路径 |
| 构建和测试命令 | `.claude/rules/` 的组织方式 |
| 目录约定、命名约定 | 哪些 skill 该在什么时候调 |
| 踩过的坑和判据 | 子代理/worktree 的用法 |

**别把同一条规则抄两份。** 两处不一致的时候，Claude 会任意挑一条走，而且不报错——这跟 CLAUDE.md 内部规则打架是同一个失败模式。

---

## `/init` 会读别的工具的规则

跑 `/init` 生成 CLAUDE.md 的时候，它会顺带读走这些并把相关部分并进去：

- **默认**：Cursor 的 `.cursor/rules/` 和 `.cursorrules`，Copilot 的 `.github/copilot-instructions.md`
- **设了 `CLAUDE_CODE_NEW_INIT=1` 之后再加**：`AGENTS.md`、`.devin/rules/`、`.windsurf/rules/`（和 `.windsurfrules`）、`.clinerules`

从别的工具迁过来的仓库，这是最省事的起点——但**它是一次性的合并，不是持续同步**。之后 AGENTS.md 再改，CLAUDE.md 不会跟着变。想要持续同步，还是回到上面的 `@AGENTS.md` 导入。

---

## 一个容易忽略的副作用

`@AGENTS.md` 这种导入**不省 context**——被导入的文件在启动时全量加载，跟直接写在 CLAUDE.md 里占的 token 一样多。导入解决的是组织问题，不是体积问题。

所以那条 200 行的建议是对**加载进来的总量**说的。AGENTS.md 本身也得瘦。要真减体积，得用 `paths:` 限定范围的 rules，或者把多步流程搬进 skill——[CLAUDE.md 到底该写什么](/guides/claude-md)那篇讲了取舍判据。

---

## 参考

- [Claude Code 官方文档：AGENTS.md 一节](https://code.claude.com/docs/en/memory)
- [AGENTS.md 开放标准](https://agents.md/)
- [告别混乱，用 AGENTS.md 统一你的 AI 开发工具规则](https://zhuanlan.zhihu.com/p/1951785160124109343)
- [CLAUDE.md 到底该写什么](/guides/claude-md)