CLAUDE.md 怎么写？Claude Code 项目记忆配置指南（附 CLAUDE.md 模板）

CLAUDE.md 怎么写，直接决定了 Claude Code 在你的项目里是"熟练的老同事"还是"每次都要重新交代的新人"。CLAUDE.md 是一个放在项目里的 Markdown 文件，Claude Code 每次启动会话都会自动读取它，里面写着构建命令、代码规范和项目约定。

这篇文章讲清 CLAUDE.md 放在哪里、怎么加载，给出一份可以直接复制的 CLAUDE.md 模板，再介绍让 Claude 更稳定遵守规则的写法，以及 .claude/rules、@ 导入和自动记忆这些进阶用法。还没装好 Claude Code 的话，先看《Claude Code 教程：2026 Claude Code 安装与使用指南》。

---

CLAUDE.md 是什么，为什么要写

每个 Claude Code 会话都从一个空白的上下文开始，它不会记得你上次交代过"这个项目用 pnpm，不用 npm"。CLAUDE.md 就是用来写下这些"否则每次都要重复说一遍"的内容。

官方建议在这些时候往 CLAUDE.md 里加内容：

• Claude 第二次犯同一个错误；
• 代码审查发现了 Claude 本该知道的项目约定；
• 你在对话里输入了和上次一样的纠正或说明；
• 新同事入职时也需要知道的背景信息。

需要注意，Claude 把 CLAUDE.md 当作上下文而不是强制配置。写得越具体、越简洁，Claude 遵守得越稳定。真正必须拦截的操作（比如禁止删除某个目录），应该用 Hook 或权限规则来保证。

---

CLAUDE.md 放在哪里：4 种作用范围

范围	位置	用途	共享对象
组织策略	macOS：/Library/Application Support/ClaudeCode/CLAUDE.md；Linux：/etc/claude-code/CLAUDE.md；Windows：C:\Program Files\ClaudeCode\CLAUDE.md	公司统一的编码和安全规范	组织内所有人
用户级	~/.claude/CLAUDE.md	个人在所有项目里的偏好	只有你
项目级	./CLAUDE.md 或 ./.claude/CLAUDE.md	项目架构、编码规范、常用流程	通过 Git 共享给团队
本地级	./CLAUDE.local.md	个人在本项目的偏好，加入 .gitignore	只有你

CLAUDE.md 的加载顺序

Claude Code 会加载当前目录以及所有上级目录里的 CLAUDE.md 和 CLAUDE.local.md。这些文件是拼接在一起的，不会互相覆盖：越靠近当前目录的文件越晚被读到，同一目录里 CLAUDE.local.md 排在 CLAUDE.md 之后。子目录里的 CLAUDE.md 不会在启动时加载，Claude 读写该子目录的文件时才会加载。

想确认哪些文件生效了，在会话中运行 /context all，查看 Memory files 列表；用 /memory 可以直接打开和编辑这些文件。

---

用 /init 快速生成 CLAUDE.md

在项目里第一次启动 Claude Code 时，输入：

/init

Claude 会分析代码库，生成一份包含构建命令、测试方法和项目约定的 CLAUDE.md。如果文件已经存在，/init 会提出改进建议而不是直接覆盖。生成的只是初稿，接下来要补上 Claude 自己发现不了的内容：团队约定、踩过的坑、不能碰的目录。

---

CLAUDE.md 模板（可直接复制）

下面是一份通用的项目 CLAUDE.md 模板，按需删减：

# 项目说明

SupaStore 控制台前端：React 19 + TypeScript，包管理器用 bun。

## 常用命令

- 安装依赖：`bun install`
- 本地开发：`bun run dev`
- 类型检查：`bun run typecheck`（每次改完 TS 代码都要跑）
- 单元测试：`bun run test`

## 目录结构

- `src/features/`：按业务功能划分的页面和组件
- `src/components/ui/`：基础 UI 组件，新增前先查这里有没有
- `src/i18n/locales/`：多语言文案，键名用英文原文

## 编码规范

- 使用 2 空格缩进，禁止两层以上嵌套三元表达式
- 用户可见文案必须通过 `t('English key')` 输出
- 新组件优先复用 `src/components/` 中已有的封装

## 工作流程

- 分支命名：`feat/xxx`、`fix/xxx`
- 提交前必须通过类型检查和 lint
- 不要修改 `src/generated/` 下的自动生成文件

## 已知问题

- 本地开发需要先启动后端，否则登录接口返回 502

这份模板的每一行都满足一个标准：删掉它，Claude 就可能犯一个具体的错误。达不到这个标准的内容，就不用写进 CLAUDE.md。

---

CLAUDE.md 写法最佳实践

写可以验证的具体指令

官方文档给出的对比很直观：

模糊写法	具体写法
代码格式要规范	使用 2 空格缩进
改完要测试	提交前运行 npm test
文件要组织好	API 处理函数放在 src/api/handlers/

每个 CLAUDE.md 控制在 200 行以内

CLAUDE.md 每次会话都会完整加载，文件越长，占用的上下文越多，Claude 的遵守程度也会下降。官方建议每个文件控制在 200 行以内。这也是省 Token 的关键一步，CLAUDE.md 的每一行都会随每次请求发送，原理见《Claude Code Token 消耗太快？10 个 Claude Code 省 Token 技巧》。

用标题和列表组织内容

按"命令、结构、规范、流程"分组，用 Markdown 标题和列表，比大段文字更容易被准确遵守。

定期清理冲突和过期内容

两条规则互相矛盾时（比如根目录要求单引号、子目录要求双引号），Claude 可能随机选择其中一条。可以运行 /doctor prompt-audit，让 Claude 检查记忆文件里过期、冲突或引用了不存在文件的内容，它会给出修改建议，你确认后才会改动。

给维护者的备注用 HTML 注释

<!-- 这条规则来自 2026-10 的线上事故 --> 这类块级 HTML 注释在注入上下文前会被去掉，既能给同事留说明，又不消耗 Token。

---

CLAUDE.md 进阶用法

用 .claude/rules/ 拆分规则

项目大了以后，可以把规则拆到 .claude/rules/ 目录，每个文件一个主题：

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── security.md

在规则文件开头加上 paths，它就只在 Claude 处理匹配的文件时加载：

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有接口必须做参数校验
- 错误响应统一使用 { code, message } 格式

只跟部分代码相关的规则放进路径规则，能让主 CLAUDE.md 保持精简。多步骤的操作流程（比如发版、数据库迁移）更适合写成 Skill，用到时才加载，写法见《Claude Code Skills 怎么用？SKILL.md 编写教程》。

用 @ 导入其他文件

CLAUDE.md 可以用 @路径 导入其他文件，例如：

项目概览见 @README.md，可用脚本见 @package.json。
- Git 工作流 @docs/git-instructions.md

导入最多支持嵌套 4 层。要注意，导入只是让文件更好组织，不会减少上下文占用，被导入的文件会和 CLAUDE.md 一起加载。

兼容 AGENTS.md

如果仓库已经为其他 AI 编程工具写了 AGENTS.md，而项目里没有 CLAUDE.md，新版 Claude Code 会直接读取 AGENTS.md。两者都有时，默认只读 CLAUDE.md；想让两个工具共用一份说明，在 CLAUDE.md 里写一行 @AGENTS.md 导入即可。

自动记忆：让 Claude 自己做笔记

除了你写的 CLAUDE.md，Claude Code 还有自动记忆：它会根据你的纠正和偏好，在 ~/.claude/projects/<项目>/memory/ 下记笔记，每次会话加载 MEMORY.md 的前 200 行或前 25KB。在 /memory 中可以开关这个功能。团队约定写进 CLAUDE.md，个人习惯交给自动记忆，两者配合效果最好。

---

CLAUDE.md 与 Claude Code 成本

CLAUDE.md 写得好，Claude 少走弯路、少读无关文件，Token 消耗自然下降；写得太长，则每次请求都要多付一段固定成本。通过 API 或中转站使用 Claude Code 时，这部分内容通常会命中 Prompt 缓存，按缓存价计费，具体价格见《Claude API 价格是多少？2026 Claude API 收费标准与省钱指南》；缓存计费是否到位，是挑选中转站时要验证的一项，见《API中转站是什么？AI中转站选型避坑指南》。

---

常见问题 (FAQ)

Q: CLAUDE.md 应该放在哪里？

答： 团队共享的项目说明放在项目根目录的 CLAUDE.md 或 .claude/CLAUDE.md，个人在所有项目通用的偏好放在 ~/.claude/CLAUDE.md，只属于自己的本项目设置放在 CLAUDE.local.md 并加入 .gitignore。

Q: CLAUDE.md 多长合适？

答： 官方建议每个 CLAUDE.md 文件控制在 200 行以内，只写 Claude 每次会话都需要的事实和规则，只跟部分目录相关的内容拆到 .claude/rules 的路径规则里。

Q: 怎么确认 CLAUDE.md 已经生效？

答： 在 Claude Code 会话中运行 /context all，在 Memory files 列表里能看到已加载的文件；运行 /memory 可以直接打开和编辑它们。

Q: CLAUDE.md 和 AGENTS.md 有什么区别？

答： 两者都是给 AI 编程工具的项目说明，新版 Claude Code 在没有 CLAUDE.md 时会直接读取 AGENTS.md，两个文件都存在时默认只读 CLAUDE.md，可以在 CLAUDE.md 中用 @AGENTS.md 导入来共用一份内容。

Q: 为什么 Claude 没有遵守 CLAUDE.md 里的规则？

答： 常见原因是指令太模糊、文件太长或规则互相冲突；把规则改成可验证的具体指令，控制在 200 行以内，并用 /doctor prompt-audit 检查冲突，必须强制执行的操作改用 Hook 或权限规则。