CLAUDE.md 记忆系统

The CLAUDE.md Memory System

CLAUDE.md 是 Claude Code 的持久化记忆机制。它让 Claude 在每次新对话开始时自动加载项目相关的背景知识，无需你重复说明。

三层记忆层级

Three-Tier Memory Hierarchy

CLAUDE.md 采用三层层级结构，从全局到局部逐步细化。

层级概览

优先级（从高到低）:

┌─────────────────────────────────────────┐
│  本地级 .claude/CLAUDE.md               │  ← 最高优先级
│  仅限本地，不提交到 Git                   │
├─────────────────────────────────────────┤
│  项目级 ./CLAUDE.md                     │  ← 中等优先级
│  项目根目录，团队共享                     │
├─────────────────────────────────────────┤
│  用户级 ~/.claude/CLAUDE.md             │  ← 最低优先级
│  全局配置，所有项目共享                   │
└─────────────────────────────────────────┘

用户级：~/.claude/CLAUDE.md

User-Level Memory

用户级 CLAUDE.md 位于你的 home 目录下，适用于所有项目的通用偏好。

markdown

# 个人偏好

- 我偏好 TypeScript 而非 JavaScript
- 使用函数式编程风格，避免使用 class
- 代码注释使用中文
- 生成提交信息时使用英文
- 缩进使用 2 个空格
- 使用单引号而非双引号

适合放在用户级的内容：

内容类型	示例
语言偏好	中文注释、英文提交信息
编码风格	缩进、引号、命名规范
工具偏好	偏好 pnpm 而非 npm
通用习惯	先写测试再写实现

项目级：./CLAUDE.md

Project-Level Memory

项目级 CLAUDE.md 位于项目根目录，应该提交到 Git，供团队所有成员共享。

markdown

# 项目：电商平台 API

## 技术栈
- Runtime: Node.js 20
- Framework: Express.js + TypeScript
- Database: PostgreSQL 15 + Prisma ORM
- Cache: Redis 7
- Queue: Bull MQ
- Testing: Vitest + Supertest

## 项目结构
- src/routes/ - API 路由定义
- src/services/ - 业务逻辑层
- src/models/ - Prisma 模型
- src/middleware/ - Express 中间件
- src/utils/ - 工具函数

## 常用命令
- `pnpm dev` - 启动开发服务器
- `pnpm test` - 运行全部测试
- `pnpm test:watch` - 监听模式测试
- `pnpm db:migrate` - 运行数据库迁移
- `pnpm db:seed` - 填充测试数据
- `pnpm lint` - 运行 ESLint
- `pnpm build` - 构建生产版本

## 编码规范
- 所有 API 路由使用 RESTful 风格
- 错误处理统一使用 AppError 类
- 数据库查询放在 service 层，不要在 route 中直接查询
- 所有公开 API 必须有请求体验证（使用 Zod）
- 日志使用 Winston，不要使用 console.log

## 注意事项
- 不要修改 src/generated/ 目录下的文件，它们由 Prisma 自动生成
- 环境变量在 .env.example 中有模板
- CI 流水线要求所有测试通过且无 lint 错误

本地级：.claude/CLAUDE.md

Local-Level Memory

本地级 CLAUDE.md 位于 .claude/ 目录下，通常被 .gitignore 排除，适合存放个人的、不宜共享的信息。

markdown

# 本地开发备注

## 本地环境
- 数据库运行在 Docker 中: localhost:5433
- Redis 端口: 6380（与其他项目冲突所以改了端口）
- API 密钥在 1Password 的 "Dev Keys" 保险库中

## 当前工作
- 正在重构支付模块，参考 JIRA-1234
- auth.ts 中的 TODO 是我故意留的，暂时不要改

## 个人提醒
- 提交前记得运行 pnpm test:payment
- staging 环境的 API 地址: https://staging-api.example.com

优先级规则

Priority Rules

当多层 CLAUDE.md 中存在冲突的指令时，优先级规则为：

本地级 > 项目级 > 用户级

优先级示例

markdown

# 用户级 ~/.claude/CLAUDE.md
使用 npm 作为包管理器

# 项目级 ./CLAUDE.md
使用 pnpm 作为包管理器

# 结果：Claude 使用 pnpm（项目级覆盖用户级）

markdown

# 项目级 ./CLAUDE.md
测试框架使用 Jest

# 本地级 .claude/CLAUDE.md
测试框架使用 Vitest（我们正在迁移中）

# 结果：Claude 使用 Vitest（本地级覆盖项目级）

优先级对比表

场景	用户级	项目级	本地级	最终生效
包管理器	npm	pnpm	-	pnpm
测试框架	-	Jest	Vitest	Vitest
缩进风格	2 空格	4 空格	-	4 空格
语言偏好	中文	-	英文	英文

/init 命令自动生成

Auto-Generation with /init

/init 命令会自动分析项目结构并生成一个合适的 CLAUDE.md 文件。

使用方法

bash

> /init
正在分析项目...
检测到:
  - 语言: TypeScript
  - 框架: Next.js 14
  - 包管理器: pnpm
  - 测试: Vitest
  - 代码规范: ESLint + Prettier

已创建 CLAUDE.md，包含项目基本信息。
请查看并根据需要补充信息。

/init 生成的内容

/init 自动检测并写入以下信息：

检测内容	来源
项目名称	package.json / 目录名
技术栈	package.json 依赖
构建命令	package.json scripts
目录结构	文件系统扫描
代码规范	.eslintrc / .prettierrc
Git 配置	.gitignore / .gitattributes
框架约定	框架特定文件检测

初始化后的建议

bash

# 1. 生成 CLAUDE.md
> /init

# 2. 查看并编辑
> /memory

# 3. 补充以下内容:
#    - 团队编码规范
#    - 特殊的架构决策
#    - 常见陷阱和注意事项
#    - PR 审查标准

CLAUDE.md 内容建议

Recommended Content

必写内容

markdown

## 技术栈
[框架、语言版本、主要依赖]

## 常用命令
[构建、测试、部署命令]

## 项目结构
[关键目录和文件的说明]

## 编码规范
[命名、格式、架构约定]

建议补充的内容

markdown

## 架构决策
- 为什么选择 X 而不是 Y
- 关键设计模式和原因

## 避免事项
- 不要直接修改 generated/ 目录
- 不要在组件中使用内联样式
- 不要使用 any 类型

## 常见问题
- 如果遇到 X 错误，运行 Y 命令
- 某个 API 有已知的限制

## 发布流程
- 版本号规则
- 分支策略
- CI/CD 流程

写作风格建议

建议	原因
使用简洁的要点格式	减少 token 消耗
避免冗长的解释	Claude 只需关键信息
包含具体命令	Claude 可以直接执行
标注"不要做"的事	防止常见错误
保持更新	过时信息会误导 Claude

特殊指令

Special Directives

CLAUDE.md 中可以使用一些对 Claude 行为有特殊影响的指令。

行为约束

markdown

# 在 CLAUDE.md 中

## 规则
- 修改任何文件前，先运行相关的测试
- 不要删除任何现有的注释
- 新增函数必须包含 JSDoc 注释
- 提交信息格式: type(scope): description
- 不要使用 force push

文件保护

markdown

## 不要修改的文件
- src/generated/**  （自动生成的文件）
- prisma/migrations/**  （数据库迁移记录）
- package-lock.json  （使用 npm install 管理）
- .env*  （环境变量文件）

工作流指令

markdown

## 开发流程
1. 修改代码前先创建新的 Git 分支
2. 每次修改后运行 `pnpm test` 确保测试通过
3. 提交前运行 `pnpm lint:fix` 修复格式问题
4. PR 描述中包含变更摘要和测试说明

条件指令

markdown

## 条件规则
- 如果修改了 API 路由，同时更新 OpenAPI 文档
- 如果新增了组件，同时创建对应的测试文件
- 如果修改了数据库 schema，提醒我需要创建迁移

与其他工具的对比

Comparison with Other Tools

CLAUDE.md vs Cursor Rules

特性	CLAUDE.md	.cursorrules
所属工具	Claude Code	Cursor
文件位置	多层级	项目根目录
层级系统	三层（用户/项目/本地）	单层
自动生成	`/init` 命令	手动创建
团队共享	项目级可共享	可共享
格式	Markdown	纯文本/Markdown
动态编辑	`/memory` 命令	手动编辑文件

CLAUDE.md vs .github/copilot-instructions.md

特性	CLAUDE.md	copilot-instructions.md
所属工具	Claude Code	GitHub Copilot
作用范围	CLI + VS Code 扩展	GitHub Copilot Chat
层级支持	三层	单层（仓库级）
内容格式	Markdown	Markdown
自动加载	每次对话开始时	Copilot Chat 中
适用场景	完整开发环境	代码补全和聊天

通用建议

如果你同时使用多个 AI 编码工具，可以：

bash

# 创建一个共享的基础配置
cat > .ai-instructions.md << 'EOF'
# 项目开发规范
[通用规范内容]
EOF

# 在 CLAUDE.md 中引用
echo "参考 .ai-instructions.md 中的通用规范" >> CLAUDE.md

# 在 .cursorrules 中也引用
echo "参考 .ai-instructions.md 中的通用规范" >> .cursorrules

完整示例

Complete Example

以下是一个真实项目的完整 CLAUDE.md 示例：

markdown

# SaaS Dashboard API

## 概述
这是一个多租户 SaaS 管理后台的后端 API 服务。

## 技术栈
- **Runtime**: Node.js 20 LTS
- **Language**: TypeScript 5.3 (strict mode)
- **Framework**: Fastify 4
- **Database**: PostgreSQL 16 + Drizzle ORM
- **Cache**: Redis 7 (ioredis)
- **Auth**: JWT + Refresh Token
- **Validation**: Zod
- **Testing**: Vitest + @faker-js/faker
- **API Docs**: Swagger/OpenAPI 3.1

## 项目结构
```text
src/
├── modules/           # 按业务模块组织
│   ├── auth/          # 认证模块
│   ├── users/         # 用户管理
│   ├── tenants/       # 租户管理
│   ├── billing/       # 计费模块
│   └── reports/       # 报表模块
├── shared/            # 共享代码
│   ├── database/      # 数据库配置和工具
│   ├── middleware/     # Fastify 插件和中间件
│   ├── errors/        # 统一错误定义
│   └── utils/         # 工具函数
├── generated/         # 自动生成（不要手动修改）
└── scripts/           # 运维和部署脚本

常用命令

pnpm dev - 启动开发服务器 (port 3000)
pnpm test - 运行测试
pnpm test -- --grep "auth" - 运行特定测试
pnpm db:generate - 生成 Drizzle 类型
pnpm db:migrate - 执行数据库迁移
pnpm db:studio - 打开 Drizzle Studio
pnpm lint - ESLint 检查
pnpm typecheck - TypeScript 类型检查

编码规范

每个模块包含: routes.ts, service.ts, schema.ts, types.ts
路由只负责 HTTP 层，业务逻辑放在 service 中
使用 Zod schema 进行请求/响应验证
错误使用 AppError 类抛出，统一在错误处理中间件捕获
数据库查询使用 Drizzle 的 query builder，避免原始 SQL
所有金额使用 bigint 存储（单位：分）
日期时间统一使用 UTC

多租户注意事项

所有数据表都有 tenant_id 字段
查询时必须包含 tenant_id 过滤条件
使用 withTenant(tenantId) 中间件自动注入
超级管理员 API 在 /admin/ 路径下，需要特殊权限

避免事项

不要修改 src/generated/ 下的文件
不要在 service 中直接访问 request/reply 对象
不要使用 any 类型，使用 unknown + 类型守卫
不要在代码中硬编码配置值，使用 env 模块
不要直接 console.log，使用 fastify.log

Git 规范

分支: feature/xxx, fix/xxx, refactor/xxx
提交: feat(module): description / fix(module): description
PR 必须包含测试，覆盖率不低于 80%


---

## 维护 CLAUDE.md 的最佳实践

*Best Practices for Maintaining CLAUDE.md*

### 定期更新

```bash
# 在每次大的技术变更后更新 CLAUDE.md
> /memory
# 添加新的框架版本、废弃的 API 等信息

团队协作

bash

# 将项目级 CLAUDE.md 纳入代码审查
# 在 PR 中包含 CLAUDE.md 的更新
git add CLAUDE.md
git commit -m "docs: update CLAUDE.md with new API patterns"

避免的做法

避免	原因	替代做法
放入完整的代码示例	消耗大量 token	指向文件路径
重复 README 内容	信息冗余	引用 README
放入敏感信息	安全风险	使用本地级
过于详细的说明	Claude 不需要	简洁的要点
长期不更新	误导 Claude	定期审查更新

小结

Summary

CLAUDE.md 是 Claude Code 最重要的配置文件之一。通过合理利用三层层级结构，你可以：

在用户级设置个人偏好和通用习惯
在项目级记录团队共享的规范和知识
在本地级保存个人的临时备注和环境信息

关键要点：

使用 /init 快速开始
保持简洁、聚焦关键信息
定期更新以反映项目变化
利用优先级机制灵活覆盖配置

CLAUDE.md 记忆系统 ​

三层记忆层级 ​

层级概览 ​

用户级：~/.claude/CLAUDE.md ​

项目级：./CLAUDE.md ​

本地级：.claude/CLAUDE.md ​

优先级规则 ​

优先级示例 ​

优先级对比表 ​

/init 命令自动生成 ​

使用方法 ​

/init 生成的内容 ​

初始化后的建议 ​

CLAUDE.md 内容建议 ​

必写内容 ​

建议补充的内容 ​

写作风格建议 ​

特殊指令 ​

行为约束 ​

文件保护 ​

工作流指令 ​

条件指令 ​

与其他工具的对比 ​

CLAUDE.md vs Cursor Rules ​

CLAUDE.md vs .github/copilot-instructions.md ​

通用建议 ​

完整示例 ​

常用命令 ​

编码规范 ​

多租户注意事项 ​

避免事项 ​

Git 规范 ​

团队协作 ​

避免的做法 ​

小结 ​

CLAUDE.md 记忆系统

三层记忆层级

层级概览

用户级：~/.claude/CLAUDE.md

项目级：./CLAUDE.md

本地级：.claude/CLAUDE.md

优先级规则

优先级示例

优先级对比表

/init 命令自动生成

使用方法

/init 生成的内容

初始化后的建议

CLAUDE.md 内容建议

必写内容

建议补充的内容

写作风格建议

特殊指令

行为约束

文件保护

工作流指令

条件指令

与其他工具的对比

CLAUDE.md vs Cursor Rules

CLAUDE.md vs .github/copilot-instructions.md

通用建议

完整示例

常用命令

编码规范

多租户注意事项

避免事项

Git 规范

团队协作

避免的做法

小结