使用记忆机制

Claude Code 的记忆不是一个神秘数据库，而是每次会话开始时被装进上下文的一组说明。你把规则写清楚，它就少走弯路；你把规则写乱，它会把混乱也带进下一次工作。——翔宇

1. 先划清边界：记忆是上下文，不是强制层

新手最容易把三件事混在一起：

• 记忆：告诉 Claude 项目结构、约定、偏好、经验。
• 配置：告诉 Claude Code 客户端如何运行，比如 scope（作用域）、环境变量、Hooks、模型、插件。
• 权限：控制工具调用能不能执行，比如 Bash、Read、Edit、WebFetch、MCP 工具。

CLAUDE.md 和 auto memory 都属于第一类。它们会影响 Claude 的判断，但不会像 permissions.deny 那样强制拦截工具。

如果你在 CLAUDE.md 写：

## Security

- Never read `.env` files.

这是一条行为提醒。它有用，但不是安全边界。

如果你要真的阻止读取 .env，要写进 settings permissions：

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

2. Claude Code 每次启动会装载什么

一个会话开始时，Claude Code 会把多种材料放进上下文窗口：

• 当前对话。
• 系统指令。
• 你启动位置相关的 CLAUDE.md / CLAUDE.local.md。
• 规则文件 .claude/rules/*.md。
• auto memory 的入口内容。
• 后续工具读到的文件、命令输出、网页内容。

可以把它理解成一条启动流水线：

这里最关键的是：上下文会被消耗。规则越多，占用越多；规则越模糊，遵循越不稳定。

3. 两套记忆：你写的，和 Claude 自己写的

Claude Code 官方把记忆分成两类。

机制               谁写                 主要用途
----------------   ------------------   ------------------------------
CLAUDE.md          你或团队              项目规则、命令、架构、工作流
auto memory        Claude 自动维护       调试经验、偏好、反复纠正过的事

CLAUDE.md 更像项目手册。它适合放稳定、明确、团队可共享的内容：

• 项目结构。
• 构建、测试、发布命令。
• 代码风格。
• 命名约定。
• 常见工作流。
• 不该靠代码自动推断的团队规则。

Auto memory 更像 Claude 的本地笔记。它适合记录 Claude 在工作中学到的东西：

• 某个测试需要本地 Redis。
• 这个项目总是用 pnpm，不要用 npm。
• 某个模块的调试入口。
• 你多次纠正过的个人偏好。

4. CLAUDE.md 应该放在哪里

位置决定作用域。

作用域             位置
----------------   --------------------------------------------------
组织级             macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
组织级             Linux / WSL: /etc/claude-code/CLAUDE.md
组织级             Windows: C:\Program Files\ClaudeCode\CLAUDE.md
项目共享           ./CLAUDE.md
项目共享           ./.claude/CLAUDE.md
用户全局           ~/.claude/CLAUDE.md
本地个人           ./CLAUDE.local.md

选择方式很直接：

• 所有机器、所有人都必须遵守：组织级 managed CLAUDE.md。
• 这个仓库所有协作者都应该知道：项目 CLAUDE.md 或 .claude/CLAUDE.md。
• 只有你自己所有项目都要用：~/.claude/CLAUDE.md。
• 只有你自己、当前项目、当前机器要用：CLAUDE.local.md。

CLAUDE.local.md 应该加入 .gitignore。它适合写本机端口、个人测试账号名、个人习惯、临时实验说明。

如果你设置了 CLAUDE_CONFIG_DIR，官方文档里的 ~/.claude 路径会整体移动到那个目录下。排障时要先确认这一点，否则你可能一直在看错误的配置目录。

5. 什么时候该写进 CLAUDE.md

官方给的判断很实用：你本来会反复向 Claude 解释的东西，就应该沉淀进 CLAUDE.md。

适合写入：

• Claude 第二次犯同一个项目级错误。
• 代码审查指出它本应知道的约定。
• 新同事也需要知道的启动、测试、发布流程。
• 项目结构不明显，靠文件名很难推断。
• 某个目录有强规则，比如 API handler、数据库迁移、支付逻辑。

不适合写入：

• 一次性任务背景。
• 长篇会议纪要。
• 密钥、账号、token。
• 复杂操作 SOP 的完整正文。
• 只对某个文件类型生效的规则。
• Claude 自动发现即可的普通代码事实。

多步 SOP 更适合做 Skill。只对部分路径生效的规则，更适合 .claude/rules/。

6. 怎么写一个有效的 CLAUDE.md

有效的记忆有三个特点：

• 具体：能被验证。
• 稳定：下周仍然成立。
• 简短：每句话都值得进入上下文。

弱规则长这样：

## Coding

- Write clean code.
- Be careful.
- Follow best practices.

这类规则几乎不可执行。它们听起来正确，但 Claude 无法稳定判断“clean”和“best”到底是什么。

更好的写法是：

## Project Commands

- Use `pnpm install` to install dependencies.
- Use `pnpm test` before changing files under `src/core/`.
- Use `pnpm build` before opening a pull request.

## Code Conventions

- API handlers live under `src/api/handlers/`.
- Database migrations live under `db/migrations/`.
- Public React components use PascalCase filenames.
- Do not edit generated files under `src/generated/`.

## Workflow

- Before changing payment code, read `docs/payment-flow.md`.
- After editing GraphQL schema, run `pnpm codegen`.

这份文件不追求完整解释项目，只告诉 Claude 不能靠猜的关键事实。

7. /init 可以帮你生成起点

新项目可以直接在 Claude Code 里运行：

/init

官方说明：/init 会分析代码库，生成或改进项目 CLAUDE.md，通常会包含构建命令、测试命令和项目约定。已有 CLAUDE.md 时，它会建议改进，而不是简单覆盖。

官方还提供了一个新流程开关：

CLAUDE_CODE_NEW_INIT=1 claude

启用后，/init 会以更交互的多阶段方式询问要设置哪些 artifact，比如 CLAUDE.md、Skills、Hooks。它会先探索代码库，再提出可审查的方案。

8. @import：拆文件，不等于省上下文

CLAUDE.md 可以用 @path 导入其他文件：

## Project Context

- See @README.md for product overview.
- See @package.json for script names.
- See @docs/release-checklist.md before release work.

关键规则：

• 相对路径按包含 import 的文件解析，不按当前 shell 工作目录解析。
• 绝对路径和 ~ 路径也可以使用。
• 导入可以递归。
• 最大递归深度是 5 层。
• 首次遇到项目外部导入时，Claude Code 会弹出确认。
• 如果用户拒绝外部导入，后续不会继续读取那些外部文件。

拆 import 适合组织内容，但它不会减少上下文。被导入的内容仍然会在启动时展开并进入上下文。

9. AGENTS.md 怎么兼容

官方口径很明确：Claude Code 读取 CLAUDE.md，不是直接读取 AGENTS.md。

如果一个仓库已经有 AGENTS.md，更稳的方式是新建一个 CLAUDE.md 导入它：

@AGENTS.md

## Claude Code

- Use plan mode before changing files under `src/billing/`.
- Run `/memory` when debugging instruction loading.

这样其他 agent 仍然读 AGENTS.md，Claude Code 通过 CLAUDE.md 读同一份基础规则，再追加 Claude-specific 说明。

10. 加载顺序：越靠近启动目录，越晚进入上下文

Claude Code 会从当前工作目录一路向上查找：

• CLAUDE.md
• CLAUDE.local.md

假设你在这个目录启动：

/repo/apps/web

可能加载：

/repo/CLAUDE.md
/repo/CLAUDE.local.md
/repo/apps/CLAUDE.md
/repo/apps/CLAUDE.local.md
/repo/apps/web/CLAUDE.md
/repo/apps/web/CLAUDE.local.md

官方说明的顺序是从更高层目录到当前目录。同一目录里，CLAUDE.local.md 接在 CLAUDE.md 后面。也就是说，越靠近启动位置，越晚进入上下文，通常更容易影响最终行为。

这不是“覆盖”。所有发现的文件会拼接进上下文。冲突规则仍然是冲突规则。

11. 子目录规则是按需加载的

启动时，Claude 不会把当前工作目录下面所有子目录的 CLAUDE.md 都读进来。

如果你在 /repo 启动：

/repo/CLAUDE.md
/repo/frontend/CLAUDE.md
/repo/backend/CLAUDE.md

启动时会读 /repo/CLAUDE.md。frontend/CLAUDE.md 和 backend/CLAUDE.md 会在 Claude 读取对应子目录文件时按需加载。

这对大型 monorepo 很重要：你不需要把所有团队规则都塞进根文件，也不需要让前端任务一开始就加载后端全部规则。

12. 附加目录不会默认加载记忆

--add-dir 可以给 Claude 额外目录访问权限：

claude --add-dir ../shared-config

但官方说明：默认不会加载这个附加目录里的 CLAUDE.md。

如果你想同时加载附加目录里的记忆文件，需要设置：

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

这会加载附加目录中的：

• CLAUDE.md
• .claude/CLAUDE.md
• .claude/rules/*.md
• CLAUDE.local.md

如果你用 --setting-sources 排除了 local，附加目录里的 CLAUDE.local.md 也会被跳过。

13. .claude/rules/：给大型项目拆规则

当 CLAUDE.md 变长，第一反应不应该是继续加标题，而是把路径相关规则拆到 .claude/rules/。

推荐结构：

your-project/
  .claude/
    CLAUDE.md
    rules/
      code-style.md
      testing.md
      security.md
      frontend/
        react.md
      backend/
        api.md

规则文件是普通 Markdown。官方说明所有 .md 文件会被递归发现。

没有 paths frontmatter 的规则，会像 .claude/CLAUDE.md 一样每次加载。

带 paths 的规则，只在 Claude 处理匹配文件时加载：

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

## API Development Rules

- All API handlers must validate input.
- Use the shared error response format.
- Update OpenAPI comments when adding endpoints.

适合用 path rules 的场景：

• src/api/** 有接口约定。
• db/migrations/** 有迁移规则。
• packages/mobile/** 和 packages/web/** 使用不同框架。
• *.test.ts 必须走固定测试工具。
• docs/** 有写作和链接规则。

14. user-level rules 与项目规则的关系

你也可以把个人规则放在：

~/.claude/rules/

这适合写个人偏好，例如：

• 所有项目默认先读 CLAUDE.md。
• 回答默认使用简体中文。
• 代码审查默认先列风险。

官方说明：user-level rules 先加载，project rules 后加载，所以项目规则优先级更高。

这个设计是合理的。你可以有全局习惯，但项目约定应该能压过个人习惯。

15. 规则支持 symlink，但要避免环

.claude/rules/ 支持 symlink。你可以把一套共享规则维护在一个目录，然后链接到多个项目：

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

官方说明 symlink 会正常解析，循环 symlink 会被检测并处理。

这个能力适合个人多仓库或组织模板，但不适合把所有规则都做成全局大包。共享规则越多，越要保持单一职责。

16. claudeMdExcludes：跳过不相关的记忆

大型 monorepo 里，经常会遇到祖先目录或其他团队的 CLAUDE.md 被加载，结果规则不相关甚至冲突。

官方提供 claudeMdExcludes：

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

建议放在：

.claude/settings.local.json

原因是排除哪些父级规则，往往和你当前机器、当前工作方式有关，不一定应该提交给团队。

注意两点：

• 匹配的是绝对文件路径。
• managed policy 的 CLAUDE.md 不能被排除。

17. block HTML comments 会被剥离

官方说明：CLAUDE.md 里的 block-level HTML comments 会在注入上下文前被剥离。

这意味着你可以给人类维护者留备注：

<!-- This section is for maintainers and will not enter Claude context. -->

## Build Commands

- Use `pnpm build` before release.

这些注释不会消耗上下文 token。代码块里的注释会保留；你直接用 Read 工具打开 CLAUDE.md 时，也仍然能看到注释。

18. Auto memory 默认开启

Auto memory 是 Claude 自己维护的跨会话笔记。官方说明它从 Claude Code v2.1.59 起可用，并且默认开启。

你可以用三种方式控制：

方式                         用途
--------------------------   --------------------------------
/memory                      会话内查看、编辑、切换 auto memory
autoMemoryEnabled            在项目 settings 里启用或关闭
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1   用环境变量关闭

关闭示例：

{
  "autoMemoryEnabled": false
}

Auto memory 不会每个会话都写。Claude 会判断某条信息未来是否有用，再决定是否保存。

19. Auto memory 存在哪里

默认位置是：

~/.claude/projects/<project>/memory/

目录里通常有：

memory/
  MEMORY.md
  debugging.md
  api-conventions.md
  other-topic-files.md

<project> 由 git repository 推导。同一个仓库里的不同 worktree 和子目录会共享同一个 auto memory 目录。仓库外则按 project root 推导。

Auto memory 是机器本地的：

• 不会自动跨机器同步。
• 不会自动进入 GitHub。
• 不会自动进入云端开发环境。
• 不会替代项目 CLAUDE.md。

如果你要改存储位置，可以在 user settings 写：

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

官方限制：autoMemoryDirectory 必须是绝对路径或以 ~/ 开头，并且只接受 policy、user settings 或命令行 --settings。不能放在 project/local settings 里。

这个限制是安全设计：仓库不能通过提交项目配置，把你的个人记忆重定向到敏感路径。

20. MEMORY.md 不是无限加载

Auto memory 目录里的入口文件是：

MEMORY.md

官方说明：每次会话开始只加载 MEMORY.md 的前 200 行，或前 25KB，取较小者。

详细主题文件不会启动时全部加载。Claude 会在需要时用标准文件工具按需读取，比如：

• debugging.md
• architecture.md
• test-fixtures.md
• api-conventions.md

这也是为什么 MEMORY.md 应该像索引，而不是长文档。

21. /memory 是排障入口

当你不确定 Claude 到底读了什么，先运行：

/memory

官方说明 /memory 可以：

• 列出当前会话加载的 CLAUDE.md。
• 列出 CLAUDE.local.md。
• 列出 rules 文件。
• 切换 auto memory。
• 打开 auto memory 文件夹。
• 选择文件用编辑器打开。

你也可以直接让 Claude 记住某条经验：

Remember that this project uses pnpm, not npm.

如果你想把内容写进 CLAUDE.md，表达要更明确：

Add this rule to CLAUDE.md: use pnpm test before editing src/core.

22. 记忆、rules、Skill、settings 怎么选

把内容放错地方，是 Claude Code 项目越用越乱的主要原因。

需求                                      放哪里
---------------------------------------   --------------------------------
所有人每次都要知道的项目规则              CLAUDE.md
只对某些路径或文件类型生效的规则          .claude/rules/*.md
跨项目个人表达偏好                        ~/.claude/CLAUDE.md 或 ~/.claude/rules/
一次可复用的复杂工作流                    Skill
工具权限、环境变量、Hooks、模型、插件     settings.json
MCP server 连接                            .mcp.json 或 MCP 配置
Claude 从纠正中学到的本机经验             auto memory
企业强制策略                              managed settings 或 managed CLAUDE.md

几个判断句：

• 要强制执行，用 settings / permissions。
• 要按路径加载，用 rules。
• 要复用流程，用 Skill。
• 要团队共享，用 project scope。
• 要个人保留，用 user 或 local scope。
• 要 Claude 自己学，用 auto memory。

23. 组织级 CLAUDE.md 和 managed settings 分工

组织可以部署 managed CLAUDE.md，让所有用户都加载组织级说明。

适合写进 managed CLAUDE.md：

• 公司代码风格。
• 数据处理提醒。
• 合规要求说明。
• 代码审查原则。
• 内部仓库结构说明。

不适合只写在 managed CLAUDE.md：

• 禁止某个工具。
• 禁止读取某类路径。
• 强制 sandbox。
• 强制登录方式。
• 强制组织账号。

这些应该进 managed settings，因为 settings 由客户端执行，不能靠 Claude 自觉。

24. /compact 后为什么像忘了

上下文会填满，Claude Code 会压缩旧上下文。用户也可以运行：

/compact

官方说明：项目根 CLAUDE.md 会在 compaction 后从磁盘重新读取并重新注入会话。

但嵌套目录里的 CLAUDE.md 不会自动全部重新注入。它们需要等 Claude 再次读取对应子目录里的文件时触发。

所以 /compact 后出现“忘了某条规则”，常见原因是：

• 那条规则只在对话里说过，没有写进 CLAUDE.md。
• 那条规则在嵌套目录 CLAUDE.md 里，但对应目录还没重新触发。
• 规则太模糊或和其他规则冲突。
• 规则来自 auto memory topic file，启动时没有直接加载。

25. 常见故障：Claude 不听 CLAUDE.md

按这个顺序查：

1. 运行 /memory，确认文件真的被列出。
2. 确认你在正确目录启动 Claude Code。
3. 检查是否设置了 CLAUDE_CONFIG_DIR。
4. 检查是否被 claudeMdExcludes 排除。
5. 检查规则是不是太长、太泛、互相冲突。
6. 检查相关规则是不是 path-scoped，还没有被触发。
7. 检查是否刚 /compact，嵌套规则还没重新加载。
8. 必要时用 InstructionsLoaded hook 记录加载了哪些 instruction files。

如果你想把某段说明提升到系统提示词层级，官方提到可以用 --append-system-prompt。但它需要每次 invocation 都传入，更适合脚本和自动化，不适合作为普通交互项目的长期规则。

26. 常见故障：不知道 auto memory 写了什么

直接运行：

/memory

然后打开 auto memory folder。

Auto memory 是普通 Markdown，你可以：

• 读取。
• 编辑。
• 删除。
• 拆分 topic。
• 删除不该保留的敏感内容。

当界面出现 Writing memory 或 Recalled memory，说明 Claude 正在写入或读取 auto memory 目录。

27. 一个新项目的推荐落地顺序

新项目不要一上来写大而全的规则。按这个顺序收敛：

最小可用版本长这样：

your-project/
  CLAUDE.md
  .claude/
    settings.json
    rules/
      testing.md
      security.md

28. 自检清单

学完这一章，你应该能完成这些判断：

• 我能解释为什么记忆不是权限系统。
• 我能判断一条规则该放 CLAUDE.md、.claude/rules/、Skill、settings 还是 auto memory。
• 我知道 CLAUDE.local.md 应该 gitignored。
• 我知道 @import 会进入上下文，不是省 token。
• 我知道 Claude Code 读取 CLAUDE.md，不是直接读取 AGENTS.md。
• 我知道子目录 CLAUDE.md 是按需加载，不是启动时全量加载。
• 我知道 --add-dir 不会默认加载附加目录记忆。
• 我知道 auto memory 默认位置和 MEMORY.md 启动加载限制。
• 我能用 /memory 排查当前会话到底加载了什么。
• 我能把安全边界放进 permissions，而不是只写进记忆。

29. 术语速查

• CLAUDE.md：Claude Code 每次会话加载的长期说明文件。
• CLAUDE.local.md：当前项目的个人本地说明，通常不提交。
• .claude/CLAUDE.md：项目级说明的另一种官方位置。
• .claude/rules/：可按路径或主题拆分的规则目录。
• paths frontmatter：控制某条 rule 何时按文件路径加载。
• @import：在 CLAUDE.md 中导入其他文件的语法。
• auto memory：Claude 自动维护的跨会话本地笔记。
• MEMORY.md：auto memory 入口索引文件。
• /memory：查看、编辑、切换记忆的命令。
• claudeMdExcludes：排除某些 CLAUDE.md 或 rules 的 settings 字段。
• InstructionsLoaded hook：调试 instruction 文件加载的 hook。
• managed CLAUDE.md：组织级统一下发的说明文件。

官方来源

• How Claude remembers your project
• Explore the .claude directory
• Claude Code settings
• How Claude Code works