用好 CoreCode

CLAUDE.md 怎么写

最后更新：2026 年 10 月 27 日

CLAUDE.md 是写给 Claude Code 的项目说明，每次会话开始时都会读一遍。写得好，Claude 少犯重复的错；写得长而乱，它每一轮都在浪费上下文。这一页按 Anthropic 的 官方说明 整理，加上它对花费的影响。

CLAUDE.md 是什么

一个纯文本的 Markdown 文件，写着 Claude 在这个项目里应该知道的事：怎么构建和测试、代码约定、目录结构、“总是要这样做”的规则。Claude Code 每次启动会话都会读它，把它当作上下文。

它不是强制配置。规则写得越具体、越简洁，Claude 越稳定地遵守；但要“无论如何都不许做”的事，比如不许改某个目录，应该用 PreToolUse hook 拦截。

另外 Claude Code 还有一套“自动记忆”：你纠正过它的事，它会自己记下来，存在 ~/.claude/projects/<项目>/memory/。CLAUDE.md 是你写的规则，自动记忆是它学到的经验，两者每次会话都会加载。

放在哪

启动时，Claude Code 读取当前目录和它所有上级目录里的 CLAUDE.md，内容按从上到下的顺序拼在一起，越靠近当前目录的越后读。子目录里的 CLAUDE.md 不在启动时读，而是等 Claude 读写那个子目录里的文件时才加载。

从哪开始

在项目里运行 /init。Claude 会分析代码库，生成一份包含构建命令、测试方法和项目约定的 CLAUDE.md；已经有的话，它会提出修改建议而不是覆盖。然后再补上 Claude 自己发现不了的东西。

写什么

把它当作“不写下来就得每次重复解释”的地方。出现下面这些情况，就该往里加一条：

• Claude 第二次犯同一个错；
• 代码评审发现了它本该知道的项目惯例；
• 你在对话里打了和上次一样的纠正；
• 新同事也需要知道同样的背景才能上手。

只写每次会话都该知道的事实。多步骤的操作流程写成 skill，需要时才加载；只对某一部分代码有效的规则，放进 .claude/rules。

怎么写才有效

写能检验的具体规则，不写笼统的要求：

• 短。每个 CLAUDE.md 控制在 200 行以内。越长越占上下文，遵守得也越差。
• 有结构。相关的规则放在同一个标题下，用列表，不写大段文字。
• 不自相矛盾。两条规则冲突时，Claude 可能随便挑一条。定期清理过时的内容；Claude Code v2.1.283 起可以运行 /doctor prompt-audit，让它找出过时、冲突或引用了不存在文件的条目。
• 给人看的备注用 HTML 注释。CLAUDE.md 里的 <!-- 备注 --> 在送进上下文前会被去掉，不占 token。

一个简短的示例：

# 项目说明

## 命令
- 安装依赖：pnpm install（不要用 npm）
- 运行测试：pnpm test，提交前必须通过
- 本地启动：pnpm dev，端口 3000

## 约定
- TypeScript 严格模式，不用 any
- API 处理函数放在 src/api/handlers/，每个文件一个路由
- 数据库变更只通过 prisma migrate，不手改表结构

## 回复
- 用中文回复，代码注释用英文

导入其他文件

用 @路径 把别的文件导入进来，比如 详见 @README 和 @docs/git-instructions.md。相对路径以 CLAUDE.md 所在位置为准，导入可以嵌套，最多四层。写在反引号里的 `@README` 不会被导入。

导入只是让文件更好组织，不会减少上下文开销：被导入的内容同样每次都会加载。第一次遇到导入项目目录以外的文件时，Claude Code 会弹窗请你确认。

用 .claude/rules 按范围拆分

项目大了，可以在 .claude/rules/ 下按主题拆成多个 .md 文件，比如 testing.md、api-design.md。没有 paths 的规则和 CLAUDE.md 一样在启动时加载；加上 paths 的只在 Claude 处理匹配的文件时才加载：

---
paths:
  - "src/api/**/*.ts"
---
# API 规则
- 所有接口都要做输入校验
- 错误统一用 ApiError 返回

CLAUDE.md 里某一段已经长成多步流程的，可以改写成 skill，用到时才加载，见 Skills 使用教程。

已经有 AGENTS.md 怎么办

Claude Code v2.1.277 起可以直接读 AGENTS.md：项目里没有 CLAUDE.md 时，它读 AGENTS.md；有 CLAUDE.md 时只读 CLAUDE.md。想让几个编程工具共用一份说明，在 CLAUDE.md 里写一行 @AGENTS.md 导入即可。

和花费、缓存的关系

• 每一轮都会发。CLAUDE.md、自动记忆和不带 paths 的规则，每一轮请求都随上下文发送。命中缓存时只按缓存读取计费，但内容越长，没命中时重写的代价越大。这是要它短的另一个原因。
• 中途修改不会马上生效。会话进行中改了 CLAUDE.md，这次会话看不到新内容，要等 /clear、/compact 或重启（见 Anthropic 的 Claude Code 缓存说明）。好处是改它不会让当前会话的缓存失效。

更多省钱做法见 省钱指南。

怎么确认它被读到了

• 在会话里运行 /context，看 Memory files 下面列出的文件。不在列表里的，Claude 就看不到。
• 运行 /memory 可以列出、打开和编辑各级 CLAUDE.md，也能开关自动记忆。

常见问题