Claude Code Memory 配置指南

官方文档：https://code.claude.com/docs/en/memory

目录

1. Memory 类型总览
2. 加载机制
3. CLAUDE.md Import 语法
4. .claude/rules/ 路径规则
5. Auto Memory
6. 实战案例一：TypeScript 全栈项目
7. 实战案例二：PHP Hyperf 中型项目
8. 最佳实践总结

一、Memory 类型总览

Claude Code 有 6 种 memory 位置，优先级从低到高（越具体优先级越高）：

二、加载机制

项目根目录启动 Claude Code
        ↓
立即加载：当前目录及所有父目录的 CLAUDE.md（向上递归到根目录）
立即加载：.claude/rules/*.md（所有规则文件）
立即加载：~/.claude/CLAUDE.md（用户 memory）
        ↓
按需加载：子目录的 CLAUDE.md（当 Claude 读取该子目录文件时才加载）
按需加载：auto memory 的 topic 文件（如 debugging.md）

官方原文

子目录 CLAUDE.md 按需加载（来源：https://code.claude.com/docs/en/memory）：

"CLAUDE.md files in the directory hierarchy above the working directory are loaded in full at launch. CLAUDE.md files in child directories load on demand when Claude reads files in those directories."

"Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees."

.claude/rules/ 启动时全量加载：

"All .md files in .claude/rules/ are automatically loaded as project memory"

带 paths 的规则文件——加载全量，生效按条件：

"These conditional rules only apply when Claude is working with files matching the specified patterns."

即：rules/ 所有文件启动时都进入 context，但带 paths 的规则只在操作匹配文件时才被应用。

三、CLAUDE.md Import 语法

CLAUDE.md 支持用 @路径 引入其他文件，最大嵌套 5 层：

markdown
复制
# 项目说明
参考 @README.md 了解项目背景，参考 @package.json 了解可用命令。

# 规范
- API 规范见 @docs/api-conventions.md
- Git 工作流见 @docs/git-workflow.md

• 支持相对路径（相对于当前 CLAUDE.md 所在目录）和绝对路径
• 代码块和行内代码中的 @路径 不会被解析
• 首次遇到外部 import 时会弹出确认对话框，确认后永久生效

四、.claude/rules/ 路径规则（核心特性）

.claude/rules/ 中每个 .md 文件可加 YAML frontmatter，指定只在操作特定文件时才激活：

markdown
复制
---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.tsx"
---

# API 层规则
（只有在读写 src/api/ 下的文件时，这段规则才会生效）

不加 paths 的规则文件始终生效，等同于写在根 CLAUDE.md。

支持的 glob 语法

目录结构建议

.claude/rules/
├── architecture.md    ← 无 paths，架构规则始终加载
├── before-coding.md   ← 无 paths，编码规范始终加载
├── api.md             ← 有 paths，只针对 API 层文件
├── frontend.md        ← 有 paths，只针对前端文件
└── database.md        ← 有 paths，只针对数据库相关文件

五、Auto Memory

Claude 在工作过程中自动写入的记忆，无需手动维护：

~/.claude/projects/<git-repo-name>/memory/
├── MEMORY.md        ← 索引文件，每次启动自动加载前 200 行
├── debugging.md     ← Claude 记录的调试经验（按需读取）
├── patterns.md      ← 发现的代码模式（按需读取）
└── ...

• MEMORY.md 前 200 行每次启动自动加载，超出部分不自动加载
• 其他 topic 文件 Claude 按需读取
• 用 /memory 命令手动编辑或查看
• 直接口头告知即可触发记录：「记住我们用 pnpm 不用 npm」

六、实战案例一：TypeScript 全栈项目

技术栈：Next.js 14 + tRPC + Prisma + PostgreSQL

目录结构

my-saas/
├── CLAUDE.md
├── CLAUDE.local.md              ← 个人本地配置（不提交）
├── .claude/
│   └── rules/
│       ├── api.md               ← tRPC 路由规则（带 paths）
│       ├── database.md          ← Prisma 数据库规则（带 paths）
│       ├── frontend.md          ← React 组件规则（带 paths）
│       └── architecture.md     ← 架构规则（无 paths，始终生效）
├── src/
│   ├── app/                     ← Next.js App Router
│   ├── server/
│   │   ├── api/routers/         ← tRPC routers
│   │   └── db.ts
│   ├── components/
│   └── lib/
├── prisma/
│   └── schema.prisma
└── package.json

根目录 CLAUDE.md

markdown
复制
# my-saas 项目

## 技术栈
- Next.js 14 App Router + TypeScript
- tRPC v11（类型安全 API）
- Prisma ORM + PostgreSQL
- Tailwind CSS + shadcn/ui

## 常用命令
- 开发：`pnpm dev`
- 数据库迁移：`pnpm prisma migrate dev --name <描述>`
- 类型检查：`pnpm typecheck`
- 测试：`pnpm test`

## 强制规则
- 包管理器：pnpm（禁止使用 npm/yarn）
- 实现新功能前先搜索 src/lib/ 是否有现成工具函数
- 所有数据库操作必须通过 Prisma，禁止裸写 SQL
- 服务端逻辑放 server/，不允许在 components 中直接查库

## 架构分层
Client Component → tRPC hooks → tRPC router → service → Prisma

.claude/rules/api.md

markdown
复制
---
paths:
  - "src/server/api/**/*.ts"
---

# tRPC API 规则

## 路由结构
- 每个业务域一个 router 文件，在 src/server/api/routers/ 下
- 统一在 src/server/api/root.ts 注册

## 必须遵守
- 所有 mutation 必须鉴权：使用 `protectedProcedure` 不用 `publicProcedure`
- 入参用 zod schema 校验，schema 定义在同文件顶部
- 错误统一抛出 `TRPCError`，不要直接 throw Error

.claude/rules/database.md

markdown
复制
---
paths:
  - "prisma/**/*"
  - "src/server/**/*.ts"
---

# 数据库规则

## Schema 约定
- 表名用 PascalCase 单数（User 不是 users）
- 所有表必须有 id/createdAt/updatedAt 字段
- 软删除用 deletedAt 字段，不要物理删除用户数据

## 查询约定
- 列表查询必须加分页（skip/take），禁止 findMany 不加限制
- 关联查询明确写 include，禁止 N+1 查询
- 事务用 prisma.$transaction()

.claude/rules/frontend.md

markdown
复制
---
paths:
  - "src/app/**/*.tsx"
  - "src/components/**/*.tsx"
---

# 前端组件规则

## 组件分类
- src/components/ui/     → shadcn/ui 基础组件，不要修改
- src/components/        → 业务组件，可复用
- src/app/**/components/ → 页面级私有组件

## 规范
- 优先用 Server Component，只有需要交互/状态才用 'use client'
- 样式只用 Tailwind，禁止内联 style
- 图片必须用 next/image
- 数据获取在 Server Component 中做，不要在客户端 useEffect 里 fetch

## 修改已有组件前
grep src/components/ 确认调用方，评估影响范围再动手

CLAUDE.local.md（个人本地，不提交）

markdown
复制
# 本地开发配置

## 环境
- 本地数据库：postgresql://localhost:5432/myapp_dev
- 测试账号：test@test.com / password123

## 个人偏好
- 代码注释用中文
- 提交信息用英文

七、实战案例二：PHP Hyperf 中型项目

技术栈：Hyperf 3.x + Swoole + MySQL + Redis + RabbitMQ

目录结构

order-service/
├── CLAUDE.md
├── .claude/
│   └── rules/
│       ├── architecture.md      ← 架构分层规则（无 paths，始终生效）
│       ├── before-coding.md     ← 编码前搜索规则（无 paths，始终生效）
│       ├── controller.md        ← 控制器规则（带 paths）
│       ├── service.md           ← 业务服务规则（带 paths）
│       └── async.md             ← 异步/队列规则（带 paths）
├── app/
│   ├── Controller/
│   ├── Service/
│   ├── Repository/
│   ├── Model/
│   ├── Job/
│   ├── Listener/
│   ├── Exception/
│   └── Middleware/
├── config/
└── test/

根目录 CLAUDE.md

markdown
复制
# order-service（订单微服务）

## 技术栈
- Hyperf 3.x + Swoole（协程模式）
- MySQL（主从）+ Redis（缓存/分布式锁）
- RabbitMQ（异步消息）

## 常用命令
- 启动：`php bin/hyperf.php start`
- 代码生成：`php bin/hyperf.php gen:controller OrderController`
- 运行测试：`composer test`

## 协程注意事项
- 禁止使用全局变量存储请求上下文，用 Context::get()/set()
- 数据库连接由连接池自动管理，禁止手动 new PDO
- sleep() 改用 Coroutine::sleep()（非阻塞）

.claude/rules/architecture.md（无 paths）

markdown
复制
# 架构分层规则

## 分层职责
Controller  → 参数校验、调用 Service、返回响应（禁止含业务逻辑）
Service     → 业务逻辑编排、事务控制、调用 Repository
Repository  → 数据库操作封装（禁止含业务判断）
Model       → 字段定义、关联关系（禁止含查询逻辑）

## 禁止的跨层调用
- Controller 禁止直接调用 Repository 或 Model
- Repository 禁止调用 Service
- 跨服务调用通过 RPC 或消息队列，不直接 new 另一个 Service

## 依赖注入
- 所有依赖通过构造函数注入，禁止在方法内 make()

.claude/rules/before-coding.md（无 paths）

markdown
复制
# 编码前强制步骤

## 新增功能
1. grep app/Service/ 确认是否有现成服务方法
2. grep app/Repository/ 确认是否有现成数据访问方法
3. 确认无重复后再新建

## 修改已有方法
1. grep -rn "方法名" app/ 找出所有调用方
2. 评估影响范围：本模块内 / 跨模块 / 对外接口
3. 影响范围大时优先新增方法或加默认参数，禁止直接改签名
4. 禁止静默修改方法的业务语义

.claude/rules/service.md（带 paths）

markdown
复制
---
paths:
  - "app/Service/**/*.php"
---

# Service 规则

## 事务处理
- 涉及多表写操作必须用事务：`Db::transaction(function() { ... })`
- 事务内禁止调用外部 HTTP 或消息队列

## 缓存使用
- 缓存 key 格式：{服务}:{业务}:{id}，如 order:detail:12345
- 通过 CacheService 统一管理，禁止直接操作 Redis

## 异常处理
- 业务异常抛出 BusinessException
- 系统异常不捕获，由全局 ExceptionHandler 处理

.claude/rules/async.md（带 paths）

markdown
复制
---
paths:
  - "app/Job/**/*.php"
  - "app/Listener/**/*.php"
  - "app/Consumer/**/*.php"
---

# 异步任务规则

## 队列任务（Job）
- 每个 Job 只做一件事，保持幂等性（重复执行结果一致）
- 必须实现 handle() 方法
- Job 内禁止直接调用其他 Job（用事件解耦）

## 协程安全
- 共享变量需加锁（RedisLock）
- 禁止在 Job 中使用 static 变量存储状态

八、最佳实践总结

选择结构的判断树

需要记录什么？
├── 整个项目都适用的规则        → 根 CLAUDE.md 或 rules/（无 paths）
├── 特定文件类型的规则           → .claude/rules/xxx.md + paths 配置
├── 某模块内部的约定和知识        → 子目录 CLAUDE.md（按需加载）
├── 方法/函数清单                → 代码注释 @reusable + barrel 文件（代码即文档）
├── 个人本地配置                 → CLAUDE.local.md（不提交）
├── 个人所有项目的习惯            → ~/.claude/CLAUDE.md
└── 让 Claude 自动记录           → 开启 Auto Memory，口头告知即可

三层分工，各司其职

写 CLAUDE.md 的建议

1. 根文件只写导航和强制规则，具体方法清单不写进 md
2. rules/ 文件单一职责，一个文件只覆盖一个主题
3. 用 paths 精确限定作用域，避免无关规则干扰 context
4. 代码注释替代方法清单，代码即文档永不过期
5. 定期用 /memory 命令检查，删除过时规则