# CLAUDE.md 文件里该写什么？

> CLAUDE.md 里放的是项目的测试和构建命令、和默认做法不一样的约定，以及已知的坑。Claude Code 每次会话开头都会读它，Anthropic 建议每个文件不超过 200 行。先用 `/init` 生成初稿，再把 Claude 读代码就能知道的行全部删掉。

Mindket 编辑部 · 发布于 2026-10-22 · 更新于 2026-11-03 · https://mindket.com/cn/blog/claude-md-file

## 要点

- 同样的错 Claude 犯了第二次，就补一行。要说“把这条加到 CLAUDE.md”，别说“记住这个”。
- 两份 CLAUDE.md 说法打架时，删掉其中一行。离你近的那份并不优先。
- 绝不能破例的规则，比如不许碰 `.env`，交给拒绝规则或钩子。

## 该写什么：Claude 从代码里看不出来的东西

先在项目里运行 `/init`。Claude 会读一遍代码库，写出第一版 CLAUDE.md。接下来的活儿多半是删行，[Anthropic 最佳实践页面](https://code.claude.com/docs/en/best-practices)也这么说。目录清单就可以先删，文件夹 Claude 自己会打开看。

每次会话开头，整个文件都会载入一个全新的上下文窗口，不管接下来做什么。你让 Claude 修 CSS，那条部署说明也照样占着上下文。

Anthropic 的[记忆文档](https://code.claude.com/docs/en/memory)给了两组例子。“使用 2 个空格缩进”行，“把代码格式整理好”不行。“提交前运行 `npm test`”行，“测试你的改动”不行。行的那一句，你都能查出 Claude 照没照做。

- 精确的测试、类型检查和 lint 命令，以及怎样只跑单个测试文件。
- 代码会误导人的地方：到处都是、但新代码不该照抄的旧写法，看着没人用、其实还在用的目录。
- 仓库里查不到的决定，比如团队选定了哪个错误处理函数，哪些改动要过迁移评审。

[![Boris Cherny（@bcherny）在 X 上回复一个关于文件大小的问题：他们提交进仓库的 CLAUDE.md 有 2.5k 个令牌，内容包括常用 bash 命令、代码风格约定、界面和文案设计准则、状态管理、日志、错误处理、功能开关和调试的做法，以及拉取请求模板](https://mindket.com/blog/shots/x-bcherny-claude-md-2-5k-tokens.webp?v=0ba566898210)](https://x.com/bcherny/status/2007212366094811401)

Boris Cherny 在 X 上，2026 年 1 月 2 日

> X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 3 日，时间为美国太平洋时间，没有收入链接预览。点击截图可到 X 上打开原帖。

## 一个简短的 CLAUDE.md 示例

这份是我们给一个小型 TypeScript 接口服务写的。标题照 Anthropic 最佳实践页面的分法，存成项目根目录下的 `CLAUDE.md` 就能用。

````markdown
# Commands
- Install: npm ci
- Run one test file: npx vitest run path/to/file.test.ts
- Typecheck: npx tsc --noEmit

# Conventions
- API handlers live in src/api/handlers/, one file per route
- Throw the error classes in src/lib/errors.ts, never raw strings
- src/legacy/ is still live. Do not copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
- Git workflow: @docs/git-workflow.md

````

## CLAUDE.md 放在哪里，怎样加载

比如你在 `foo/bar/` 里启动 Claude Code。这一级和上面每一级目录里的 `CLAUDE.md`、`CLAUDE.local.md` 都会加载。先读 `foo/CLAUDE.md`，再读 `foo/bar/CLAUDE.md`，离你最近的排在最后。`foo/bar/` 再往下的子目录，要等 Claude 读取或修改那里的文件，里面的 CLAUDE.md 才加载。

这些文件是首尾拼起来的，谁也不覆盖谁。项目文件排在用户文件后面（见[记忆文档](https://code.claude.com/docs/en/memory)），但两份说法不一样时，Claude 听哪一份都有可能。

示例最后一行 `@docs/git-workflow.md` 是一条导入。被导入的文件跟着导入它的文件一起加载，所以拆成几个文件并不省上下文。块级 HTML 注释不一样，比如 `<!-- maintainer notes -->`，送给 Claude 之前就被去掉了。给同事的备注写在里面，不占上下文。

`CLAUDE.local.md` 加进了 gitignore，只存在于你创建它的那个 git worktree。想让每个 worktree 都用上同一套个人指令，就放进主目录下的一个文件再导入，比如 `@~/.claude/my-project-instructions.md`。

| 范围 | 位置 | 谁能看到 |
| --- | --- | --- |
| 组织托管策略 | macOS：`/Library/Application Support/ClaudeCode/CLAUDE.md`。Linux 和 WSL：`/etc/claude-code/CLAUDE.md`。Windows：`C:\Program Files\ClaudeCode\CLAUDE.md` | 组织内的所有用户 |
| 用户 | `~/.claude/CLAUDE.md` | 只有你，所有项目 |
| 项目 | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 团队，通过版本控制共享 |
| 本地 | `./CLAUDE.local.md`，并加入 `.gitignore` | 只有你，仅限当前项目 |

[![Boris Cherny（@bcherny）在 X 上的回复，针对 Charles Frye 的一条帖子，后者觉得把 CLAUDE.md 沿目录树向上和向下全部加载是一个疯狂的策略：上级目录的 CLAUDE.md 在启动时自动载入上下文，下级目录的则是惰性加载，只有 Claude 读写它所在文件夹里的文件时才载入](https://mindket.com/blog/shots/x-bcherny-claude-md-loading.webp?v=1bd4732dfe44)](https://x.com/bcherny/status/2016339448863355206)

Boris Cherny 在 X 上的回复，2026 年 1 月 27 日

> 拍摄方式和日期同上。X 在回复处用“Show more”截断了后面的内容，想看全文请到 X 上打开。

## 用 /init、/doctor 和 /memory 加行、删行

项目里已经有 CLAUDE.md，`/init` 就不会覆盖它，只提改进建议。Cursor 和 Copilot 的规则它也会读：Cursor 的在 `.cursor/rules/` 或 `.cursorrules`，Copilot 的在 `.github/copilot-instructions.md`。

`/doctor` 会建议删掉 Claude 能从代码里推出来的东西，比如目录结构、依赖清单。容易踩的坑、背后的理由、和工具默认不同的约定，它会留着。它的 `prompt-audit` 模式要 Claude Code v2.1.283 或更高版本，会多标出三类问题：给旧模型写的指令，指向不存在的文件或命令的引用，互相矛盾的文件。它只出报告。你不让 Claude 应用修改，文件就一个字都不变。

手动改用 `/memory`。用户和项目两个范围的 CLAUDE.md、CLAUDE.local.md 它都会列出来，还不存在的也列，选哪个就在编辑器里打开哪个。在对话里说一句“把这条加到 CLAUDE.md”也行。[扩展功能总览](https://code.claude.com/docs/en/features-overview)的建议是，同一句纠正别打第二遍，直接这么加进去。

只说“记住这个”，内容进的是自动记忆。那是另一套存储，由 Claude 自己写，记你的偏好、你给过的纠正。每个仓库在 `~/.claude/projects/` 下有一个文件夹，同一仓库的所有 worktree 共用。每次会话只加载 MEMORY.md 索引的开头，主题文件 Claude 要用时再读。开关在 `/memory` 里。

> **Anthropic 说什么时候该加一行**
>
> Claude 第二次犯同样的错。代码评审发现了 Claude 本该知道的、关于这个代码库的事。你在聊天里输入了和上次会话一样的纠正或说明。新来的同事也需要同样的背景才能上手。
>
> Anthropic, 记忆文档里“何时该往 CLAUDE.md 里添加内容”那份清单，引文为译文, [Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory) (2026-11-03 查阅)

## 哪些内容不该写，以及改放到哪里

全大写的强调可以先删。现在的模型看到平实的写法就会照做，IMPORTANT 堆多了，反而容易[让 Claude 把规则用过头](https://code.claude.com/docs/en/best-practices)。文件超过推荐长度，Claude Code 启动时会警告。要到 4 MiB 以上，它才整个跳过，一个字都不加载。

只跟接口代码有关的规则，放进 `.claude/rules/`。在头信息里写一个 `paths` 过滤条件，只匹配 `src/api/` 下的 TypeScript 文件。Claude 读取或修改这些文件时，规则才加载。按需加载的文件，包括子目录里的 CLAUDE.md，在 200K 上下文窗口下每个最多读 40,000 个字符。超出的部分 Claude 收不到，只拿到开头。用 `wc -m` 数一下，就知道还剩多少。

很长的发布流程，适合做成[技能](https://mindket.com/cn/blog/what-are-agent-skills)，也就是 `.claude/skills/` 下一个带 SKILL.md 的文件夹。[每次会话，Claude Code 只加载技能的描述](https://code.claude.com/docs/en/skills)，任务用得上才读完整文件。

你定义的[子智能体](https://mindket.com/cn/blog/claude-code-subagents)启动时也带着 CLAUDE.md。文件越长，每次委派重复加载的就越多。内置的 Explore 和 Plan 智能体会[跳过它们](https://code.claude.com/docs/en/sub-agents)，自定义智能体设 `omitClaudeMd: true` 也能不加载。

CLAUDE.md 里写“不要读 .env”，Claude 多半会照做，但不保证次次照做。这份文件放的是准则，Claude 可能觉得某条不适用。设置里加一条 `Read(./.env)` 拒绝规则，任何权限模式下都管用。“不要动 migrations 文件夹”可以写成 `PreToolUse` 钩子，拦下 `migrations/` 下的所有修改。失手一次就会泄露密钥或损坏数据的规则，我们才搬出去。最佳实践页面也提醒别过头。“优先使用具名导出”例外很多，留在 CLAUDE.md 里就好。

**拿来对照 CLAUDE.md 大小的三个数**

- **2.5k** 个令牌：Claude Code 的创造者 Boris Cherny 说，他的团队提交进仓库的 CLAUDE.md 就这么大 (来源：[Boris Cherny 在 X 上的帖子](https://x.com/bcherny/status/2007212366094811401), 2026-11-03 查阅)
- **200** 行：Anthropic 建议的每个文件长度，因为文件越长，占的上下文越多，遵循程度越低 (来源：[Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory), 2026-11-03 查阅)
- **40,000** 个字符：在 200K 上下文窗口下，每个按需加载的文件的上限 (来源：[Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory), 2026-11-03 查阅)

**每一类指令该放到哪里**

| | CLAUDE.md | 按路径生效的规则 | 技能 | 钩子或拒绝规则 |
| --- | --- | --- | --- | --- |
| 放什么 | 命令、约定和容易踩的坑 | 只和代码库某一部分有关的规则 | 某类任务的一长串做法 | 绝不允许例外的规则 |
| 什么时候送到 Claude 面前 | 启动时，每次会话都有 | Claude 读取或修改匹配的文件时 | 描述每次会话都有，其余部分在任务需要时才读 | 在它监听的事件上，比如每次修改文件之前 |
| 做不相干的任务时也占上下文 | ✓ 是 | ✗ 否 | ◐ 部分 | ✗ 否 |
| 每次都会照做 | ✗ 否 | ✗ 否 | ✗ 否 | ✓ 是 |

来源：[Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory) (2026-11-03 查阅)；[Claude Code 文档：最佳实践](https://code.claude.com/docs/en/best-practices) (2026-11-03 查阅)；[Claude Code 文档：用技能扩展 Claude](https://code.claude.com/docs/en/skills) (2026-11-03 查阅)

> 这里的每个事实都来自下方来源列表里的页面，阅读日期为 2026 年 11 月 2 日和 3 日。本文是对官方文档的解读，不是实际测试，文件位置、命令和版本要求也会随 Claude Code 的发布而变化。

## 常见问题

### CLAUDE.md 和 AGENTS.md 是同一个文件吗？

不是，这是两个文件，AGENTS.md 在 Claude Code 那里只是备选。v2.1.277 及以后的版本，只有在工作目录及其上级目录里都找不到 CLAUDE.md 或 CLAUDE.local.md 时，才会改读 AGENTS.md。两个都想用，就在 CLAUDE.md 开头写一行 `@AGENTS.md`，Claude 会先读共用的那份，再读你专门写给 Claude 的内容。在 Windows 上，Anthropic 更推荐这种导入，而不是符号链接，因为 Git 可能把提交进仓库的符号链接检出成只有一行字的文本文件。

### Claude 为什么不照我的 CLAUDE.md 做？

先确认它加载了没有。运行 `/context`，看 Memory files 下面有没有它。子目录里的 CLAUDE.md 是按需加载的，加载前不会出现，加载后会多一行带路径的 Loaded。加载了还不管用，可能是写得太长、太含糊，或者跟另一个文件矛盾。CLAUDE.md 是排在系统提示后面、作为一条用户消息交给 Claude 的。[Anthropic 的排查步骤](https://code.claude.com/docs/en/memory)最后一步是把这一行写得更具体，就像前面缩进那组例子。

### CLAUDE.md 在 /compact 之后还在吗？

项目根目录的那个文件还在。执行 `/compact` 之后，Claude 会从磁盘重新读取它并再次注入，嵌套的文件和按路径生效的规则则在需要时重新加载。只在对话里说过的指令可能会丢，想让它一直有效，就写进文件。

### 在大型单体仓库里，怎样跳过别的团队写的 CLAUDE.md？

在 `.claude/settings.local.json` 里加一个 `claudeMdExcludes` 列表，写上路径或 glob 模式，这样排除设置只在你自己的电脑上生效。模式按绝对文件路径匹配。组织托管的 CLAUDE.md 不能被排除。

## 资料来源

- [Claude Code 文档：Claude 如何记住你的项目](https://code.claude.com/docs/en/memory) (2026-11-03 查阅)
- [Claude Code 文档：最佳实践](https://code.claude.com/docs/en/best-practices) (2026-11-03 查阅)
- [Claude Code 文档：扩展 Claude Code](https://code.claude.com/docs/en/features-overview) (2026-11-02 查阅)
- [Claude Code 文档：用技能扩展 Claude](https://code.claude.com/docs/en/skills) (2026-11-02 查阅)
- [Claude Code 文档：创建自定义子智能体](https://code.claude.com/docs/en/sub-agents) (2026-11-02 查阅)
- [Boris Cherny 在 X 上的帖子：Claude Code 团队提交进仓库的 CLAUDE.md 有 2.5k 个令牌](https://x.com/bcherny/status/2007212366094811401) (2026-11-03 查阅)
- [Boris Cherny 在 X 上的帖子：哪些 CLAUDE.md 在启动时加载，哪些稍后加载](https://x.com/bcherny/status/2016339448863355206) (2026-11-03 查阅)

[创建 Agent Skill](https://mindket.com/cn/blog/how-to-create-agent-skill)