告别"失忆症"：Claude Code 记忆系统完全指南

海听山歌
0 阅读9分钟

你是否遇到过这种情况：每次打开 Claude Code，它都像第一次认识你一样对你的项目一无所知？你需要反复解释项目背景、代码规范、团队约定……

这不是 Claude 的 Bug，而是它设计上的"遗忘机制" ——为了确保每次对话的独立性和安全性。

但现在，我们可以通过 CLAUDE.md 彻底解决这个问题。

什么是 CLAUDE.md？

CLAUDE.md 是 Claude Code 的"项目入职手册"。

它是一个放在项目根目录的 Markdown 文件，每次启动新对话时，Claude Code 会自动读取这个文件，快速了解项目的背景、规范和特殊需求。

想象一下：

  • 新同事入职，你只需要给他一本手册，他就知道公司的一切
  • CLAUDE.md 就是 Claude 的"入职手册"

有了它，Claude 每次对话都像工作了 3 年的老员工——真正懂你的项目。

AI 的入职手册.png

五层记忆架构：你的 AI 记忆管理系统

Claude Code 的记忆系统分为五个层级，从全局到局部，帮你精准控制 AI 的认知范围：

1️⃣ 企业策略级

组织范围内的通用指令，所有项目都遵循的规则。
位置：

  • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
  • Linux: /etc/claude-code/CLAUDE.md
  • Windows: C:\Program Files\ClaudeCode\CLAUDE.md

示例

# 公司开发策略

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

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

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

2️⃣ 用户级

你个人的全局偏好，如个人代码风格，沟通语言设置，通用工作习惯等。需要注意的是，用户级记忆会被项目级覆盖。如果你个人喜欢 2 空格缩进，但项目要求 4 空格，那就用 4 空格。
位置： ~/.claude/CLAUDE.md
示例

# 个人偏好

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

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

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

3️⃣ 项目级

团队共享的项目规范。
位置：项目根目录的 ./CLAUDE.md
示例

# 项目：订单服务 API

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

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

## API 响应格式
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 - 运行数据库迁移

4️⃣ 本地级

个人工作空间用于记载个人工作笔记，不提交到 Git，适合内容包括本地环境配置、个人调试技巧、当前工作备注，敏感信息（测试账号等）。
位置： 项目根目录的 ./CLAUDE.local.md 。记得把 .CLAUDE.local.md 加入 .gitignore

示例

# 本地开发笔记

## 我的环境
- 本地 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:*"

5️⃣ 规则目录

Rules 是按主题组织的规则文件，支持条件作用域（也就是视情况来确定是否加载该记忆内容），适合场景包括 CLAUDE.md 变得太长时，不同文件类型需要不同规范时，以及前后端分离的项目。
位置： .claude/rules/*.md
目录结构：

.claude/
└── rules/
    ├── typescript.md      # TypeScript 规范
    ├── testing.md         # 测试规范
    ├── api-design.md      # API 设计规范
    └── security.md        # 安全规范

条件作用域示例 .claude/rules/testing.md

---
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字段让这个规则只在编辑测试文件时生效，不会浪费其他场景的上下文空间。

五层架构记忆.png

五层架构记忆.png

编写高效 CLAUDE.md 的四大核心原则

好的 CLAUDE.md 不是越多越好，而是精准到位。

🎯 Less is More

只写必要的、最能影响 Claude 行为的内容。

❌ 不要写成：

本项目使用 React 18，使用 TypeScript，使用 Vite，使用 Tailwind CSS...

✅ 应该写成：

技术栈：React 18 + TypeScript + Vite + Tailwind

📍 具体优于泛泛

越具体的指令，Claude 执行得越准确。

❌ 不要写成：

# 项目规范
## 代码质量
请写出高质量的代码。代码应该是可读的。使用有意义的变量名。
保持代码整洁。遵循最佳实践。不要写重复的代码。

这些话没有一句是错的，但问题在于——Claude 本来就知道这些。它们不会改变 Claude 的任何决策，只会白白占用上下文空间。这些话对人类尚且含糊，对模型来说，更是几乎等于什么都没说。

✅ 应该写成：

# 项目规范

## TypeScript
- 使用 `interface` 定义对象结构，`type` 用于联合类型
- 禁止 `any`，使用 `unknown` + 类型守卫
- 函数参数 > 3 个时，使用对象参数

## 错误处理
```typescript
// 业务错误
throw new BusinessError('ORDER_NOT_FOUND', '订单不存在');

// 验证错误（Zod 自动抛出）
const data = orderSchema.parse(input);

// controller 中不要 try-catch
// 由全局错误中间件统一处理

两者的差异非常明确。后者不是模糊要求“要高质量”，而是给出了如何做才算高质量；不是“注意错误处理”，而是具体的错误模型；不是抽象描述，而是可直接模仿的代码形态。这里有个简单的判断标准——如果你不写，Claude 也大概率会做对，那就不要写。

❓ 关键三问题：WHY / WHAT / HOW

一份真正“能用”的 CLAUDE.md，通常都在回答三个问题。不是一次性回答，而是在关键地方给出明确指引。

每个规则回答这三个问题：

WHY 为什么需要这条规则？（避免踩坑）

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

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

WHAT 具体是什么要求？（明确标准）

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

这一部分的重点是边界。什么是允许的，什么是禁止的，决策应该发生在哪一层？对 Claude 来说，这比“最佳实践”四个字重要得多。

HOW 按什么步骤去做？（可操作性）

## 创建新 API 端点

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

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

当步骤清晰、路径明确、还有参考文件时，Claude 才会稳定复用同一套工作流，而不是每次自由发挥。

📖 渐进式披露

先放最重要的，细节按需添加。

# 项目规范

## 核心
[精简的核心规范]

## 详细文档
- 数据库设计: 见 `docs/database.md`
- API 规范: 见 `docs/api-spec.md`
- 部署流程: 见 `docs/deployment.md`

这样做有两个好处：

  1. CLAUDE.md 保持轻量，启动成本低 。
  2. 当 Claude 需要进一步的细节信息时，可以按需读取引用文件。

实战演练：三分钟上手

场景一：为新项目创建记忆

# CLAUDE.md

# 项目：电商平台前端

## 技术栈
- 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` - 测试

除此之外，最好还创建本地记忆

touch CLAUDE.local.md
echo "CLAUDE.local.md" >> .gitignore

# 本地笔记

## 环境
- API: http://localhost:8080
- Mock: 使用 MSW

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

场景二：优化已有 CLAUDE.md

检查三个问题：

  1. 是否有冗余信息？→ 删除
  2. 是否有模糊表述？→ 改具体
  3. 是否有过期内容？→ 更新

场景三：记忆管理命令

要查看当前记忆，在 Claude Code 中输入：

# 查看当前记忆
/memory

# 编辑记忆的命令参数如下
/memory edit         # 编辑项目级 CLAUDE.md
/memory edit user    # 编辑用户级记忆
/memory edit local   # 编辑本地级记忆

你也可以通过自然语言指令，让 Claude 帮你更新记忆！

你：请记住，我们项目使用 pnpm 而不是 npm

Claude：好的，我可以将这个信息添加到项目的 CLAUDE.md 中。
        要我现在更新吗？

Auto Memory：更智能的自动记忆

除了手动编写 CLAUDE.md，Claude Code 还有一个自动记忆功能。

当你和 Claude 一起完成一些工作后（比如创建了一个组件、定义了一个规则），Claude Code 会自动生成功能记忆，保存到本地。

下次遇到类似场景，它会自动调用这些记忆，真正变成"越用越懂你"的 AI 助手。

总结

能力说明
CLAUDE.md项目入职手册，让 Claude 快速了解项目
五层记忆企业→用户→项目→本地→Rules
四大原则精简、具体、三问、渐进
Auto Memory自动生成功能记忆

好的 CLAUDE.md，是对 AI 最好的投资。

它让 Claude 从"每次都要解释"变成"天然就懂你"，省下的时间才是真正的效率飞升。

如果你觉得这篇文章对你有帮助的话，也希望可以关注我的微信公众号：图解前端。 一起交流技术，获取更多技术干货～

543528bd302386e823063d0012d0e348.jpg

avatar
文章
阅读
粉丝