×−+
Memory 记忆第 2 课 · Claude Code 教程
第 2 课 · MEMORY

Memory：
让 Claude 记住你的项目

每段新对话，Claude 都从零开始。"装依赖用 pnpm""测试前先起 Redis"这些话，你不想每次都重说一遍。写进记忆，它每次开工前都会先读。

约 45 分钟 11 节 · 7 个动手练习 章末测验 改编自 luongnv89/claude-howto（MIT）
+
点一下笔记试试
入门先用起来 原理弄懂为什么 实战动手练 深入进阶与避坑

时间紧就先看"入门"和"实战"；"原理"讲清楚文件怎么加载，决定你的规则能不能真正生效。

01入门

为什么需要记忆？

把 Claude 想成一位能力很强、刚来你们团队的新同事。麻烦的是，他每天早上都会失忆。

每段对话开始时，Claude 的上下文都是空的：昨天聊过什么、你纠正过它什么，它都不记得。同一个请求，有没有记忆，结果差别很大：

两套记忆，分工不同

CLAUDE.md自动记忆
谁来写你Claude 自己
写什么指令和规则它从你的纠正和偏好里学到的东西
范围项目、个人或整个组织每个代码仓库一份
什么时候读每段对话开始时每段对话开始时（只读前 200 行或 25KB）
适合代码规范、常用命令、项目架构你的偏好、你纠正过的事、从代码里看不出来的背景
记忆是"提醒"，不是"强制"

两套记忆对 Claude 来说都是上下文：它会读、会努力遵守，但不保证百分之百照做。规则写得越具体、越简短，它越听话。必须每次都执行的事（比如提交前一定跑 lint），要交给 Hook（第 6 课）。

02入门

写出第一个 CLAUDE.md

不用从空白文件开始。一条 /init，Claude 会先读一遍项目，替你起个草稿。

在项目目录里启动 Claude Code，输入 /init。Claude 会分析代码库，生成一份包含构建命令、测试方法、项目约定的 CLAUDE.md。如果已经有 CLAUDE.md，它不会覆盖，而是给出改进建议。下面是草稿补完之后的样子，最后"注意"那一节是你自己加的：

CLAUDE.md — my-app

草稿只是起点。接下来补上Claude 从代码里看不出来的东西：团队约定、踩过的坑、为什么这么做。它能自己从代码里读出来的内容（比如目录结构、依赖列表），反而可以删掉。

怎么确认它真的被读到了？

在对话里输入 /context，看 Memory files 下面的列表。列表里没有的文件，Claude 就看不到。

想要更细的引导

启动前设置环境变量 CLAUDE_CODE_NEW_INIT=1，/init 会变成多步引导：先问你要生成哪些东西（CLAUDE.md、skill、hook），再派子代理探索代码库、追问细节，最后给你一份方案确认后才写文件。

03入门

该写什么，不该写什么

把 CLAUDE.md 当成"不想再解释第二遍"的清单。

什么时候该往里加一条

  • Claude 第二次犯同一个错误
  • 代码审查时发现，有件事 Claude 本该知道
  • 你在对话里打了一句纠正，而这句话上次也打过
  • 新同事入职也需要知道这件事

写法：具体到能检验

✗ 太笼统✓ 具体
代码格式要规范用 2 个空格缩进
改完要测试提交前运行 npm test
文件放整齐接口处理函数放在 src/api/handlers/
  • 短：每个 CLAUDE.md 控制在 200 行以内。越长越占上下文，Claude 也越不容易全部遵守。
  • 有结构：用 Markdown 标题和列表分组，Claude 和人一样，扫读结构清楚的文档更快。
  • 不矛盾：两条规则打架时，Claude 可能随便挑一条。定期检查，删掉过时的。

练一练：这条该放哪？

不是所有"要记住的事"都该进 CLAUDE.md。每条选一个最合适的去处。

04入门

放在哪里：四个位置

同样叫 CLAUDE.md，放的位置不同，给谁用就不同。

范围位置给谁用放什么
组织策略公司里所有人公司规范、安全要求。由 IT 统一下发，个人不能排除
个人~/.claude/CLAUDE.md只有你，所有项目你的习惯，比如"回复用中文"
项目./CLAUDE.md 或
./.claude/CLAUDE.md		整个团队（提交到 git）项目架构、代码规范、常用命令
本地./CLAUDE.local.md只有你，当前项目你本机的测试地址、个人测试数据。记得加进 .gitignore

练一练：这条放哪个位置？

怎么打开和编辑

输入 /memory，会列出个人和项目范围里的记忆文件，选一个就在编辑器里打开。个人和项目的 CLAUDE.md 就算还没创建也会列出来，选中就会新建。自动记忆的开关和文件夹也在这里。

05原理

加载顺序：拼在一起，不是覆盖

多个 CLAUDE.md 同时存在时，Claude Code 会把它们全部拼接进上下文，而不是只用"优先级最高"的那个。

Claude Code 从你启动的目录开始，往上找每一层目录里的 CLAUDE.md 和 CLAUDE.local.md，启动时全部读进来；往下的子目录里的，要等 Claude 读到那个子目录里的文件时才加载。换个启动目录、让 Claude 读几个文件，看看"上下文里的顺序"怎么变：

文件
在哪里启动 Claude Code
工作中，Claude 读了……
上下文里的顺序（从先到后）
    • 越靠后，越晚被读到。离启动目录越近的文件越靠后；同一目录里，CLAUDE.local.md 排在 CLAUDE.md 后面。
    • 没有谁覆盖谁。个人规则和项目规则互相矛盾时，Claude 照哪条做都有可能。发现冲突就改掉一条。
    • "组织策略"最先加载，而且个人没法把它排除。
    压缩之后还在吗？

    项目根目录的 CLAUDE.md、没写 paths 的规则和自动记忆，都会在 /compact 后从磁盘重新读取，不会丢。子目录的 CLAUDE.md 和带 paths 的规则会暂时跟着对话一起被压缩掉，等 Claude 下次读到相关文件时再加载回来。真正会丢的，是只在对话里说过、没写进文件的要求，所以重要的话要写进文件。

    06原理

    @ 导入与 .claude/rules/

    CLAUDE.md 越写越长时，有两种拆法。一种只是"整理"，另一种才真正"省空间"。

    @ 导入：引用已有的文档

    CLAUDE.md
    项目概况见 @README.md
可用的 npm 命令见 @package.json

# Git 流程
- 分支和提交规范见 @docs/git-instructions.md
    • 相对路径相对于写这行的文件，不是相对于启动目录；也可以用绝对路径或 @~/…。
    • 被导入的文件还能继续导入，最多 4 层。
    • 写在反引号或代码块里的 @路径 不会被导入，只是文字，所以可以放心地在文档里举例。
    • 项目文件第一次导入工作目录以外的文件时，会弹窗请你确认。这是为了防止别人提交的文件偷偷引入你电脑上的内容。
    导入不省上下文

    被导入的文件启动时就会全部加载，和直接写在 CLAUDE.md 里占的空间一样。它的好处是避免重复、方便维护，不是瘦身。

    .claude/rules/：按主题拆，还能按文件生效

    .claude/rules/api.md
    ---
paths:
  - "src/api/**/*.ts"
---

# 接口开发规则
- 所有接口都要校验输入参数
- 错误统一用标准的响应格式
    • 每个文件讲一个主题，比如 testing.md、security.md；子目录也会被扫描到。
    • 没写 paths：启动时加载，地位和 .claude/CLAUDE.md 一样。
    • 写了 paths：只有 Claude 读到匹配的文件时才加载。这才是真正省上下文的拆法。paths 也是规则文件唯一会被读取的字段。
    • 放在 ~/.claude/rules/ 的是个人规则，对你所有项目生效，加载顺序在项目规则之前。

    试一试：这个文件会触发哪些规则？

    Claude 读了
    写法匹配
    **/*.ts任意目录下的所有 .ts 文件
    src/**/*src/ 下的所有文件
    *.md项目根目录下的 Markdown 文件（不含子目录）
    src/**/*.{ts,tsx}用花括号同时匹配多种扩展名
    07原理

    自动记忆：Claude 自己记的笔记

    你纠正过它的事、你的偏好，Claude 会自己记下来，下次对话开始时再读。默认就是开着的。

    Claude 会把笔记分成四类，记在每个文件开头的 type 字段里：

    user你是谁：角色、擅长什么、工作习惯
    feedback你纠正过它的、你确认过的做法
    project进行中的工作、截止日期，以及代码里看不出来的决定
    reference项目外的信息在哪：工单系统、监控看板

    能从代码里看出来的东西（架构、文件路径、改过的 bug），以及 CLAUDE.md 里已经写了的，它都不会重复记。也不是每次对话都会记：它只记下以后可能用得上的。

    打开文件夹看看

    自动记忆存在 ~/.claude/projects/<项目>/memory/，全是普通的 Markdown，你可以随时查看、修改、删除。下面是一个示例文件夹：

    memory
    ~/.claude/projects/my-app/memory
    • MEMORY.md 是索引，一条一行。每段对话开始时只读它的前 200 行或前 25KB（先到哪个算哪个），超出的部分读不到，所以 Claude 会把细节挪进单独的主题文件。
    • 主题文件按需读取：启动时不加载，Claude 需要时才打开。
    • 只在本机：同一个 git 仓库的各个 worktree、子目录共用一份；不会同步到别的电脑或云端。
    • 界面里看到 "Saved 2 memories"、"Recalled 2 memories"，就是它在写入或读取这个文件夹。

    你说的话，决定记到哪里

    你怎么说记到哪里
    "记住：我们一律用 pnpm"自动记忆
    "把『用 pnpm』加到 CLAUDE.md 里"CLAUDE.md
    输入 /memory，自己打开文件改你选的那个文件
    开关在哪

    在 /memory 里切换自动记忆开关，会写进 ~/.claude/settings.json 的 autoMemoryEnabled。只想对某个项目关掉，就在那个项目的 .claude/settings.local.json 里写 "autoMemoryEnabled": false（写在 .claude/settings.json 会提交到 git，整个团队都关掉）；也可以用环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

    08实战

    终端演练：让 Claude 记住规矩

    从 /init 开始，看记忆怎样跨过一次新对话。点"下一步"回放，放完可以自己输入。

    my-app — claude — 90×28
    >

    终端画面为教学示意，与真实 Claude Code 的界面细节可能略有不同，但记忆的工作方式一致。

    09实战

    给你的 CLAUDE.md 做个体检

    把你的 CLAUDE.md 贴进来，对照这节课讲的原则逐条检查。

    载入示例：

    这是按本课原则做的简单规则比对，方便自查，不代表 Claude 实际怎么读。Claude Code 自带的 /doctor 也会检查 CLAUDE.md，并建议删掉能从代码里推断出来的内容。

    三份模板

    原教程仓库提供的三份 CLAUDE.md 示例，保留英文原文。里面的具体数字、人名是示例，拿去用时换成你项目的实际情况。

    保存为
    10深入

    进阶与避坑

    团队协作、大仓库、和其他 AI 工具共存时会遇到的问题。

    Claude 不照 CLAUDE.md 做
    1. 先 /context 看 Memory files 列表里有没有这个文件。没有就是没加载，检查位置对不对。
    2. 把要求写得更具体："用 2 个空格缩进"比"格式整齐"有效得多。
    3. 找找有没有互相矛盾的规则，包括子目录的 CLAUDE.md 和 .claude/rules/。
    4. CLAUDE.md 是作为一条用户消息放在系统提示之后的，本来就不保证严格执行。必须执行的动作写成 hook（第 6 课）。
    项目里已经有 AGENTS.md
    v2.1.277 起，Claude Code 可以直接读 AGENTS.md（很多 AI 编程工具通用的项目说明文件）。默认规则是：找不到任何项目级 CLAUDE.md 时才读 AGENTS.md；两者都有时只读 CLAUDE.md。想两个都读，在 /config 里把 Project instructions 设成 claude-md-and-agents-md。也可以在 CLAUDE.md 里写一行 @AGENTS.md 导入它，不会被读两遍。
    加了 CLAUDE.local.md 之后，AGENTS.md 不生效了
    因为 CLAUDE.local.md 也算"有 CLAUDE.md"，默认规则下 AGENTS.md 就不再读了。解决办法同上：改 Project instructions 设置，或在 CLAUDE.md 里导入 @AGENTS.md。
    大仓库里总加载别的团队的 CLAUDE.md
    在设置里用 claudeMdExcludes 跳过它们。这些写法是拿去和文件的绝对路径比对的，所以要么写完整路径，要么用 **/ 开头："claudeMdExcludes": ["**/packages/legacy-app/CLAUDE.md", "**/vendors/**/CLAUDE.md"]。只想对自己生效，就写在 .claude/settings.local.json 里。组织策略的 CLAUDE.md 不能被排除。
    想在 CLAUDE.md 里写给人看的备注，又不想占上下文
    用 HTML 注释 <!-- 备注 -->。块级 HTML 注释在交给 Claude 之前会被去掉，不占 token；代码块里的注释会保留。
    用 --add-dir 加了别的目录，那边的 CLAUDE.md 没加载
    默认不加载。启动时设置环境变量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 才会一起读那个目录的 CLAUDE.md、.claude/rules/ 和 CLAUDE.local.md。
    CLAUDE.md 太长了怎么办
    超过 200 行就该瘦身（超过 4 MiB 的文件会被直接跳过）。多步流程改成 skill（第 5 课），只和部分文件有关的规则改成带 paths 的 rules；@ 导入只能整理，不能瘦身。也可以跑一次 /doctor，它会建议删掉能从代码里推断出来的内容。
    老教程里的 # 快捷记忆不能用了
    以前在输入框开头打 # 可以快速加一条记忆，这个快捷方式已经取消。现在直接对 Claude 说"记住……"（存到自动记忆），或"把……加到 CLAUDE.md"，或用 /memory 自己改。
    11检验

    小测验

    8 道题，每题选完会立刻看到解析。