CLAUDE.md 记忆系统深潜：让 Claude 跨会话记住你的规矩

如果每次新对话，Claude 都让你从零开始——不记得你用什么技术栈、不记得你的代码风格、不记得团队规范——那这种"失忆症"会让人抓狂。CLAUDE.md 就是治疗这种失忆症的药。

为什么需要记忆系统

我们和 Claude 的协作，理想状态应该像加入一个熟悉你项目的老同事——他知道你用什么 ORM，清楚团队的 commit 规范，知道哪个目录不能动。但默认情况下，Claude 每次启动都是"失忆"的：没有项目背景、没有团队规则、没有历史经验。

CLAUDE.md 解决的就是这个问题。每次 Claude Code 启动对话时，会自动扫描并加载这些记忆文件，把里面的约束、偏好、规范当作"必须遵守的宪法"。

CLAUDE.md 的工作原理

整个流程只有四步：启动 → 扫描 → 加载 → 工作。但关键细节全在第二步——它会按层级顺序扫描五类文件，把所有匹配的内容全部注入到当前对话的上下文中。

一个常被忽略的事实是：CLAUDE.md 的每一行，每一轮对话都会重新占用 token。冗余不是无害的，而是持续消耗的。所以这份文件的写作原则不是"写得越多越好"，而是"写得越精越好"。

五层记忆架构

CLAUDE.md 不是单文件，而是一种分层叠加的上下文注入架构。从高层到底层依次加载，低层文件在前一层基础上叠加：

各级职责速查表

层级	路径	部署方式	是否提交 Git
Level 0 企业策略	`/etc/claude-code/CLAUDE.md` (Linux) `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows)	MDM / Group Policy / Ansible	❌
Level 1 用户级	`~/.claude/CLAUDE.md`	个人维护	❌
Level 2 项目级	`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	团队共同维护	✅
Level 3 项目规则	`./.claude/rules/*.md`	团队共同维护	✅
Level 4 本地级	`./CLAUDE.local.md`	个人维护	❌（加入 .gitignore）

Level 0：企业策略级

由 IT/DevOps 统一部署到所有开发者机器上。适合放公司级强制规范：

markdown

# 公司开发策略
## 安全要求
- 禁止在代码中硬编码任何密钥或敏感信息
- 所有 API 调用必须使用 HTTPS
- 用户输入必须经过验证和清理

## 合规要求
- 所有日志必须排除 PII（个人身份信息）
- 数据库连接必须使用加密传输

## 禁止项
- 禁止使用未经审批的第三方库
- 禁止直接访问生产数据库

组织内所有机器的内容完全一致，由配置管理系统统一推送，避免人为遗漏。

Level 1：用户级——个人跨项目偏好

承载跨所有项目生效的个人偏好。比如沟通语言、通用代码风格、个人常用工具：

markdown

# 个人偏好
## 沟通方式
- 使用中文回复
- 代码注释使用英文
- 解释简洁直接，不要过多铺垫

## 通用代码风格
- 缩进使用 2 空格
- 优先使用 async/await
- 变量命名使用 camelCase
- 常量命名使用 UPPER_SNAKE_CASE

## 我的常用工具
- 包管理器: uv
- 编辑器: VS Code
- 终端: zsh

这类设置跨项目生效，所以不要在这里写"项目特定的规范"——那应该放到 Level 2。

Level 2：项目级——团队共享规范

最适合放团队共识——所有人都应该遵守的约定。这份文件要提交到 Git，让每个团队成员都能享受到相同的环境：

markdown

# 项目：订单服务 API

## 技术栈
- Node.js 20 + TypeScript
- Fastify（Web 框架）
- Prisma（ORM）
- PostgreSQL + Redis
- Zod（数据验证）

## 目录结构
src/
├── routes/         # 路由定义
├── controllers/    # 请求处理
├── services/       # 业务逻辑
├── repositories/   # 数据访问
├── schemas/        # Zod schemas
└── types/          # 类型定义

## API 响应格式
```typescript
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: { code: string; message: string };
}

编码规范

TypeScript strict 模式
禁止使用 any，使用 unknown + 类型守卫
所有 API 端点必须有 Zod schema 验证
业务错误使用自定义 Error 类

常用命令

pnpm dev - 启动开发服务器
pnpm test - 运行测试
pnpm prisma migrate dev - 运行数据库迁移


### Level 3：项目规则——条件作用域（paths）

当 CLAUDE.md 变得很长，或者"不同文件类型需要不同规范"时，把它拆分到 `.claude/rules/` 目录，每个文件用 `paths` 字段声明**只在哪些文件被编辑时加载**：

.claude/ └── rules/ ├── typescript.md # TypeScript 通用规范 ├── testing.md # 测试规范（paths 限定） ├── api-design.md # API 设计规范 └── security.md # 安全规范


**关键特性**：`paths` 字段让规则只在编辑匹配的路径时生效，**不浪费其他场景的上下文空间**。

最经典的案例是测试规范——只有当你编辑测试文件时，下面的规则才会被加载：

```markdown
---
paths:
  - "src/**/*.test.ts"
  - "tests/**/*.ts"
---

# 测试规范

## 命名
- 单元测试: `*.test.ts`
- 集成测试: `*.integration.test.ts`

## 结构
使用 Arrange-Act-Assert 模式：

```typescript
describe('OrderService', () => {
  describe('createOrder', () => {
    it('should create order when stock is available', async () => {
      // Arrange
      const mockProduct = createMockProduct({ stock: 10 });
      // Act
      const order = await orderService.createOrder(mockProduct.id, 1);
      // Assert
      expect(order.status).toBe('created');
    });
  });
});

覆盖率要求

业务逻辑: > 80%
工具函数: > 90%
路由/控制器: 可以较低


当你写普通业务文件时，这段规则完全不会加载；只有当 `paths` 匹配时才会被读取注入。这是一种非常优雅的"按需加载"机制。

### Level 4：本地级——个人工作空间

个人临时工作笔记，**绝不提交 Git**。放本地环境配置、敏感信息、当前任务上下文：

```markdown
# 本地开发笔记
## 我的环境
- 本地 API: http://localhost:3000
- 测试数据库: order_service_dev
- Redis: localhost:6379

## 测试账号
- admin@test.com / test123
- user@test.com / test123

## 当前工作
- 正在重构支付模块
- 参考 PR #234 的讨论
- 周五前完成

## 调试技巧
- 订单状态机日志: LOG_LEVEL=debug pnpm dev
- 查看 Redis 缓存: redis-cli KEYS "order:*"

⚠️ 重要：务必将 CLAUDE.local.md 加入 .gitignore，否则测试账号、调试笔记会暴露给全团队。

gitignore

CLAUDE.local.md

四级作用域的协作流程

五层架构看起来复杂，但实际协作模式很清晰：

Level 0：企业 IT 单向推送，所有人一致
Level 1 / 4：个人维护，不共享
Level 2 / 3：团队共同维护，Git 协作

怎么写好 CLAUDE.md

写 CLAUDE.md 不是把规范全堆进去，而是有明确的判断标准。四大核心原则：

原则 1：Less is More

CLAUDE.md 的每一行都会在每轮对话被注入。这意味着一件事：冗余不是无害的，而是持续消耗的。

判断标准：如果你不写，Claude 也大概率会做对，那就不要写。

原则 2：具体优于泛泛

不要写"做好错误处理"这种模糊要求，而是给出可直接模仿的代码形态：

写法	示例	评价
模糊 ❌	"注意错误处理"	没指导意义
具体 ✅	"统一抛出 BusinessError，包含 code/msg 字段"	可直接复用

原则 3：WHY / WHAT / HOW 关键三问

一份真正"能用"的 CLAUDE.md，通常在关键地方回答三个问题：

WHY——为什么要这样做？

不是让 Claude "记住一个库"，而是让它理解背后的决策逻辑。当 Claude 明白了为什么，在面对相似但不完全相同的场景时，才更可能做出一致的判断：

markdown

## 为什么使用 Zod？
- TypeScript 只有编译时类型检查
- API 输入需要运行时验证
- Zod 可以同时生成 TS 类型和验证逻辑
- 错误信息自动生成，对用户友好

WHAT——具体要做什么，不要做什么？

重点是边界：什么是允许的，什么是禁止的，决策应该发生在哪一层：

markdown

## 数据库操作规范
- 所有查询通过 Prisma ORM
- 复杂查询封装在 `src/repositories/`
- 禁止在 controller/service 中直接写 SQL
- 事务使用 `prisma.$transaction()`

HOW——按什么步骤去做？

当步骤清晰、路径明确、还有参考文件时，Claude 才会稳定复用同一套工作流：

markdown

## 创建新 API 端点
1. 在 `src/schemas/` 创建请求/响应 Zod schema
2. 在 `src/routes/` 添加路由定义
3. 在 `src/controllers/` 实现请求处理
4. 在 `src/services/` 实现业务逻辑
5. 在 `tests/` 添加测试用例

示例参考: `src/routes/orders.ts`

原则 4：渐进式披露

CLAUDE.md 的职责是定义默认决策，而不是承载全部知识。对于非核心但可能被用到的内容，正确做法是引用而不是复制：

markdown

# 项目规范
## 核心
[精简的核心规范]
## 详细文档
- 数据库设计: 见 `docs/database.md`
- API 规范: 见 `docs/api-spec.md`
- 部署流程: 见 `docs/deployment.md`

好处很明显：CLAUDE.md 保持轻量，启动成本低；当 Claude 需要进一步细节时，可以按需读取引用文件。

从零开始的初始化演练

以一个电商平台前端项目为例，走一遍 CLAUDE.md 初始化流程。

Step 1：创建项目级 CLAUDE.md

markdown

# 项目：电商平台前端

## 技术栈
- React 18 + TypeScript
- Vite 构建
- TanStack Query（数据获取）
- Zustand（状态管理）
- Tailwind CSS

## 目录结构
src/
├── components/      # 组件
│   ├── ui/         # 基础 UI
│   └── features/   # 功能组件
├── pages/          # 页面
├── hooks/          # 自定义 Hooks
├── stores/         # Zustand stores
├── api/            # API 调用
└── types/          # 类型定义

## 组件规范
- 函数组件 + Hooks
- Props 接口命名: `XxxProps`
- 一个组件一个目录: `Button/index.tsx`

## 状态管理
- 服务端状态: TanStack Query
- 客户端状态: Zustand
- 本地状态: useState

## 常用命令
- `pnpm dev` - 开发服务器
- `pnpm build` - 构建
- `pnpm test` - 测试

Step 2：创建本地记忆

markdown

# 本地笔记
## 环境
- API: http://localhost:8080
- Mock: 使用 MSW

## 当前任务
- 重构购物车组件
- 截止: 本周五

Step 3：添加条件规则（可选）

对于测试规范，可以拆到 .claude/rules/testing.md，只在编辑测试文件时加载：

markdown

---
paths:
  - "src/**/*.test.tsx"
  - "src/**/*.test.ts"
---

# 测试规范
- 使用 Vitest + React Testing Library
- 测试文件放在同目录: `Button.test.tsx`
- 优先测试用户行为，而非实现细节

```typescript
// ✅好
expect(screen.getByRole('button')).toBeEnabled();
// ❌不好
expect(component.state.isLoading).toBe(false);

优化已有的 CLAUDE.md

如果你已经有一份 CLAUDE.md 跑了一段时间，发现 Claude 行为越来越迟钝，可以按三步走优化：

Step 1：识别核心内容

问自己一个问题：哪些内容是每次对话都需要的？ 把"每次都需要"和"偶尔需要"分开。

Step 2：拆分文件

详细的 API 文档、数据库表结构、部署流程虽然重要，但完全没必要每次都读入 Claude 内存。可以移动到单独文件，精简原文件：

markdown

## 核心规范
[精简内容]

## 详细参考
- API 端点清单: @docs/api.md
- 数据库 Schema: @prisma/schema.prisma
- 部署配置: @docs/deploy.md

注意 @docs/api.md 这种引用语法——Claude 会按需读取，不会注入到默认上下文。

Step 3：使用条件规则

把测试规范、前端规范、后端规范拆分到 .claude/rules/，并设置 paths 条件。例如：

frontend.md → paths: ["src/components/**", "src/pages/**"]
backend.md → paths: ["src/services/**", "src/repositories/**"]
testing.md → paths: ["**/*.test.ts", "**/*.test.tsx"]

这样每个规则只在最相关的场景下被激活，避免规则互相干扰。

记忆管理命令

Claude Code 内置了记忆管理命令，在交互界面输入即可使用：

命令	作用
`/memory`	查看当前生效的所有记忆文件
`/memory edit`	编辑项目级 CLAUDE.md
`/memory edit user`	编辑用户级记忆
`/memory edit local`	编辑本地级记忆

最典型的使用方式是和 Claude 对话式添加：

你：请记住，我们项目使用 pnpm 而不是 npm
Claude：好的，我可以将这个信息添加到项目的 CLAUDE.md 中。要我现在更新吗？

这种"对话式配置"的体验，比手动编辑文件自然得多。

Auto Memory：自动沉淀的经验笔记

CLAUDE.md 并非 Claude 唯一的记忆来源。Claude Code 还拥有 Auto Memory 机制：

随着项目演进和对话深入，Claude 会在 ~/.claude/projects/<project>/memory/ 目录下自动生成 Auto Memory，记录模型在项目中学习到的模式、调试经验和结构认知。

CLAUDE.md 和 Auto Memory 是两种完全不同的记忆来源：

维度	CLAUDE.md	Auto Memory
来源	人为编写	模型自动沉淀
内容性质	显性规则、规范、约定	隐性经验、模式识别、调试技巧
写入时机	你主动添加	Claude 在合适时自动写入
决定什么	"系统被告知什么"	"系统在实践中学到了什么"
存放路径	项目根目录或用户主目录	`~/.claude/projects/<project>/memory/`
适用场景	团队规范、必须遵守的硬约束	个人经验、可参考的最佳实践

一个简单的判断标准：CLAUDE.md 写"必须遵守的"，Auto Memory 学"这样做事更好的"。

常见陷阱

错误做法	后果	正确做法
在 CLAUDE.md 堆 200 行 ESLint 规则	上下文一直都被这些规则占据，挤占任务相关 token	引用 `@.eslintrc.json`，让 Claude 按需查阅
模糊规则"做好单元测试"	每个测试 Claude 都按自己的理解写，结果飘忽不定	提供具体的 Arrange-Act-Assert 模板和反例
CLAUDE.md 和 Auto Memory 混淆	个人经验泄漏到团队项目，影响其他成员	团队规范只放 CLAUDE.md，个人经验交给 Auto Memory
用 `/memory edit local` 写团队规范	local 文件不上传 Git，团队成员根本看不到	团队规范用 `/memory edit`，写项目级
paths 写得过宽	规则在所有场景都被加载，没有达到省上下文的目的	精确匹配路径：`src/*/.test.ts` 而非 `*/`
企业策略放项目 CLAUDE.md	项目约束和公司约束混在一起，难维护	Level 0 给 IT，Level 2 给项目负责人

记忆系统的关键不在于写得多，而在于对的内容放在对的层级。

局限性声明

CLAUDE.md 不是银弹。有几个边界必须诚实指出：

token 成本：无论精简与否，CLAUDE.md 都会占用每次对话的固定 token。超大对话场景下仍然是开销。
无法保证行为：规则只是"prompt 级约束"，Claude 不会因为 CLAUDE.md 写明就 100% 遵守。需要配套的自动化检查（Hook、CI）。
冲突处理：当 Level 0 企业策略和 Level 2 项目规则冲突时，行为依赖模型判断，无法用工具强制优先级。
版本漂移：CLAUDE.md 更新后，旧对话中 Claude 已经"学到"的行为不会同步更新。

核心要点回顾

CLAUDE.md 是一种多层叠加的记忆架构：

五层架构：企业策略 → 用户偏好 → 项目规范 → 项目规则 → 本地工作
四级作用域：Level 1~4，分别对应个人 / 项目 / 团队的协作边界
paths 条件作用域：让规则只在匹配的路径下激活，按需加载节省上下文
四大写作原则：Less is More / 具体优于泛泛 / WHY-WHAT-HOW / 渐进式披露
CLAUDE.md vs Auto Memory：显性规则 vs 隐性经验，两种记忆机制分工协作

一个好的 CLAUDE.md 不是"全部文档的搬运"，而是"每次对话都必读的最简决策集合"。

CLAUDE.md 记忆系统深潜：让 Claude 跨会话记住你的规矩 ​

为什么需要记忆系统 ​

CLAUDE.md 的工作原理 ​

五层记忆架构 ​

各级职责速查表 ​

Level 0：企业策略级 ​

Level 1：用户级——个人跨项目偏好 ​

Level 2：项目级——团队共享规范 ​

编码规范 ​

常用命令 ​

覆盖率要求 ​

四级作用域的协作流程 ​

怎么写好 CLAUDE.md ​

原则 1：Less is More ​

原则 2：具体优于泛泛 ​

原则 3：WHY / WHAT / HOW 关键三问 ​

WHY——为什么要这样做？ ​

WHAT——具体要做什么，不要做什么？ ​

HOW——按什么步骤去做？ ​

原则 4：渐进式披露 ​

从零开始的初始化演练 ​

Step 1：创建项目级 CLAUDE.md ​

Step 2：创建本地记忆 ​

Step 3：添加条件规则（可选） ​

优化已有的 CLAUDE.md ​

Step 1：识别核心内容 ​

Step 2：拆分文件 ​

Step 3：使用条件规则 ​

记忆管理命令 ​

Auto Memory：自动沉淀的经验笔记 ​

常见陷阱 ​

局限性声明 ​

核心要点回顾 ​

延伸阅读 ​

CLAUDE.md 记忆系统深潜：让 Claude 跨会话记住你的规矩

为什么需要记忆系统

CLAUDE.md 的工作原理

五层记忆架构

各级职责速查表

Level 0：企业策略级

Level 1：用户级——个人跨项目偏好

Level 2：项目级——团队共享规范

编码规范

常用命令

覆盖率要求

四级作用域的协作流程

怎么写好 CLAUDE.md

原则 1：Less is More

原则 2：具体优于泛泛

原则 3：WHY / WHAT / HOW 关键三问

WHY——为什么要这样做？

WHAT——具体要做什么，不要做什么？

HOW——按什么步骤去做？

原则 4：渐进式披露

从零开始的初始化演练

Step 1：创建项目级 CLAUDE.md

Step 2：创建本地记忆

Step 3：添加条件规则（可选）

优化已有的 CLAUDE.md

Step 1：识别核心内容

Step 2：拆分文件

Step 3：使用条件规则

记忆管理命令

Auto Memory：自动沉淀的经验笔记

常见陷阱

局限性声明

核心要点回顾

延伸阅读