11. CLAUDE.md 记忆系统

为什么需要记忆系统

每次启动 Claude Code，都是一个新的上下文窗口（Context Window）。上一轮对话里你说的”用 pnpm 不要用 npm”、“缩进 2 个空格”、“别动 migrations 目录”，Claude 全都忘了。

这就像你每天换一个新助手，得把项目背景从头讲一遍。烦不烦？

记忆系统就是解决这个问题的。它让知识能跨会话持久保存，每次对话开始时自动加载。Claude Code 提供了两套互补的记忆机制：

• CLAUDE.md 文件：你手动写的指令，告诉 Claude 该怎么干。
• 自动记忆（Auto Memory）：Claude 自己记的笔记，从你的纠正和偏好中学习。

两者在每次会话开始时都会加载。Claude 把它们当作参考上下文，而不是强制配置。指令越具体、越简洁，Claude 遵循得越一致。

两套记忆机制对比

维度	CLAUDE.md 文件	自动记忆（Auto Memory）
谁写	你	Claude 自己
内容	指令和规则	学习和模式
范围	项目、用户或组织	每个工作树，跨 worktree 共享
加载	每次会话完整加载	前 200 行或 25KB
用途	编码标准、工作流、架构	构建命令、调试经验、偏好

简单说：CLAUDE.md 是你给 Claude 写的工作手册，自动记忆是 Claude 自己记的笔记本。

CLAUDE.md 文件

什么是 CLAUDE.md

CLAUDE.md 是一个普通的 Markdown 文件，放在项目目录里。Claude Code 每次启动会自动读取它，把内容作为上下文注入对话。

你可以把它想象成新员工入职时拿到的那份项目说明文档：技术栈是什么、代码放哪、怎么跑测试、哪些东西不能碰。写一次，每次都生效。

四层作用域

CLAUDE.md 可以放在不同位置，作用范围从大到小：

范围	位置	用途	共享对象
托管策略	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md Linux/WSL: /etc/claude-code/CLAUDE.md Windows: C:\Program Files\ClaudeCode\CLAUDE.md	IT/DevOps 管理的组织级指令	组织中所有用户
用户级	~/.claude/CLAUDE.md	所有项目的个人偏好	仅你（所有项目）
项目级	./CLAUDE.md 或 ./.claude/CLAUDE.md	团队共享的项目指令	通过 Git 共享给团队
本地级	./CLAUDE.local.md	个人项目特定偏好	仅你（当前项目）

加载顺序从最广泛到最具体：托管策略 -> 用户级 -> 项目级 -> 本地级。越具体的指令后加载，在上下文中出现在后面，相当于”最后读到”。

文件加载机制

Claude Code 启动时，会从当前工作目录向上遍历目录树，沿途检查每个目录有没有 CLAUDE.md 和 CLAUDE.local.md。

比如你在 foo/bar/ 启动 Claude Code，它会依次加载：

foo/CLAUDE.md          → 先加载
foo/bar/CLAUDE.md      → 后加载（更具体的指令）
foo/bar/CLAUDE.local.md → 最后加载（你的个人笔记）

所有文件被拼接在一起，不是相互覆盖。越靠近工作目录的文件，内容出现在上下文越后面。

子目录里的 CLAUDE.md 不会在启动时加载，而是当 Claude 读取该子目录的文件时按需加载。这样既省 token，又能提供精准的上下文。

用 /init 快速创建

最简单的创建方式是在会话中执行：

/init

Claude 会分析你的项目结构、代码风格、已有配置文件（package.json、pyproject.toml、.eslintrc 等），自动生成一份符合项目实际的 CLAUDE.md。如果文件已存在，/init 会建议改进而不是覆盖。

也可以手动创建：

touch CLAUDE.md

编写有效指令

CLAUDE.md 每次会话都会加载到上下文窗口，和你的对话一起消耗 token。所以写得好不好，直接影响 Claude 遵循指令的可靠性。

控制大小：每个文件目标在 200 行以下。太长会消耗更多上下文，降低遵守度。如果你的指令很大，用后面讲的路径范围规则，让指令只在处理匹配文件时加载。

用结构化格式：用 Markdown 标题和项目符号分组。Claude 扫描结构的方式和人一样：有组织的段落比密集的文字更容易遵循。

写具体的指令：具体到能验证的程度。

模糊写法	具体写法
”正确格式化代码"	"使用 2 空格缩进"
"测试你的更改"	"提交前运行 npm test"
"保持文件有组织"	"API 处理程序放在 src/api/handlers/"
"注意安全"	"用户输入必须经过 sanitize() 处理”

保持一致性：如果两条规则相互矛盾，Claude 可能随便选一条。定期审查 CLAUDE.md，删掉过时或冲突的指令。

推荐的内容结构

# 项目名称

一句话说明项目是什么。

## 技术栈
- 语言：Python 3.11
- 框架：FastAPI 0.110
- 数据库：PostgreSQL 15 + SQLAlchemy
- 测试：pytest

## 常用命令
```bash
uv run uvicorn main:app --reload   # 启动开发服务器
uv run pytest                       # 运行所有测试
uv run ruff check .                 # 代码检查

项目结构

• src/api/ - API 路由
• src/models/ - 数据库模型
• src/services/ - 业务逻辑

编码规范

• 所有函数必须有类型注解
• 字符串一律使用双引号
• 新增 API 路由必须同步添加测试

注意事项

• 不要修改 migrations/ 下的已有文件
• config/secrets.py 包含敏感配置，禁止输出内容
• 数据库操作必须通过 Service 层

核心模块就这几个：技术栈、常用命令、项目结构、编码规范、注意事项。每条规则只写一次，不重复。

### 五个核心内容模块

**常用命令**是最高频被参考的部分。Claude 执行测试、构建、代码检查时会优先查找这里，避免猜错命令：

```markdown
## 常用命令
```bash
pnpm dev                    # 启动开发服务器（端口 3000）
pnpm build                  # 构建生产版本
pnpm test                   # 运行所有测试
pnpm lint && pnpm typecheck # 代码检查和类型检查

**项目结构说明**帮 Claude 快速定位文件，减少不必要的目录扫描：

```markdown
## 项目结构
- `src/app/` - App Router 页面和 API 路由
- `src/components/` - 可复用组件
- `src/lib/` - 工具函数和配置
- `prisma/schema.prisma` - 数据库 Schema 定义

编码规范确保生成的代码和现有代码库风格一致。写具体的规则，不要写”遵循最佳实践”这种废话。

架构约束和禁止事项是防止 Claude 做”聪明但错误”决策的关键。你了解但 Claude 不知道的特殊情况，必须明确写出来：

## 注意事项
- `legacy/` 目录下的代码禁止修改，只能读取
- `.env.local` 包含真实密钥，禁止输出文件内容
- `prisma/migrations/` 中已有文件禁止修改，只能新增迁移
- 修改 `src/middleware.ts` 前必须先告知我

开发环境说明帮 Claude 理解运行环境，避免因环境差异导致命令执行失败：

## 开发环境
- Node.js：v20 或以上
- 包管理器：pnpm（禁止使用 npm 或 yarn）
- 本地数据库：docker compose up -d
- 端口：前端 3000，API 3001，数据库 5432

用 @ 语法导入外部文件

CLAUDE.md 可以用 @路径 语法导入其他文件。导入的文件在启动时展开并加载到上下文中，和引用它的 CLAUDE.md 一起。

有关项目概述，请参阅 @README，有关 npm 命令，请参阅 @package.json。

# 其他指令
- git 工作流 @docs/git-instructions.md

路径是相对于 CLAUDE.md 所在目录解析的。导入可以递归，最多四层。

第一次遇到外部导入时，Claude Code 会弹出批准对话框列出这些文件。你拒绝的话，导入保持禁用。

用 .claude/rules/ 组织规则

项目大了以后，一个 CLAUDE.md 不够用。你可以用 .claude/rules/ 目录把指令拆成多个文件，按主题组织：

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主项目指令
│   └── rules/
│       ├── code-style.md   # 代码样式指南
│       ├── testing.md      # 测试约定
│       └── security.md     # 安全要求

没有 paths frontmatter 的规则在启动时加载，优先级和 .claude/CLAUDE.md 相同。

路径范围规则

规则可以用 YAML frontmatter 限定到特定文件类型。这些条件规则只在 Claude 处理匹配文件时才加载，省 token 又精准：

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

# API 开发规则

- 所有 API 端点必须包括输入验证
- 使用标准错误响应格式
- 包括 OpenAPI 文档注释

常用的 glob 模式：

模式	匹配
**/*.ts	任何目录中的 TypeScript 文件
src/**/*	src/ 目录下所有文件
*.md	项目根目录的 Markdown 文件
src/components/*.tsx	特定目录的 React 组件

一个规则文件可以指定多个模式：

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

用户级规则

~/.claude/rules/ 里的规则对你机器上的每个项目生效，适合放跨项目通用的个人偏好：

~/.claude/rules/
├── preferences.md    # 个人编码偏好
└── workflows.md      # 首选工作流

用户级规则在项目规则之前加载，项目规则优先级更高。

自动记忆（Auto Memory）

它是什么

自动记忆让 Claude 跨会话积累知识，不需要你写任何东西。Claude 在工作时自己记笔记：构建命令、调试见解、架构笔记、代码风格偏好、工作流习惯。

它不会每次都记，而是判断哪些信息在未来对话中有用才写入。

存储位置

每个项目在 ~/.claude/projects/<project>/memory/ 有自己的记忆目录。<project> 路径来自 Git 仓库，所以同一仓库的所有 worktree 和子目录共享一个记忆目录。

目录结构：

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 索引文件，每次会话加载前 200 行
├── debugging.md       # 调试模式笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 创建的其他主题文件

MEMORY.md 是索引，前 200 行或 25KB（以先到者为准）在每次会话开始时加载。超过的部分不加载。Claude 会把详细笔记移到单独的主题文件里，保持索引简洁。

主题文件（如 debugging.md）在启动时不加载，Claude 需要时用标准文件工具按需读取。

怎么触发

当你告诉 Claude 某些事情时，它会自动保存到记忆中：

你：始终使用 pnpm，不要用 npm
你：记住 API 测试需要本地运行 Redis 实例
你：我们的日期格式统一用 ISO 8601

Claude 会把这些写入自动记忆。下次会话自动知道。

如果你想保存到 CLAUDE.md 而不是自动记忆，明确说：

你：把这条加到 CLAUDE.md

开启和关闭

自动记忆默认开启。三种方式切换：

方式一：用 /memory 命令切换。 在会话中输入 /memory，用自动记忆开关切换。

方式二：在 settings.json 中配置。

{
  "autoMemoryEnabled": false
}

方式三：环境变量。

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

自定义存储位置

默认存在 ~/.claude/projects/<project>/memory/。想改到别处，在 settings.json 中设置：

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

值必须是绝对路径或以 ~/ 开头。

/memory 命令

/memory 是管理记忆系统的核心命令。在会话中输入后可以：

• 查看当前加载的所有 CLAUDE.md、CLAUDE.local.md 和规则文件
• 切换自动记忆的开关
• 打开自动记忆文件夹
• 选择任意文件在编辑器中打开编辑

当你不确定 Claude 读到了哪些指令时，先跑一下 /memory 看看文件列表。

用 # 键快速记录

在输入框按 # 键，输入你想记住的内容，回车。Claude Code 会自动将其写入对应的 CLAUDE.md 文件。适合快速记录项目约定、常用命令、代码风格细节。

Monorepo 的配置方式

大型 Monorepo 里，可以在仓库根目录放全局 CLAUDE.md，每个子包目录再放各自的：

my-monorepo/
├── CLAUDE.md                  ← 全局规范
├── packages/
│   ├── web/
│   │   └── CLAUDE.md          ← 前端专属
│   ├── api/
│   │   └── CLAUDE.md          ← 后端专属
│   └── shared/
│       └── CLAUDE.md          ← 共享包

Claude 打开某个子包的文件时，会同时加载根目录和该子包的 CLAUDE.md。

如果其他团队的 CLAUDE.md 干扰到你，用 claudeMdExcludes 设置排除：

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

AGENTS.md 兼容

Claude Code 读 CLAUDE.md，不读 AGENTS.md。如果你的仓库已经在用 AGENTS.md（给其他编码工具用的），创建一个导入它的 CLAUDE.md：

@AGENTS.md

## Claude Code

对 `src/billing/` 下的更改使用 Plan Mode。

这样两个工具读相同的指令，不用重复维护。

常见问题排查

Claude 不遵循我的 CLAUDE.md

这是最常见的问题。排查步骤：

1. 运行 /memory 确认文件被加载。如果没列出，Claude 看不到它。
2. 检查文件是否在正确的位置（参考四层作用域表）。
3. 让指令更具体。“使用 2 空格缩进”比”格式化代码”有效得多。
4. 查找跨文件的冲突指令。两个文件给不同指导，Claude 可能随便选一个。

不知道自动记忆保存了什么

运行 /memory，选择自动记忆文件夹，浏览 Claude 保存的内容。都是纯 Markdown，可以读、编辑、删除。

CLAUDE.md 太大了

超过 200 行会消耗更多上下文并降低遵守度。解决方案：

• 用路径范围规则，让指令只在处理匹配文件时加载
• 删掉不是每个会话都需要的内容
• 跑 /doctor 检查可修剪的内容（v2.1.206+），它会删除 Claude 能从代码库推断的内容（目录布局、依赖列表等），保留陷阱、原理和约定

/compact 后指令丢失了

项目根 CLAUDE.md 在压缩中会存活：/compact 之后，Claude 从磁盘重新读取并重新注入。但子目录的嵌套 CLAUDE.md 不会自动重新注入，要等 Claude 下次读取该子目录文件时才重新加载。

如果指令在压缩后消失，说明它要么只在对话中给过，要么在尚未重新加载的嵌套 CLAUDE.md 里。把仅对话的指令加到 CLAUDE.md 里让它持久化。

最佳实践速查

场景	推荐做法
团队共享规范	项目根目录 CLAUDE.md，提交 Git
个人偏好	~/.claude/CLAUDE.md（用户级）
个人项目偏好	CLAUDE.local.md，加入 .gitignore
模块特定规则	.claude/rules/ 下按主题拆分
让 Claude 自学	开启自动记忆，口头告知偏好
临时引用文档	@docs/filename.md 按需引用
必须执行的操作	写成 Hook，不靠 CLAUDE.md

记住一个原则：CLAUDE.md 写项目独有的约定，通用的东西（ESLint 已经定义的代码风格）不要重复声明。保持精简，持续更新，用命令式语言写具体指令。