<!-- title: 给项目装记忆：CLAUDE.md 入门 -->

# 给项目装记忆：CLAUDE.md 入门

## 概述

Claude Code 每一次会话都从一个**全新的上下文窗口**开始——它不会记得你上次说过的项目约定、构建命令或代码风格。本教程教你用 `CLAUDE.md` 这个纯文本文件，给项目装上一份**持久记忆**，让 Claude 在每个会话开头自动读取，从而稳定遵循你的规范。适合零基础开发者、刚装好 Claude Code 还没跑过真实项目、以及希望减少重复纠正的同学。读完你将掌握：记忆的四个层级、`/init` 一键生成、手写有效指令的诀窍、`@import` 引入、`.claude/rules/` 路径限定，以及自动记忆（auto memory）。

## 前置条件

- 已安装 Claude Code（终端能跑 `claude --version`，建议 v2.1.59 以上以启用 auto memory）
- 有一个本地项目目录（任何语言均可，本文示例用 Python）
- 会基本的终端操作和编辑文本文件
- 对 Markdown 有最低限度的了解（会写标题和列表即可）

---

## 第一步：理解"为什么需要 CLAUDE.md"

先建立一个关键认知：**Claude Code 没有跨会话记忆**。

你今天告诉它"本项目用 4 空格缩进、提交前必须跑 `pytest`"，明天打开新会话，它又从零开始。于是你会发现自己反复输入同样的纠正：用 pnpm 不是 npm、API handler 放在 `src/api/handlers/`、不要碰 `legacy/` 目录……

`CLAUDE.md` 就是解决这个问题的官方机制。它是一个 Markdown 文件，Claude Code 在**每次会话开始时自动读取**，把里面的内容当作持久的上下文。你写一次，长期受益。

官方文档给出一个简单的判断标准——**当你满足以下任一情况，就该往 CLAUDE.md 加内容**：

1. Claude 第二次犯了同样的错误
2. Code review 抓住了"它本应知道的"项目常识
3. 你把上次的纠正又打了一遍
4. 一个新同事需要同样的背景知识才能高效工作

> 一句话原则：CLAUDE.md 装的是"每次会话 Claude 都该知道的事实"，不是临时任务清单。

## 第二步：认识记忆的四个层级

CLAUDE.md 不只是一个文件，而是一套**分层的记忆体系**。理解层级，才能把规则放到正确的位置。官方按加载顺序（从最宽到最窄）划分为：

| 层级 | 文件位置 | 用途 | 是否共享 |
|------|----------|------|----------|
| **托管策略**（Managed） | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br>Linux/WSL: `/etc/claude-code/CLAUDE.md` | 组织级规范（IT/DevOps 维护） | 全公司 |
| **用户级**（User） | `~/.claude/CLAUDE.md` | 你个人的、跨所有项目的偏好 | 仅自己 |
| **项目级**（Project） | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 团队共享的项目规范 | 通过版本控制共享给团队 |
| **本地级**（Local） | `./CLAUDE.local.md` | 你个人针对该项目的偏好（需加入 `.gitignore`） | 仅自己（当前项目） |

要点：

- 加载顺序是**从宽到窄**，越靠近你启动目录的文件**越晚加载**，因此更具体的项目指令会覆盖/补充更宽泛的用户指令。
- 同一层级内，`CLAUDE.local.md` 会排在 `CLAUDE.md` **之后**，保证你的个人注释是"Claude 最后读到的话"。
- 所有发现的文件是**拼接**进上下文，而不是相互覆盖。

零基础起步，你只需要关心两件事：**项目级 `./CLAUDE.md`**（团队共享）和 **`./CLAUDE.local.md`**（只属于你）。用户级 `~/.claude/CLAUDE.md` 可以放"我永远用中文回复"这类全局偏好。

## 第三步：用 `/init` 一键生成第一份 CLAUDE.md

最快的起步方式是让 Claude 自己分析代码库生成草稿。

**操作：**

```bash
cd 你的项目目录
claude
```

进入会话后输入：

```
/init
```

**预期结果：** Claude 会自动扫描你的代码库，生成一份初始 `CLAUDE.md`，内容通常包含：项目概述、构建/测试/lint 命令、它发现的项目约定、目录结构等。把它当作**起点**，再手动补充它发现不了的东西。

**进阶：交互式多阶段流程**

设置环境变量后，`/init` 会变成一个交互式向导：

```bash
CLAUDE_CODE_NEW_INIT=1 claude
# 会话内输入 /init
```

它会先问你"要设置哪些东西"（CLAUDE.md / skills / hooks），用子代理深入探索代码库，针对空白处追问，最后**提交一份可审查的方案**，你确认后才真正写文件——对零基础者更友好，不容易写坏。

**常见问题：**

- **已有 CLAUDE.md 怎么办？** `/init` **不会覆盖**，而是给出改进建议。
- **`/init` 生成的太啰嗦？** 这是正常的，它偏保守。手动删掉显然的东西，留下高价值的"项目专属事实"。

## 第四步：手写有效指令——三个核心原则

CLAUDE.md 是"上下文"而非"强制配置"。Claude 会尽力遵循，但**写得越具体、越简洁，遵循率越高**。记住三个原则：

### 原则一：具体而非模糊

❌ 差："格式化好代码"
✅ 好："使用 2 空格缩进"

❌ 差："测试你的改动"
✅ 好："提交前运行 `npm test`"

❌ 差："保持文件整洁"
✅ 好："API 处理器放在 `src/api/handlers/` 下"

### 原则二：简洁——目标 200 行以内

官方明确建议：**单个 CLAUDE.md 控制在 200 行以内**。越长，消耗的上下文越多，遵循率反而下降。

判断方法：如果某条规则只针对一部分代码，就别塞进主文件，用后面讲的 **路径限定规则**。

### 原则三：结构化

用 Markdown 标题和列表组织，而不是大段文字。Claude 扫描结构的方式和人类读者一样——分组的章节比密密麻麻的段落好读。

**一份好的项目级 CLAUDE.md 模板：**

```markdown
# 项目：支付网关后端

## 构建与测试
- 启动开发服务：`make dev`
- 运行测试：`pytest -q`（必须先起本地 Redis）
- 类型检查：`mypy src/`
- 提交前必须全绿

## 代码规范
- Python 3.11，类型注解必填
- 4 空格缩进，行宽 100
- 新增 API 必须有输入校验和统一错误格式

## 架构
- src/api/handlers/  放 HTTP 入口
- src/domain/        放业务逻辑（禁止直接 import HTTP 层）
- src/infra/         放数据库、缓存、第三方客户端
- legacy/ 目录不要改，正在下线

## 注意
- 永远不要 push 到 main
- 数据库迁移用 alembic，禁止手写 SQL 改表
```

## 第五步：用 `@import` 引入其他文件

CLAUDE.md 支持 `@路径` 语法导入外部文件，导入的内容会在启动时**展开并加载进上下文**。

```markdown
项目概览见 @README，npm 命令见 @package.json。

# 额外规范
- git 工作流见 @docs/git-instructions.md
```

要点：

- **相对路径**基于"包含 import 的那个文件"解析，不是工作目录。
- 导入可**递归**，最多 4 层。
- 想在文中**提到**一个路径而不导入，用反引号包起来：`` `@README` `` 是字面文本，`@README` 才会触发导入。
- 首次遇到外部导入，会弹**批准对话框**列出涉及的文件；拒绝则该导入保持禁用。

**配合 AGENTS.md：** Claude Code 只读 `CLAUDE.md`，不读 `AGENTS.md`。如果你的仓库已有 `AGENTS.md`（给其他 AI 工具用），创建一个 `CLAUDE.md` 导入它即可，两边共享同一份指令：

```markdown
@AGENTS.md

## Claude Code 专属
- 对 `src/billing/` 的改动请用 plan 模式。
```

Windows 不便建符号链接，用 `@AGENTS.md` 导入最省事。

## 第六步：理解加载顺序——目录会向上爬

这是最容易踩坑的点。Claude Code **从当前工作目录开始，沿目录树向上逐级查找** `CLAUDE.md` 和 `CLAUDE.local.md`。

假设你在 `foo/bar/` 启动，它会加载：

- `foo/bar/CLAUDE.md` 和 `foo/bar/CLAUDE.local.md`
- `foo/CLAUDE.md` 和 `foo/CLAUDE.local.md`
- …一直到根

加载顺序是**从文件系统根向下到你的工作目录**——离你启动位置越近的，越晚进入上下文（也最具体）。子目录里的 `CLAUDE.md` **不会在启动时加载**，而是当 Claude 读取该子目录里的文件时**按需加载**。

```text
flowchart TD
    A[claude 在 foo/bar/ 启动] --> B[向上逐级扫描]
    B --> C1[/CLAUDE.md]
    B --> C2[foo/CLAUDE.md]
    B --> C3[foo/bar/CLAUDE.md]
    C1 --> D1[1. 最早加载<br/>最宽泛]
    C2 --> D2[2. 中间加载]
    C3 --> D3[3. 最后加载<br/>最具体]
    D1 & D2 & D3 --> E[拼接进启动上下文]
    F[子目录 src/ 内的 CLAUDE.md] -.按需.-> G[读到该目录文件时才加载]
    E --> H[会话开始]
```

**技巧：** 用 HTML 注释 `<!-- 维护者备注 -->` 写只给人看的内容，Claude 不会把注释注入上下文，省 token。代码块里的注释则会保留。

## 第七步：用 `.claude/rules/` 做路径限定规则

项目变大后，所有规则堆进一个 CLAUDE.md 会让它超长。这时用 `.claude/rules/` 目录把指令拆成**主题文件**，并支持**按文件路径限定**——只在 Claude 处理匹配文件时才加载，省上下文、减噪音。

**目录结构：**

```
your-project/
├── .claude/
│   ├── CLAUDE.md          # 主指令
│   └── rules/
│       ├── code-style.md  # 代码风格
│       ├── testing.md     # 测试约定
│       └── security.md    # 安全要求
```

**无条件规则**（无 frontmatter）：和 `.claude/CLAUDE.md` 一样，每次会话加载。

**路径限定规则**（带 `paths` frontmatter）：只在 Claude 读取匹配文件时触发：

```markdown
---
paths:
  - "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 端点必须有输入校验
- 使用统一错误响应格式
- 必须包含 OpenAPI 文档注释
```

**glob 写法速查：**

| 模式 | 匹配 |
|------|------|
| `**/*.ts` | 任意目录下的 TypeScript 文件 |
| `src/**/*` | src/ 下所有文件 |
| `*.md` | 项目根的 Markdown |
| `src/**/*.{ts,tsx}` | src 下所有 ts 和 tsx（花括号扩展）|

**个人规则**：放 `~/.claude/rules/` 会对你机器上**每个项目**生效，且加载顺序在项目规则之前。

## 第八步：自动记忆（Auto Memory）——Claude 自己做笔记

除了你手写的 CLAUDE.md，Claude Code 还有一套**自动记忆**：它会在工作中自己记笔记——构建命令、调试心得、架构要点、你纠正过的风格偏好。它不会每次都记，只在判断"这对未来会话有用"时才存。

- 需要 **v2.1.59+**，用 `claude --version` 确认。
- 默认开启，可在 `/memory` 里切换，或设置 `"autoMemoryEnabled": false`。
- 存储位置：`~/.claude/projects/<项目>/memory/`，按 git 仓库划分，**同仓库的所有 worktree 共享**。
- 目录里有 `MEMORY.md`（索引）和若干主题文件（如 `debugging.md`、`api-conventions.md`）。
- 每次会话只加载 `MEMORY.md` 的**前 200 行或 25KB**（取先到者）；主题文件按需读取。

**手动让 Claude 记：** 直接说"记住：本项目 API 测试需要本地 Redis"，它会存进 auto memory。如果想存进 CLAUDE.md 而非 auto memory，明确说"把这个加到 CLAUDE.md"。

## 第九步：用 `/memory` 查看与编辑

`/memory` 命令是记忆的"控制台"，它能：

- 列出当前会话加载的**所有** CLAUDE.md、CLAUDE.local.md、rules 文件
- 切换 auto memory 开关
- 打开 auto memory 文件夹
- 选中任意文件直接在编辑器里打开

**排查"Claude 没遵守我的 CLAUDE.md"的标准动作：**

1. 跑 `/memory`，确认你的文件**真的在加载列表里**——不在列表里，Claude 就看不到它。
2. 检查文件位置是否在会被加载的层级。
3. 把指令改得更具体（"2 空格缩进"优于"格式化好一点"）。
4. 排查跨文件**冲突指令**——两个文件给出相反指导时，Claude 可能随机挑一个。
5. 如果某事必须在固定时机执行（如提交前），别写 CLAUDE.md，改用 **hook**（钩子，硬执行）。

> 重要区分：CLAUDE.md 是"行为引导"，**不是强制层**。要硬性阻止某个动作（不管 Claude 怎么想），用 PreToolUse hook。

---

## 实战案例：为 Python 项目配置完整记忆

下面用一个虚构的"支付网关后端"项目，把上述所有步骤串起来，产出一套可直接抄走的配置。

**目录结构：**

```
payment-gateway/
├── CLAUDE.md                  # 团队共享（提交到 git）
├── CLAUDE.local.md            # 你个人（gitignore）
├── .claude/
│   ├── CLAUDE.md              # 与根 CLAUDE.md 二选一
│   └── rules/
│       ├── api.md             # 限定 src/api/**
│       └── db.md              # 限定 src/infra/db/**
├── .gitignore
└── ...源码...
```

**1. 根 `CLAUDE.md`（精简、全员共享）：**

```markdown
# 支付网关后端（Python 3.11 / FastAPI）

## 常用命令
- 起服务：`make dev`
- 测试：`pytest -q`（需本地 Redis）
- 类型检查：`mypy src/`

## 红线
- 永不 push 到 main
- 改表走 alembic，禁手写 SQL DDL
- legacy/ 下线中，勿动
```

**2. `.claude/rules/api.md`（路径限定）：**

```markdown
---
paths:
  - "src/api/**/*.py"
---
# API 层规范
- 每个端点必须有 Pydantic 输入模型
- 错误统一用 app.errors.PaymentError 体系
- 返回结构：{ "code": int, "data": ..., "msg": str }
```

**3. `.claude/rules/db.md`（路径限定）：**

```markdown
---
paths:
  - "src/infra/db/**"
---
# 数据访问规范
- 仓库模式，禁止在 handler 直接写 SQL
- 查询必须走 src/infra/db/repositories/
- 涉及金额用 Decimal，禁 float
```

**4. `CLAUDE.local.md`（个人，加入 .gitignore）：**

```markdown
# 我的本地偏好
- 本地沙箱地址：http://localhost:8080
- 测试数据用 fixtures/local_seed.json
```

**5. `.gitignore` 追加：**

```
CLAUDE.local.md
```

**验证流程：**

```bash
cd payment-gateway
claude
# 会话内
/memory        # 确认 4 个文件都在加载列表
```

然后让 Claude 写一个新端点，观察它是否：用了 Pydantic 校验、统一错误格式、把 SQL 放进 repositories/、用了 Decimal。符合就说明记忆生效了。

```text
flowchart LR
    S[claude 启动] --> A[/init 生成草稿]
    A --> B[手写根 CLAUDE.md<br/>200 行内]
    B --> C[大规则拆 .claude/rules]
    C --> D[个人偏好放 .local.md]
    D --> E[/memory 验证加载]
    E --> F{Claude 遵守?}
    F -->|是| G[✅ 记忆生效]
    F -->|否| H[改具体/查冲突/转 hook]
    H --> E
    I[工作中] -->|自动| J[auto memory 自记笔记]
    J --> I
```

## 常见问题与解决方案

**Q1：`/init` 后 Claude 还是犯了 CLAUDE.md 里写过的错？**
A：先 `/memory` 确认文件在列表里；再把指令写具体；最后查跨文件冲突。CLAUDE.md 是"尽力遵循"而非"硬执行"。

**Q2：CLAUDE.md 太长了（超 200 行）怎么办？**
A：用路径限定规则 `.claude/rules/`，只让相关文件触发。注意 `@import` 只是组织手段，**不省上下文**——导入的文件照样在启动时加载。

**Q3：`/compact` 压缩上下文后，指令"丢了"？**
A：项目根的 `CLAUDE.md` 能在压缩后**从磁盘重新注入**；但子目录里的 CLAUDE.md 不会自动重注入，要等 Claude 再读该目录文件时才重新加载。关键规则放项目根。

**Q4：auto memory 存了什么我不知道？**
A：`/memory` → 选 auto memory 文件夹，全是纯 Markdown，可直接读、改、删。

**Q5：团队 monorepo 里别的团队的 CLAUDE.md 干扰我？**
A：用 `claudeMdExcludes` 设置按路径/glob 跳过（托管策略级除外）。

**Q6：怎么让"提交前自动跑测试"成为铁律？**
A：别写 CLAUDE.md，改写一个 hook（如 PreToolUse / Stop 钩子），它是脚本级的硬执行，不依赖 Claude 自觉。

## 延伸阅读

- **Claude Code 官方文档 — How Claude remembers your project**：`https://code.claude.com/docs/en/memory`（最权威，层级、import、rules、auto memory 全覆盖）
- **Claude Code 官方文档 — Commands**：`https://code.claude.com/docs/en/commands`（`/init`、`/memory`、`/compact` 等命令参考）
- **Best Practices — Memory Management**：社区整理的生产级 CLAUDE.md 经验（结构化与精简权衡）
- **CLAUDE.md Files and Memory Hierarchy（DeepWiki）**：图解加载顺序与优先级
- 进阶配套：学完本篇后，可继续学 **hook（硬执行护栏）**、**skill（按需加载的任务包）**、**`.claude/rules/` 高级 glob**，构成"记忆 + 强制 + 按需"三件套。

## 训练营适用性评估

- **适用类型**：Claude Code 入门营、AI 编程工具实战营、研发效能提升训练营。零基础友好，无需任何前置 Claude Code 知识。
- **教学时长**：讲授 + 动手约 **2～2.5 小时**。其中概念（层级、加载顺序）30 分钟，`/init` 动手 30 分钟，手写 + rules 实战 60 分钟，排查答疑 30 分钟。
- **学员产出**：结营时每人能为自己真实项目交付一套"根 CLAUDE.md + 2 个路径限定规则 + 1 个 local 偏好"的完整记忆配置，并通过 `/memory` 验证生效。
- **衔接课程**：建议作为"安装与首个项目"之后的第二节，紧接"hook 护栏"与"skill 按需加载"，形成由软到硬的记忆与执行体系。

## 参考来源

1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — Anthropic 官方权威文档，覆盖 CLAUDE.md 层级、import、rules、auto memory 全部细节
2. [Commands — Claude Code Docs](https://code.claude.com/docs/en/commands) — 官方命令参考，含 `/init`、`/memory`、`/compact` 用法
3. [CLAUDE.md Files and Memory Hierarchy — DeepWiki](https://deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide/4.1-claude.md-files-and-memory-hierarchy) — 图解记忆层级与加载优先级
4. [CLAUDE.md File: The Complete Guide With Examples & Templates — TensorFeed.ai](https://tensorfeed.ai/claude-md-guide) — 含可直接套用的模板与实战示例（2026 年更新）
5. [Claude Code Memory Explained: How It Really Works — Jose Parreo Garcia](https://joseparreogarcia.substack.com/p/claude-code-memory-explained) — 各层记忆交互机制的深度拆解

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)