<!-- title: 读懂Claude Code的三层记忆 -->

# 读懂 Claude Code 的三层记忆：建立正确的心智模型

## 概述

很多新手装好 Claude Code 后，第一反应是"它怎么好像没记住我上次说的话？"——这往往不是 bug，而是没建立正确的心智模型。本教程面向**第一次接触 Claude Code、已经完成安装与首次认证**的零基础开发者，目标是让你在写第一行有效指令之前，先搞懂一件事：**Claude Code 究竟是怎么"看懂"你的项目的**。我们将围绕"会话上下文、项目记忆（CLAUDE.md）、用户配置（settings.json）"三层结构，配合一个可复现的实战案例，帮你避开 90% 新手都会踩的"它为什么不记得""它为什么乱改文件""为什么越聊越慢"三类坑。

## 前置条件

- 已在终端成功运行过一次 `claude`（任一平台均可，桌面/CLI/IDE 插件）
- 有一个**非空的真实代码目录**（哪怕只是一个 hello-world 项目）能拿来练手
- 了解命令行的 `cd`、文本编辑器的基本用法
- 不需要任何 AI 或大模型理论知识

---

## 一、先打破一个错觉：Claude 默认没有跨会话记忆

理解 Claude Code 最关键的一句话来自官方文档：

> **Each Claude Code session begins with a fresh context window.**（每一次会话都从一个全新的上下文窗口开始。）

换句话说，你昨天和它聊了三小时的项目背景、技术选型、命名约定，今天重开 `claude` 时，它**一无所知**——除非你把这些信息固化下来。这不是缺陷，而是设计：每次会话干净启动，能保证行为可预测、避免历史污染。

那么知识如何跨会话延续？官方给出两条主线，业界把它总结为**三层记忆结构**：

| 层级 | 载体 | 寿命 | 谁来写 |
|------|------|------|--------|
| 第一层 会话上下文 | 当前对话 + 当前被读取的文件 | 单次会话 | 你 + Claude |
| 第二层 项目记忆 | `CLAUDE.md`、`SKILL.md` | 跨会话、跨会话自动加载 | 你 |
| 第三层 用户配置 | `~/.claude/settings.json` | 永久（跨所有项目） | 你 + 企业策略 |

先记住这张表，后面每一步都是在具体操作它。

---

## 二、第一层记忆：会话上下文（Context Window）

### 它是什么

会话上下文是 Claude "此刻能看到的一切"，容量上限是 **200,000 tokens**（约 20 万个 token，相当于十几万汉字或一个中型代码仓库的核心文件）。它是一个**滑动容器**：随着对话变长、文件被读取，容器被填满；满了之后，最早的内容会被"挤出"窗口，或触发自动压缩。

官方的上下文窗口模拟器透露了两个关键数字：

- `MAX = 200000` —— 窗口上限
- `STARTUP_END = 0.2` —— 启动阶段就占掉了约 **20%**（系统提示、CLAUDE.md、项目结构索引等）

也就是说，你一句还没说，窗口已经有 20% 被占用了。理解这一点，你就能解释很多"奇怪现象"。

### 怎么操作

在会话中输入斜杠命令：

```text
/clear      # 彻底清空当前会话，回到干净启动状态
/compact    # 把历史对话压缩成摘要，腾出空间继续聊
```

**预期结果**：执行 `/clear` 后，Claude 不再记得本轮之前的任何对话，但仍会重新读取 `CLAUDE.md`；执行 `/compact` 后，你会看到一段"压缩摘要"，对话历史变短，窗口利用率回落。

### 常见问题与解决

| 现象 | 原因 | 解决 |
|------|------|------|
| 聊久了 Claude 开始"忘事"、答非所问 | 窗口接近满（默认约 92% 触发 auto-compact） | 主动 `/compact`，或拆成新会话 |
| 让它读了一个超大文件后变慢/报错 | 单次文件读取吃掉大量 token | 改为只读片段，或先让它 `grep` 定位再读 |
| 切换到完全不相关的任务后表现混乱 | 旧上下文干扰 | `/clear` 后重新开场 |

> **新手心法**：把会话当成"一次专注的工作时段"，一个会话做一件事。任务切换 = `/clear`。

---

## 三、第二层记忆：项目记忆 CLAUDE.md（本教程的核心）

### 它是什么

`CLAUDE.md` 是放在项目里的一个普通 Markdown 文件，Claude Code **每次启动都会自动读取它**。它就是你写给 Claude 的"项目说明书"，让它在每个全新会话一开始就拥有项目背景、约定、禁忌。这是知识跨会话延续**最主要、最可控**的手段。

### 加载优先级（谁覆盖谁）

官方定义了清晰的层级，从全局到局部依次加载，**更局部的规则覆盖更全局的**：

1. **企业策略**（Enterprise policy，`/etc/claude-code` 等，管理员设定，最高优先级）
2. **用户记忆**（`~/.claude/CLAUDE.md`，跨所有项目）
3. **项目记忆**（项目根目录 `./CLAUDE.md`，进版本库共享给团队）
4. **本地记忆**（`./CLAUDE.local.md`，个人覆盖，建议加入 `.gitignore`）
5. **子目录记忆**（嵌套子目录里的 `CLAUDE.md`，进入对应目录时追加）

### 快速上手

在项目根目录执行：

```bash
cd your-project
claude
```

进入会话后输入：

```text
/init
```

**预期结果**：Claude 会自动扫描项目结构、读取关键文件，并为你**生成一份初版 `CLAUDE.md`**，内容通常包括项目概览、构建/测试命令、代码风格、目录约定。你可以直接采纳或编辑。

管理记忆的另一个入口是：

```text
/memory
```

它会用可视化菜单让你编辑各层级记忆文件，比手动找路径更省心。

### 用 `@` 引用：把长文档拆出去

当项目记忆变长，全部塞进根 `CLAUDE.md` 会拖慢启动（还记得那 20% 启动开销吗）。官方支持 `@路径` 递归引用：

```markdown
# CLAUDE.md
本项目是一个 Go 微服务网关。

详见：
@docs/architecture.md
@docs/coding-style.md
@.claude/conventions/testing.md
```

引用的内容**按需加载**，不会一次性占满启动窗口——这是渐进式披露的关键。

### 写一份"高信噪比"的 CLAUDE.md

新手最常犯的错是写成散文小说。记住：**CLAUDE.md 是指令清单，不是 README**。好用的写法是命令式、可执行的短句：

```markdown
# 项目：payment-gateway

## 构建
- 跑测试：`make test`
- 单个包：`go test ./pkg/xxx -run TestYyy`

## 约定
- 错误处理统一用 errors.Wrap，禁止裸 panic
- 新增 HTTP 接口必须先写表驱动测试
- 提交前跑 `golangci-lint run`，0 warning 才可提交

## 禁忌（IMPORTANT）
- 不要修改 pkg/legacy/* 目录，那是冻结的遗留代码
- 数据库迁移文件只增不改，绝不回写已发布的版本
```

几个要点：
- **用 `IMPORTANT` 标记硬约束**，Claude 对这个词更敏感
- **写"怎么做"而不是"为什么"**：`make test` 远胜于"我们重视测试"
- **明确边界与禁忌**：告诉它别动什么，比告诉它做什么更能防止事故
- 控制在 **150–300 行**以内，长内容用 `@` 拆出去

### 常见问题与解决

| 现象 | 原因 | 解决 |
|------|------|------|
| 改了 CLAUDE.md 但没生效 | 当前会话已缓存 | `/clear` 重新启动会话 |
| Claude 仍不遵守某条规则 | 规则太模糊或与全局冲突 | 改成命令式短句，加 `IMPORTANT` |
| 启动变慢 | 根 CLAUDE.md 过长 | 用 `@引用` 把长文档拆出去 |
| 团队成员各自规则打架 | 都写进了共享的根文件 | 个人偏好放 `CLAUDE.local.md` 并 gitignore |

---

## 四、第三层记忆：用户配置 settings.json

这一层解决"我所有项目都希望 Claude 这样做"的问题，载体是 `~/.claude/settings.json`。常见配置包括：默认权限（允许哪些命令免确认）、默认模型、环境变量、主题等。

它和 CLAUDE.md 的分工很清晰：

- **`settings.json`** → 偏好与权限开关（"允许跑 npm，不允许跑 rm"）
- **`CLAUDE.md`** → 项目知识与约定（"本项目用 pnpm，不是 npm"）

> 本层细节涉及权限模式，已有专题教程展开。新手阶段你只需知道：**跨项目的个人偏好放 settings.json，项目专属知识放 CLAUDE.md**。

---

## 五、被忽略的一层：工具（Tools）连接上下文与世界

心智模型最后一块拼图是"工具"。Claude 本身只会读字、写字；它能看你的代码、能跑命令，是因为 Claude Code 给它配了一批工具：`Read`（读文件）、`Edit`（改文件）、`Bash`（执行命令）、`Grep`（搜索）等。

理解工具能解释一个关键事实：**Claude 不会魔法般知道你的全部代码——它只看到它"主动读取"过的部分**。所以：

- 不要问"你看看我整个项目哪里有 bug"——它得先一个个读文件，非常耗 token。
- 更好的问法："用 grep 找出所有调用 `processPayment` 的地方，然后审查异常处理"——引导它高效用工具定位。

```text
flowchart TD
    A[启动 claude] --> B[加载系统提示<br/>占用 ~20% 窗口]
    B --> C[读取 CLAUDE.md 各层级<br/>+ settings.json]
    C --> D[进入交互<br/>窗口剩余 ~80%]
    D --> E{用户指令}
    E -->|读文件/跑命令| F[调用工具<br/>消耗窗口]
    F --> E
    E -->|窗口接近满| G[/compact 自动压缩]
    G --> E
    E -->|切换任务| H[/clear 干净重启]
    H --> C
```

---

## 实战案例：给一个真实项目配三层记忆

下面用一个最小可复现的 Node.js 项目演示完整闭环。

### 步骤 1：准备项目

```bash
mkdir demo-api && cd demo-api
npm init -y
npm install express
```

新建 `index.js`：

```javascript
const express = require('express');
const app = express();
app.get('/', (req, res) => res.json({ ok: true }));
app.listen(3000);
```

### 步骤 2：生成初版项目记忆

```bash
claude
```

进入会话后输入 `/init`。预期输出（节选）：

```markdown
# CLAUDE.md（Claude 自动生成，可编辑）

## 项目概览
demo-api 是一个基于 Express 的 Node.js 服务。

## 常用命令
- 安装依赖：`npm install`
- 启动：`node index.js`
- （如果配置了 test 脚本会列出测试命令）
```

### 步骤 3：把 CLAUDE.md 改成"高信噪比"指令

把自动生成的文件改写成下面这样（核心是命令式 + 禁忌）：

```markdown
# demo-api

## 命令
- 装依赖：`npm install`
- 启动开发：`node index.js`（监听 3000）

## 约定
- 所有路由处理必须 try/catch，错误统一走 `next(err)`
- 新增接口必须返回 JSON

## IMPORTANT
- 不要升级 express 主版本号
- 不要删除 app.listen，否则服务无法启动
```

保存后，**在会话里输入 `/clear`** 让新规则生效。

### 步骤 4：验证记忆是否真的被记住

输入一个新指令测试：

```text
帮我加一个 /health 接口，返回当前时间和进程 pid
```

**预期结果**：Claude 会生成一个符合"返回 JSON""有 try/catch"约定的接口，且**不会**去碰 express 版本号——因为这三层记忆在它动手前就加载进了上下文。

### 步骤 5：观察上下文消耗

在会话中输入 `/context`（或观察界面状态栏），你会看到当前窗口占用百分比。如果你让它连续读取多个大文件，能看到百分比攀升；执行 `/compact` 后回落。这正是第一层"会话上下文"的可视化。

### 步骤 6：固化跨项目偏好

假设你希望在**所有项目**里都默认允许 `npm`、`node` 命令免确认，编辑 `~/.claude/settings.json`：

```json
{
  "permissions": {
    "allow": ["Bash(npm install)", "Bash(npm test)", "Bash(node *)"]
  }
}
```

保存后新开会话即生效。这就是第三层"用户配置"。

至此，你已亲手搭建并验证了三层记忆：会话上下文（`/clear`/`/compact`）、项目记忆（`CLAUDE.md`）、用户配置（`settings.json`）。

---

## 心智模型总览图

```mermaid
flowchart LR
    subgraph 第三层["第三层：用户配置（永久·跨项目）"]
        S["~/.claude/settings.json<br/>权限 / 模型 / 偏好"]
    end
    subgraph 第二层["第二层：项目记忆（跨会话·进版本库）"]
        E["企业策略"] --> U["~/.claude/CLAUDE.md"] --> P["./CLAUDE.md"] --> L["./CLAUDE.local.md"]
        P -.引用.-> D["@docs/architecture.md<br/>按需加载"]
    end
    subgraph 第一层["第一层：会话上下文（单次会话·200K token）"]
        C["对话历史 + 被读取的文件<br/>/clear /compact 管理"]
    end
    S --> C
    P --> C
    C -->|调用工具<br/>Read/Bash/Grep| W["真实代码世界"]
```

---

## 新手避坑速查

1. **"它不记得我上次说的"** → 不是 bug，把要点写进 `CLAUDE.md`。
2. **"改了 CLAUDE.md 没生效"** → 当前会话要 `/clear`。
3. **"越聊越慢/越蠢"** → 上下文快满了，`/compact` 或换新会话。
4. **"它乱改/删文件"** → 在 CLAUDE.md 用 `IMPORTANT` 写明禁忌目录。
5. **"团队规则被个人改动污染"** → 个人偏好放 `CLAUDE.local.md` 并 gitignore。
6. **"启动变慢"** → 根 CLAUDE.md 过长，用 `@引用` 拆分。

---

## 延伸阅读

- **Claude Code 官方文档：How Claude remembers your project** —— 三层记忆的权威说明
- **Claude Code 官方文档：Explore the context window** —— 上下文窗口交互模拟器
- **Anthropic 工程博客：Claude Code Best Practices** —— 官方推荐的 CLAUDE.md 写法与工作流
- 社区实践中关于 `@引用` 渐进式披露、monorepo 多层 CLAUDE.md 的讨论

---

## 训练营适用性评估

- **适合类型**：面向零基础开发者的 Claude Code 入门营、企业 AI 编程提效第一课、转岗/新人 onboarding 训练营。
- **建议时长**：约 **1.5 小时**（讲授 40 分钟 + 动手实战 40 分钟 + 答疑 10 分钟）。
- **前置环节**：应排在"安装与首次认证"之后、首个功能开发之前，作为承上启下的心智模型课。
- **动手要求高**：本教程的实战案例可一人一组当场完成，建议要求学员**现场把示例 CLAUDE.md 写到自己的真实项目**并验证生效，效果远好于纯听讲。
- **后续衔接**：学完后自然过渡到"权限模式与项目配置""Skill 开发""自动化批处理"等专题。

---

## 参考来源

1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — 官方对 CLAUDE.md 与 auto memory 的权威说明，明确"每次会话干净启动、CLAUDE.md + 自动记忆两条跨会话主线"
2. [Explore the context window — Claude Code Docs](https://code.claude.com/docs/en/context-window) — 官方上下文窗口交互模拟器，给出 200K 上限与启动约占 20% 的关键数据
3. [Claude Code Memory: How Context and History Work (2026) — agensi.io](https://www.agensi.io/learn/claude-code-memory-context-guide) — 将记忆总结为"会话上下文 / 项目知识 / 用户偏好"三层结构的实践指南
4. [Claude Code & Agent Memory: Best Practices for 2026 — orchestrator.dev](https://orchestrator.dev/blog/2026-04-06--claude-code-agent-memory-2026/) — 分层记忆架构与高信噪比 CLAUDE.md 写法的深度实践
5. [The Complete Guide to CLAUDE.md — Medium](https://medium.com/@bijit211987/the-complete-guide-to-claude-md-memory-rules-loading-and-cross-tool-compression-97cc12ed037b) — 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)