<!-- title: 记忆文件：让AI永久懂你的项目 -->

## 概述

本教程面向第一次接触 Claude Code 的开发者，聚焦一个最容易被忽略却最影响使用体验的核心机制——**项目记忆文件 CLAUDE.md**。学完你将掌握：用 `/init` 一键生成记忆、手写一份高质量的 CLAUDE.md、理解四级作用域与加载顺序、用 `@` 引用和 `.claude/rules/` 拆分模块、开启自动记忆并用 `/memory` 审计，以及写出"AI 真的会照做"的有效指令。适用人群：刚装好 Claude Code、想让它在每个项目里都"懂规矩"而不是每次重新解释的零基础用户。

## 前置条件

- 已安装 Claude Code（`claude --version` 能正常输出版本号；要使用自动记忆需 **v2.1.59 或更高**）。
- 终端里能进入一个代码项目目录（git 仓库最佳，非 git 目录也可）。
- 一台 macOS / Linux / Windows + WSL 机器，有基本的命令行操作能力。
- 无需任何编程语言基础——本教程以配置文件为核心，命令可直接复制运行。

---

## 第零步：先搞懂"为什么需要记忆文件"

每次启动 Claude Code，它都拿着一个**全新的上下文窗口**——也就是说，它对你昨天的对话、你的项目结构、你的代码风格一无所知。如果不做任何配置，你会发现自己一遍又一遍地重复同一句话："用 pnpm 不要用 npm""提交前先跑 `npm test`""API 处理函数放在 `src/api/handlers/`"。

Claude Code 用**两套互补的记忆系统**把知识跨会话保留下来：

| 维度 | CLAUDE.md 文件 | 自动记忆（Auto memory） |
| :--- | :--- | :--- |
| 谁来写 | 你（人） | Claude（AI）自己 |
| 内容 | 指令与规则 | 学习到的模式、偏好 |
| 作用范围 | 项目 / 用户 / 组织 | 单个仓库（同仓库的 worktree 共享） |
| 加载方式 | 每个会话**全文加载** | 每个会话加载 MEMORY.md 的前 200 行或 25KB |
| 典型用途 | 编码规范、构建命令、架构约定 | 调试心得、Claude 自己发现的偏好 |

一句话总结：**CLAUDE.md 是你写给 AI 的"项目说明书"，自动记忆是 AI 给自己记的"笔记本"**。本教程主要教你写好前者，顺带开启后者。

> ⚠️ 重要认知：CLAUDE.md 是被当作**上下文**注入的，而不是被强制执行的配置。Claude 会尽量遵守，但不会 100% 保证。要硬性拦截某个动作（比如禁止执行某条命令），应该用 PreToolUse 钩子，而不是只写在 CLAUDE.md 里。这一点决定了你"哪些规则放记忆文件、哪些规则放钩子"。

---

## 第一步：用 /init 一键生成项目记忆

最快的上手方式是让 Claude 帮你起草。进入项目根目录，启动 Claude Code，输入：

```
/init
```

**会发生什么**：Claude 会扫描你的代码库——读 `package.json`、构建脚本、测试目录、README、甚至已有的 `.cursorrules`、`.devin/rules/`、`.windsurfrules`、`AGENTS.md` 等其他工具的配置——然后自动生成一份包含**构建命令、测试方式、项目约定**的 `CLAUDE.md`。

**预期结果**：项目根目录出现一个 `CLAUDE.md` 文件，内容大致长这样：

```markdown
# 项目：my-app

## 构建
- 安装依赖：`pnpm install`
- 启动开发服务器：`pnpm dev`
- 构建：`pnpm build`

## 测试
- 运行测试：`pnpm test`
- 单测在 `tests/` 目录

## 代码风格
- 使用 TypeScript 严格模式
- 组件放在 src/components/
```

**关键细节**：
- 如果项目里**已经有** `CLAUDE.md`，`/init` 不会覆盖，而是**建议改进**。这很重要——你不用担心心血被冲掉。
- 想体验更强大的"多阶段交互式初始化"，设置环境变量再跑：

  ```bash
  CLAUDE_CODE_NEW_INIT=1 claude
  # 然后输入 /init
  ```

  开启后，`/init` 会先问你要不要同时建立 CLAUDE.md、skills、hooks，用一个**子代理**深入探索代码库，通过追问补全信息，最后给出一个**可审阅的方案**，你确认后才真正写文件。对新手极其友好。

**常见问题**：
- **`/init` 生成的文件很简陋？** 正常。它能发现的是客观信息（构建命令），而你需要手动补充"它发现不了的东西"——比如架构决策、命名约定、为什么这么设计。
- **生成后没生效？** 退出当前会话重开一次（或重启 Claude Code），记忆文件在**会话开始时**才加载。

---

## 第二步：手动打造第一份高质量 CLAUDE.md

`/init` 给你的是骨架，真正的价值在于你手写的内容。下面是一个可直接套用的模板，对应一个 Node.js + TypeScript 后端项目：

```markdown
# my-api 项目记忆

## 构建与运行
- 包管理器：pnpm（永远不要用 npm 或 yarn）
- 安装依赖：`pnpm install`
- 开发：`pnpm dev`（监听 3000 端口）
- 测试：`pnpm test`（提交前必须通过）

## 代码规范
- 使用 2 空格缩进
- 用双引号字符串
- 所有函数必须有显式返回类型

## 项目结构
- API 路由处理器：src/routes/
- 数据库模型：src/models/
- 业务逻辑：src/services/
- 类型定义：src/types/

## 关键约定
- 新增 API 必须写输入校验，用 zod
- 错误响应统一走 src/utils/errorHandler.ts
- 数据库迁移用 prisma migrate，不要手写 SQL 改表
```

**写好它的四条铁律**（官方文档反复强调）：

1. **体积**：单个 CLAUDE.md **控制在 200 行以内**。文件越长，消耗的上下文越多，**遵守率反而下降**。内容多就拆到 `.claude/rules/`（见第五步）。
2. **结构**：用 Markdown 标题 + 项目符号分组。Claude 读结构和人一样——有分区的比一大段好懂。
3. **具体到可验证**：
   - ❌ "格式化代码" → ✅ "用 2 空格缩进"
   - ❌ "测试你的改动" → ✅ "提交前运行 `pnpm test`"
   - ❌ "保持文件有序" → ✅ "API 处理器放在 `src/routes/`"
4. **一致性**：两条互相矛盾的规则，Claude 会随便挑一条。定期检查，删掉过时的指令。

**预期结果**：保存后，新开的会话里 Claude 一上来就知道用 pnpm、知道去哪找路由——你再也不用重复解释。

**常见问题**：
- **Claude 没遵守我的规则？** 先用 `/memory` 命令确认文件真的被加载了（见第六步）。若已加载还不遵守，多半是规则太模糊或与别处冲突——改具体一点。
- **规则必须执行、不能有例外怎么办？** 那就不是 CLAUDE.md 的事，改用钩子（hook）强制拦截。

---

## 第三步：理解四级作用域与加载顺序

这是新手最容易迷糊的地方。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` | 团队共享的项目说明 | 通过 Git 共享给团队 |
| **本地级**（Local） | `./CLAUDE.local.md` | 你在本项目的私有偏好，加入 `.gitignore` | 只你自己（当前项目） |

**加载的关键规则**：
- 内容是**拼接**进上下文的，不是后者覆盖前者——所以四份文件可以同时生效。
- 顺序是从文件系统根**向下**到你的工作目录：越靠近你启动位置的文件，**读得越晚**，影响力相对越靠后。
- 同一目录里，`CLAUDE.local.md` 会追加在 `CLAUDE.md` 之后——你的私人笔记是"最后被读到的"。

**实战建议**：
- 把"团队都要遵守的"放 `./CLAUDE.md`，提交进 Git。
- 把"只有我这样干"的（比如你的沙箱地址、本地测试数据）放 `./CLAUDE.local.md`，并加入 `.gitignore`。运行 `/init` 选 personal 选项会自动帮你加 gitignore。
- 把"所有项目通用"的（比如你个人偏好的代码风格）放 `~/.claude/CLAUDE.md`。

**常见问题**：
- **我在子目录启动 Claude，会读到上级的 CLAUDE.md 吗？** 会。Claude 会从当前目录**向上**逐级查找。在 `foo/bar/` 启动，会读到 `foo/bar/CLAUDE.md`、`foo/CLAUDE.md` 以及它们的 local 版本。
- **大型 monorepo 里别的团队的 CLAUDE.md 干扰我怎么办？** 用 `claudeMdExcludes` 设置按 glob 排除，写进 `.claude/settings.local.json`：

  ```json
  {
    "claudeMdExcludes": [
      "**/other-team/CLAUDE.md"
    ]
  }
  ```

---

## 第四步：用 @ 引用把外部文件拼进来

CLAUDE.md 支持用 `@路径` 语法**导入其他文件**，导入的内容会在启动时展开并一起进上下文。

```markdown
# my-app

See @README for project overview
and @package.json for available npm commands.

# Git 工作流
@docs/git-instructions.md
```

**要点**：
- 相对路径**相对于包含 import 的那个文件**解析，不是工作目录。
- 导入可以递归，但**最多 4 层**。
- 想在文中**提到**一个路径而不是导入它，用反引号包起来：`` `@README` `` 不会触发导入。
- 第一次遇到项目外的导入时，Claude Code 会弹审批对话框列出文件；你拒绝后该导入保持禁用，不再询问。
- **重要权衡**：拆成 `@` import 有助于组织，但**不能减少上下文占用**——导入的文件照样在启动时进上下文。真想省上下文，得用第五步的路径规则。

**跨 worktree 共享个人偏好**：如果你用多个 git worktree 操作同一仓库，`CLAUDE.local.md` 只存在于创建它的那个 worktree。想跨 worktree 共享，改用导入家目录文件：

```markdown
# 个人偏好
- @~/.claude/my-project-instructions.md
```

---

## 第五步：用 .claude/rules/ 把规则拆成模块、按文件类型加载

当项目变大、CLAUDE.md 超过 200 行，就该用 `.claude/rules/` 目录拆分了。它有两个杀手锏：**模块化**和**按路径加载**。

**目录结构**：

```
your-project/
├── .claude/
│   ├── CLAUDE.md            # 主记忆文件
│   └── rules/
│       ├── code-style.md    # 代码风格
│       ├── testing.md       # 测试约定
│       ├── security.md      # 安全要求
│       └── frontend/        # 可建子目录，递归发现
│           └── react.md
```

**无条件规则**（启动时和 `.claude/CLAUDE.md` 一起加载）：直接写 markdown 即可。

**按路径触发的条件规则**（只在 Claude 操作匹配文件时才加载，省上下文）：在文件头加 YAML frontmatter：

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

glob 模式速查：

| 模式 | 匹配 |
| :--- | :--- |
| `**/*.ts` | 任意目录下的 TypeScript 文件 |
| `src/**/*` | src/ 下所有文件 |
| `src/**/*.{ts,tsx}` | src/ 下的 ts 和 tsx（花括号展开） |
| `tests/**/*.test.ts` | 测试文件 |

**用户级规则**：放在 `~/.claude/rules/`，对所有项目生效，且**先于项目规则加载**（项目规则优先级更高）。

> 区分清楚：**rules**（规则）用于"总要在上下文里或按文件类型加载"的长期约定；**skills**（技能）用于"偶尔才用、按需触发"的工作流。别把一次性流程塞进 rules。

---

## 第六步：开启自动记忆，用 /memory 审计一切

自动记忆（Auto memory）让 Claude **自己给自己记笔记**——构建命令、调试心得、架构笔记、它发现的你的偏好。它默认开启，需要 **v2.1.59+**。

**存储位置**：每个项目一个独立目录 `~/.claude/projects/<hash>/memory/`，其中 `<hash>` 由 git 仓库派生，所以**同一仓库的所有 worktree 和子目录共享一份记忆**。

**目录结构**：

```
~/.claude/projects/<hash>/memory/
├── MEMORY.md          # 精简索引，每次会话加载前 200 行/25KB
├── debugging.md       # 调试心得（按需读取，不在启动加载）
└── api-conventions.md # API 约定
```

**工作机制**：
- 启动时只加载 `MEMORY.md` 的**前 200 行或 25KB**（取先到者）。所以 Claude 会把 MEMORY.md 保持精简，把细节挪到 topic 文件里——topic 文件**不**在启动加载，需要时再用文件工具现读。
- 当你在界面看到 "Writing memory" / "Recalled memory"，就是它在读写这个目录。

**怎么用**：
- 开关：会话里输入 `/memory`，用其中的开关切换；或在 settings 里设 `"autoMemoryEnabled": false`；环境变量 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` 也能关。
- **审计**：`/memory` 会列出当前会话加载的所有 CLAUDE.md、CLAUDE.local.md、rules 文件，还能开关自动记忆、打开自动记忆文件夹。选任意文件可在编辑器打开。
- **让它记**：直接说"记住我永远用 pnpm""记住 API 测试需要本地 Redis"，Claude 就会写进自动记忆。
- **写进 CLAUDE.md 而非自动记忆**：明确说"把这条加到 CLAUDE.md"，或自己用 `/memory` 编辑。

**自定义存储位置**：在 `settings.json` 里设：

```json
{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}
```

> 自动记忆是**本机本地**的，不会跨机器、不会进云端环境。它是纯 markdown，随时可读可改可删。

---

## 第七步：写给 AI 的有效指令（避坑清单）

把前面的原则凝练成一份"自检清单"，每次写规则前过一遍：

1. **每条都要具体到可验证**——能写"运行 `pnpm test`"就别写"记得测试"。
2. **控制体积**——单文件 < 200 行；膨胀就拆 `.claude/rules/`。
3. **善用标题与列表**——别堆大段散文。
4. **消除矛盾**——定期巡检，别让两条规则打架。
5. **分清三种机制**：
   - 必须在固定时机执行的（提交前、编辑后）→ **钩子**（强制）
   - 长期约定 → **CLAUDE.md / rules**（上下文引导）
   - 偶发工作流 → **skills**（按需加载）
6. **想确认为何不生效**：
   - `/memory` 看文件是否在加载列表里。
   - 确认文件位置对不对（项目级要放 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`）。
   - 指令改具体些。
   - 排查跨文件冲突。
   - 高级调试可用 `InstructionsLoaded` 钩子记录"哪些指令文件、何时、为何加载"。

---

## 实战案例：给一个 Express + TypeScript API 配齐记忆体系

假设你有一个目录 `my-api/`，下面用一个完整流程把它从"裸奔"变成"AI 全懂"。

**1. 初始化**（项目根目录）：

```bash
cd my-api
CLAUDE_CODE_NEW_INIT=1 claude
# 输入 /init，选择建立 CLAUDE.md，按提示确认方案
```

**2. 编辑生成的 `./CLAUDE.md`**，替换为精炼版（保持 < 50 行）：

```markdown
# my-api

## 运行
- 依赖：`pnpm install`
- 开发：`pnpm dev`（端口 3000）
- 测试：`pnpm test`（提交前必跑）

## 约定
- 包管理器只用 pnpm
- 新增 API 必须用 zod 校验输入
- 错误统一走 src/utils/errorHandler.ts
```

**3. 拆分按文件类型生效的规则**，建 `.claude/rules/testing.md`：

```markdown
---
paths:
  - "tests/**/*.ts"
---
# 测试规则
- 每个公开函数都要有对应单测
- 测试文件与源文件同名加 .spec，如 user.ts → user.spec.ts
- 用 vitest，不要引 jest
```

**4. 加个人私有偏好**，建 `./CLAUDE.local.md`（加进 `.gitignore`）：

```markdown
# 本地偏好
- 我的本地数据库：postgresql://localhost:5432/myapi_dev
- 调试时倾向多打日志
```

**5. 验证加载**，新开会话输入 `/memory`，应看到 `CLAUDE.md`、`CLAUDE.local.md`、`rules/testing.md` 全部列出。

**6. 让自动记忆沉淀**，工作中直接对 Claude 说：

> "记住：测试数据库迁移前要先把 docker compose up 起来。"

它会写进 `~/.claude/projects/<hash>/memory/`，下次自动召回。

**效果**：从这一刻起，无论你隔多久、开多少个新会话，Claude 都默认知道用 pnpm、API 要校验、测试用 vitest、迁移前要先起 docker——而你**一句都不用再解释**。

---

## 整体工作流：记忆体系全景图

```text
flowchart TD
    A[新会话启动·空上下文窗口] --> B{扫描记忆}
    B --> C[托管策略 CLAUDE.md<br/>组织级]
    B --> D[用户级 ~/.claude/CLAUDE.md<br/>+ ~/.claude/rules/]
    B --> E[项目级 ./CLAUDE.md<br/>./.claude/CLAUDE.md + .claude/rules/]
    B --> F[本地级 ./CLAUDE.local.md]
    B --> G[自动记忆<br/>MEMORY.md 前200行/25KB]
    C --> H[逐级拼接注入上下文]
    D --> H
    E --> H
    F --> H
    G --> H
    H --> I[进入对话]
    I --> J{Claude 工作中}
    J -->|读到 src/api/*.ts| K[触发路径规则<br/>.claude/rules/*.md]
    J -->|你纠正/补充| L[Claude 自己记笔记<br/>写 auto memory]
    K --> J
    L --> G
    I --> M[/memory 命令<br/>审计·编辑·开关]
    M --> B
```

---

## 延伸阅读

- **Claude Code 官方记忆文档**：`code.claude.com/docs/en/memory`（本教程主要依据，权威性最高）
- **Skills 文档**：当你想把一次性流程做成可复用技能时深入
- **Hooks 指南**：当你需要"硬性强制"某条规则、而非靠上下文引导时
- **Debug your configuration**：当记忆文件死活不生效时的官方排障页
- **Subagent memory**：让子代理维护各自的自动记忆

进阶方向：把记忆体系与 skills、hooks 三者配合——记忆负责"长期约定"、skills 负责"按需工作流"、hooks 负责"强制拦截"，三者各司其职，就是一套成熟的 AI 协作工程化方案。

---

## 训练营适用性评估

- **适用训练营类型**：Claude Code / AI 辅助开发入门营、企业研发提效训练营、团队 AI 工程化落地营。本主题是所有后续内容（skills、hooks、子代理）的地基，**必须放在课程最前段**。
- **教学时长**：建议 **1.5～2 小时**。其中概念讲解 20 分钟、`/init` 与手写 CLAUDE.md 演示 30 分钟、作用域与 rules 实操 40 分钟、自动记忆与排障 20 分钟、综合实战 20 分钟。
- **学员产出**：每个学员为自己的真实项目配齐一套记忆文件，并通过 `/memory` 验证加载成功，作为结业检查点。
- **难度系数**：★☆☆☆☆（零基础友好，无需编程），但"写有效指令"这条需要反复练习，可设置 3～5 个"把模糊规则改具体"的小练习巩固。

---

## 参考来源

1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — Anthropic 官方记忆系统权威文档，涵盖 CLAUDE.md、自动记忆、rules、`/init`、`/memory` 全部机制（本文主要依据）
2. [The Complete Guide to CLAUDE.md — TensorFeed.ai](https://tensorfeed.ai/claude-md-guide) — 含示例与模板的 CLAUDE.md 完整指南，补充了实战写法与模板
3. [Claude Code Instructions and Memory: The Complete Setup — Alex Rusin's Blog](https://blog.alexrusin.com/claude-code-instructions-memory-setup-guide/) — 多文件规则系统与 `/memory` 的完整配置实战博客
4. [What Does /init Do in Claude Code? — HowDoIUseAI](https://www.howdoiuseai.com/blog/2026-04-16-what-does-init-do-in-claude-code-claudemd-setup) — 详解 `/init` 如何扫描项目并生成 CLAUDE.md
5. [The CLAUDE.md Memory System Tutorial — SFEIR Institute](https://institute.sfeir.com/en/claude-code/claude-code-memory-system-claude-md/tutorial/) — 结构化的 CLAUDE.md 记忆系统教学，含分层规则与最佳实践

> [!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)