# Claude Code记忆体系与上下文管理深度实战
## 概述
本教程面向已掌握 Claude Code 基础操作的开发者，深入讲解 Claude Code 的**记忆持久化体系**和**上下文窗口管理策略**。学完之后，你将能够：设计多层级的 CLAUDE.md 配置架构、利用 rules 目录实现模块化指令分发、掌握 `/memory` 命令的知识管理流程、理解上下文压缩（compaction）的三层机制，以及构建适用于大型项目的长期记忆系统。适用人群：日常使用 Claude Code 超过一周、希望提升多会话协作效率的中高级开发者。
## 前置条件
- 已安装 Claude Code CLI（`npm install -g @anthropic-ai/claude-code`）
- 熟悉 Claude Code 基本操作（对话、文件读写、工具调用）
- 了解 Markdown 基础语法
- 至少有一个正在使用 Claude Code 开发的项目
---
## 第一章：Claude Code 的记忆问题
### 1.1 为什么需要记忆系统
每次启动 Claude Code 会话，模型拿到的是**全新的上下文窗口**——它不记得昨天你让它做了什么，不知道你的团队编码规范，甚至不知道项目用了什么框架。这种"金鱼记忆"带来的问题显而易见：
| 问题场景 | 没有记忆的表现 | 有记忆的表现 |
|---------|-------------|-----------|
| 新会话继续开发 | 需要重新解释项目结构 | 自动加载项目约定 |
| 团队成员协作 | 每人重复配置 | 共享 CLAUDE.md 生效 |
| 跨会话 Bug 修复 | 忘记之前的排查路径 | 记录已知问题和方案 |
| 代码风格一致性 | 每次风格可能不同 | 始终遵循已定义规范 |
Claude Code 提供两套核心机制来解决这个问题：
1. **CLAUDE.md 文件体系** — 项目级别的持久化指令
2. **Memory 文件系统** — 跨会话的结构化知识库
### 1.2 记忆层级全景图
```mermaid
graph TD
A[Claude Code 记忆层级] --> B[全局级 ~/.claude/CLAUDE.md]
A --> C[项目级 项目根目录/CLAUDE.md]
A --> D[项目本地 项目根目录/CLAUDE.local.md]
A --> E[模块级 .claude/rules/*.md]
A --> F[用户记忆 ~/.claude/projects/项目/memory/]
B --> B1[个人偏好
语言/风格/通用规则]
C --> C1[项目约定
架构/框架/编码规范]
D --> D1[个人项目配置
不应提交到 Git]
E --> E1[路径精确匹配
模块化规则文件]
F --> F1[结构化知识
带 frontmatter 的记忆文件]
style B fill:#4a9eff,color:#fff
style C fill:#22c55e,color:#fff
style D fill:#f59e0b,color:#fff
style E fill:#8b5cf6,color:#fff
style F fill:#ef4444,color:#fff
```
每个层级有不同的加载时机和作用范围，理解它们的关系是高效使用 Claude Code 的关键。
---
## 第二章：CLAUDE.md 文件体系详解
### 2.1 全局 CLAUDE.md
**位置**：`~/.claude/CLAUDE.md`
这是你的**个人全局偏好文件**，对所有项目生效。适合放置跨项目通用的指令：
```markdown
# 全局偏好
## 语言与风格
- 默认使用中文回复，代码注释用英文
- 回复简洁明了，避免冗长解释
## 通用规则
- 不要自动 commit，只在明确要求时执行 git commit
- 始终先读取文件再编辑，不要盲目修改
- 优先编辑现有文件而非创建新文件
- 不要提交 secrets、credentials、.env 等敏感文件
## 代码风格
- 使用有意义的变量名
- 函数不超过 50 行
- 添加必要的错误处理
```
**加载时机**：每次启动 Claude Code 会话时自动读取。它是所有记忆层中**最先加载**的。
**最佳实践**：
- 保持精简（建议 50 行以内）
- 只放真正跨项目通用的规则
- 定期清理过时的偏好
### 2.2 项目级 CLAUDE.md
**位置**：项目根目录 `/CLAUDE.md`
这是最重要的记忆文件——它让 Claude Code **理解你的项目**。一个优秀的项目 CLAUDE.md 应包含：
```markdown
# 项目：电商平台后端
## 技术栈
- Node.js 20 + TypeScript 5.3
- Express.js + typeorm
- PostgreSQL 16 + Redis 7
- Jest 单元测试 + Supertest 集成测试
## 项目结构
```
src/
├── controllers/ # 路由处理，调用 service 层
├── services/ # 业务逻辑，不直接操作数据库
├── repositories/ # 数据访问层，封装 typeorm 操作
├── models/ # TypeORM 实体定义
├── middleware/ # 认证、日志、错误处理中间件
├── utils/ # 工具函数，纯函数无副作用
└── types/ # TypeScript 类型定义
```
## 编码规范
- Service 层禁止直接引入 typeorm 的 Repository，必须通过 Repository 层
- 所有 API 响应使用统一格式 `{ code, data, message }`
- 错误处理使用自定义 AppError 类，包含 HTTP 状态码
- 数据库查询使用 QueryBuilder，不写原生 SQL
## 测试要求
- 新功能必须包含单元测试
- API 端点需要集成测试覆盖
- 运行测试命令：`npm test`
- 运行单个测试：`npm test -- --testPathPattern=users`
## Git 规范
- 分支命名：feature/xxx, fix/xxx, refactor/xxx
- Commit message 格式：type(scope): description
- 不允许直接 push 到 main 分支
```
**关键原则**：把 CLAUDE.md 当成**新同事的入职文档**来写。假设一个完全不了解你项目的高级工程师第一天来上班，他需要知道什么，你就写什么。
### 2.3 项目本地 CLAUDE.local.md
**位置**：项目根目录 `/CLAUDE.local.md`
这是**个人专属**的项目配置，**不应该提交到 Git**。确保在 `.gitignore` 中添加：
```gitignore
CLAUDE.local.md
```
典型内容：
```markdown
# 本地开发配置
## 个人偏好
- 我的本地数据库端口是 5433（非默认）
- 调试时喜欢加详细的 console.log
- 我使用 pnpm 而不是 npm
## 临时笔记
- 正在排查 orders 表的慢查询问题
- payment service 的重试逻辑需要重写
- 已和后端团队确认接口变更方案
```
### 2.4 CLAUDE.md 预算系统
CLAUDE.md 的内容会占用上下文窗口的 token 预算。一个**无限膨胀的 CLAUDE.md 反而有害**——它会挤占给代码分析和对话的有效空间。
推荐的 token 预算分配策略：
```mermaid
pie title CLAUDE.md Token 预算建议（总计 ≤ 2000 tokens）
"技术栈与项目结构" : 40
"编码规范" : 30
"测试与部署要求" : 15
"Git 规范与注意事项" : 15
```
**实操建议**：
- 项目级 CLAUDE.md 控制在 **100 行以内**
- 如果内容太多，把详细规范拆到 `docs/` 目录，CLAUDE.md 中只写引用
- 定期审查，删除过时的指令
---
## 第三章：Rules 目录——模块化指令系统
### 3.1 为什么需要 Rules 目录
当项目越来越大，单一的 CLAUDE.md 文件会变成"万能垃圾桶"——前端规则、后端规则、数据库规范、部署流程全部塞在一起。Claude Code 提供了 `.claude/rules/` 目录来解决这个问题。
### 3.2 Rules 目录结构
```
.claude/
├── rules/
│ ├── frontend.md # 前端相关规则
│ ├── backend.md # 后端相关规则
│ ├── database.md # 数据库操作规则
│ ├── testing.md # 测试相关规则
│ ├── security.md # 安全编码规范
│ └── deployment.md # 部署相关规则
├── CLAUDE.md # 项目根指令（仍然保留）
└── settings.json # 项目设置
```
### 3.3 路径精确匹配（Path-Scoped Rules）
Rules 文件最强大的特性是**路径精确匹配**——规则只在编辑特定路径下的文件时生效。通过 YAML frontmatter 实现：
```markdown
---
description: 前端 React 组件开发规范
globs: ["src/components/**", "src/pages/**"]
---
# React 组件开发规范
## 文件命名
- 组件文件使用 PascalCase：`UserProfile.tsx`
- 样式文件同名但后缀为 `.module.css`
- 测试文件命名为 `*.test.tsx`
## 组件结构
- 使用函数组件 + Hooks，不用 class 组件
- 自定义 Hook 以 `use` 前缀命名，放在 `src/hooks/` 目录
- Props 接口定义在组件文件顶部，命名为 `ComponentNameProps`
- 组件默认 export，工具函数 named export
## 状态管理
- 全局状态使用 Zustand
- 局部状态优先使用 useState
- 服务端状态使用 React Query (TanStack Query)
- 禁止在组件内直接调用 fetch，必须通过 api 层
## 样式
- 使用 CSS Modules
- 颜色值使用 CSS 变量引用 `var(--color-xxx)`
- 响应式断点：768px / 1024px / 1440px
```
另一个例子——数据库操作规则：
```markdown
---
description: 数据库操作与迁移规范
globs: ["src/repositories/**", "src/models/**", "migrations/**"]
---
# 数据库规范
## 迁移文件
- 迁移文件名格式：`YYYYMMDDHHMMSS_description.ts`
- 每个迁移必须包含 up 和 down 方法
- 禁止在迁移中使用 ORM 模型，必须使用原始 SQL
## 查询规范
- 所有查询必须使用参数化，禁止字符串拼接
- 分页查询必须包含总数统计
- 批量操作超过 1000 条时使用 batch 处理
- 慢查询（> 500ms）必须添加索引建议注释
## 模型定义
- Entity 字段必须添加注释说明用途
- 关联关系使用 `onDelete` 和 `onUpdate` 明确行为
- 金额字段统一使用 `decimal(19,4)` 类型
```
### 3.4 Rules 文件的加载机制
```mermaid
flowchart LR
A[用户发起请求] --> B{请求涉及哪些文件路径?}
B -->|src/components/| C[加载 frontend.md]
B -->|src/repositories/| D[加载 database.md]
B -->|src/__tests__/| E[加载 testing.md]
B -->|所有路径| F[始终加载 CLAUDE.md]
C --> G[合并所有适用规则到上下文]
D --> G
E --> G
F --> G
G --> H[执行任务]
style F fill:#22c55e,color:#fff
style G fill:#4a9eff,color:#fff
```
**关键细节**：
- `globs` 字段支持 `*`、`**`、`?` 等标准 glob 模式
- 多个 glob 模式用数组表示（OR 关系，匹配任一即生效）
- 没有 `globs` 字段的规则文件会**始终加载**（等同 CLAUDE.md 的效果）
- `description` 字段帮助你在 `/memory` 命令中快速识别每条规则的用途
### 3.5 实战：为真实项目创建 Rules 体系
假设你有一个全栈项目，目录结构如下：
```
my-saas-app/
├── frontend/ # React + TypeScript
├── backend/ # Node.js + Express
├── shared/ # 共享类型和工具
├── infra/ # Terraform 基础设施
├── scripts/ # 运维脚本
└── .claude/
└── rules/
├── frontend-react.md
├── backend-api.md
├── shared-types.md
├── infra-terraform.md
└── scripts-bash.md
```
创建这些规则的完整命令：
```bash
# 创建 rules 目录
mkdir -p .claude/rules
# 创建前端规则
cat > .claude/rules/frontend-react.md << 'EOF'
---
description: React 前端开发规范
globs: ["frontend/**"]
---
# React 开发规范
- 组件使用函数式组件 + TypeScript
- 状态管理使用 Zustand
- API 调用统一通过 frontend/src/api/ 层
- 测试使用 Vitest + Testing Library
- 运行测试: cd frontend && npm test
- 构建: cd frontend && npm run build
EOF
# 创建后端规则
cat > .claude/rules/backend-api.md << 'EOF'
---
description: Node.js 后端 API 开发规范
globs: ["backend/**"]
---
# 后端 API 规范
- 使用 Express + TypeScript
- 路由 → Controller → Service → Repository 四层架构
- 所有 API 响应格式: { code: number, data: T, message: string }
- 错误使用自定义 AppError 类
- 测试: cd backend && npm test
- 数据库迁移: cd backend && npm run migration:run
EOF
# 创建基础设施规则
cat > .claude/rules/infra-terraform.md << 'EOF'
---
description: Terraform 基础设施管理规范
globs: ["infra/**"]
---
# Terraform 规范
- 使用 Terraform 1.6+
- 状态文件存储在 S3 backend
- 变量定义在 terraform.tfvars（不提交）
- 环境区分: dev / staging / prod
- 修改前必须先运行 terraform plan
EOF
```
---
## 第四章：Memory 文件系统——结构化知识库
### 4.1 Memory 与 CLAUDE.md 的区别
| 维度 | CLAUDE.md | Memory 文件 |
|------|----------|------------|
| 创建方式 | 手动编写 | `/memory` 命令或手动创建 |
| 存储位置 | 项目根或 `~/.claude/` | `~/.claude/projects/<项目路径>/memory/` |
| 内容类型 | 项目约定、编码规范 | 事实记录、学习心得、跨会话知识 |
| Git 管理 | 项目级应提交 | 个人专属，不提交 |
| 结构化 | 纯 Markdown | 带 frontmatter 的 Markdown |
### 4.2 `/memory` 命令详解
在 Claude Code 会话中输入 `/memory`，你会看到当前会话加载的所有记忆文件列表：
```
> /memory
📋 Loaded Memory Files:
✅ ~/.claude/CLAUDE.md (global)
✅ ./CLAUDE.md (project)
✅ ./CLAUDE.local.md (project-local)
✅ .claude/rules/frontend-react.md (scoped: frontend/**)
✅ .claude/rules/backend-api.md (scoped: backend/**)
📝 Memory Index: ~/.claude/projects/.../MEMORY.md
- [Vue 迁移注意事项](vue-migration-notes.md)
- [API 限流方案](api-rate-limiting.md)
```
### 4.3 手动创建 Memory 文件
Memory 文件使用带 frontmatter 的 Markdown 格式。每个文件记录一个知识点：
```markdown
---
name: api-rate-limiting
description: API 限流方案设计记录，包含选型理由和最终实现
metadata:
type: reference
created: 2026-05-20
updated: 2026-06-01
---
# API 限流方案
## 背景
用户服务在高峰期出现 503 错误，需要实现限流保护。
## 方案对比
- **Token Bucket**（最终选择）：允许突发流量，适合 API 场景
- Leaky Bucket：流量平滑，不适合突发场景
- Fixed Window：实现简单但有临界问题
## 最终实现
- 使用 Redis + Lua 脚本实现分布式 Token Bucket
- 限流维度：用户 ID + API 路径
- 默认配额：100 req/min（普通用户）/ 1000 req/min（VIP）
- 超限响应：HTTP 429 + Retry-After header
## 相关文件
- `backend/src/middleware/rateLimit.ts` — 核心实现
- `backend/src/config/rateLimitConfig.ts` — 限流配置
## 注意事项
- Lua 脚本必须保证原子性
- Redis 连接池大小影响限流性能
- 测试时注意 mock Redis 时间
[[api-auth-design]] [[redis-patterns]]
```
另一个例子——反馈类型的记忆：
```markdown
---
name: prefer-detailed-error-messages
description: 用户偏好：错误信息需要包含完整上下文
metadata:
type: feedback
---
错误处理代码必须包含完整上下文信息：请求参数、用户 ID、调用链。
**Why:** 多次因为错误信息不足导致排查困难，浪费了团队大量时间。
**How to apply:** 所有 catch 块中的 error message 必须附带上下文对象。使用 `logger.error('message', { context })` 格式。
[[error-handling-standards]]
```
### 4.4 MEMORY.md 索引文件
**位置**：`~/.claude/projects/<项目路径>/memory/MEMORY.md`
这是记忆系统的**索引文件**，每次会话启动时加载到上下文中。格式为每行一条，用 `[[name]]` 语法链接：
```markdown
- [API 限流方案](api-rate-limiting.md) — 分布式限流选型与实现
- [用户认证设计](api-auth-design.md) — JWT + Refresh Token 方案
- [Redis 使用模式](redis-patterns.md) — 项目中 Redis 的标准用法
- [错误处理规范](error-handling-standards.md) — 统一错误处理约定
- [个人编码偏好](prefer-detailed-error-messages.md) — 错误信息需含上下文
```
**关键原则**：
- MEMORY.md 是**索引**，不是内容本身——保持每条一行
- 只列出最重要的记忆，避免索引过长占用 token
- 使用 `[[name]]` 语法建立记忆间的关联
- Claude Code 会在需要时按需读取具体记忆文件
### 4.5 Memory 文件的四种类型
```mermaid
graph TB
A[Memory 文件类型] --> B["👤 user
用户画像"]
A --> C["💬 feedback
反馈与偏好"]
A --> D["📋 project
项目知识"]
A --> E["🔗 reference
外部资源"]
B --> B1["角色、专业领域、
技术栈偏好"]
C --> C1["工作方式纠正、
确认的方法、避免的做法"]
D --> D1["架构决策、技术债、
已知问题、里程碑"]
E --> E1["URL、仪表盘链接、
工单号、外部文档"]
style B fill:#3b82f6,color:#fff
style C fill:#10b981,color:#fff
style D fill:#f59e0b,color:#fff
style E fill:#ef4444,color:#fff
```
### 4.6 实战：构建项目的记忆系统
完整的工作流程：
```bash
# 1. 确认记忆目录存在
ls ~/.claude/projects/*/memory/ 2>/dev/null || echo "目录不存在，Claude Code 会自动创建"
# 2. 在 Claude Code 会话中让 AI 帮你创建记忆
# 输入提示词：
# "记住以下信息：我们团队决定使用 Redis 实现分布式限流，
# 而不是 Nginx 限流，因为需要按用户维度精确控制"
# 3. 验证记忆已创建
# 输入 /memory 命令查看
# 4. 在新会话中验证记忆生效
# 启动新会话，问："我们的限流方案是什么？"
# Claude Code 应该能从记忆中正确回答
```
---
## 第五章：上下文窗口管理
### 5.1 理解上下文窗口
Claude Code 的上下文窗口有一个固定的 token 预算。每次会话中，以下内容都会占用这个预算：
```mermaid
graph LR
A[上下文窗口] --> B[系统提示
~2000 tokens]
A --> C[CLAUDE.md 文件
~500-2000 tokens]
A --> D[Rules 文件
~0-1500 tokens]
A --> E[对话历史
持续增长]
A --> F[工具调用结果
持续增长]
A --> G[Memory 文件
~200-500 tokens]
style E fill:#ef4444,color:#fff
style F fill:#ef4444,color:#fff
```
**核心矛盾**：对话历史和工具调用结果是**持续增长的**，而总预算有限。这就是上下文管理要解决的核心问题。
### 5.2 三层压缩（Compaction）机制
当上下文接近上限时，Claude Code 会自动触发压缩。理解这个过程有助于你写出更高效的指令：
```mermaid
flowchart TD
A[上下文使用率上升] --> B{达到阈值?}
B -->|未达到| C[继续正常对话]
B -->|达到 60%| D[第一层：自动压缩
对话历史摘要]
B -->|达到 80%| E[第二层：激进压缩
丢弃低优先级内容]
B -->|达到 95%| F[第三层：强制重置
清空并重新加载]
D --> G[保留关键指令和最近对话]
E --> H[只保留 CLAUDE.md 和
最近几轮对话]
F --> I[从 CLAUDE.md 重新开始
对话历史全部丢失]
style D fill:#f59e0b,color:#fff
style E fill:#ef4444,color:#fff
style F fill:#7f1d1d,color:#fff
```
**三层压缩的具体行为**：
| 层级 | 触发条件 | 压缩策略 | 对你的影响 |
|------|---------|---------|----------|
| 第一层 | 上下文约 60% | 将较早的对话轮次总结为摘要 | 早期细节可能丢失，但核心指令保留 |
| 第二层 | 上下文约 80% | 丢弃大部分工具调用结果，只保留摘要 | 之前读取的文件内容不再精确可用 |
| 第三层 | 上下文约 95% | 强制清空，只保留 CLAUDE.md 和 Memory | 对话历史完全丢失，等同于新会话 |
### 5.3 手动上下文管理命令
你不必等到自动压缩——Claude Code 提供了多个手动命令：
#### `/compact` — 主动压缩
```
> /compact
```
**效果**：Claude Code 将对话历史总结为简洁摘要，释放上下文空间。关键指令和最近的对话轮次会保留。
**何时使用**：
- 完成一个大任务后，准备开始新任务
- 感觉 Claude Code 开始"忘记"之前的指令
- 长时间对话中间的"中场休息"
#### `/compact` 带自定义指令
```
> /compact 在压缩时请保留关于用户认证模块的所有讨论，因为后面还需要参考
```
**效果**：在压缩时特别保留你指定的内容。
#### `/clear` — 完全清空
```
> /clear
```
**效果**：清空整个对话历史，等同于开启新会话。CLAUDE.md 和 Memory 文件会重新加载。
**何时使用**：
- 切换到完全不同的任务
- 对话已经非常混乱
- Claude Code 给出的回答质量明显下降
#### `/rewind` — 回退对话
```
> /rewind
```
**效果**：撤销最近的几轮对话，回退到之前的状态。
**何时使用**：
- Claude Code 走了错误的方向
- 最近的操作产生了不好的结果
- 想尝试不同的方法
### 5.4 上下文优化策略
#### 策略一：分而治之
不要在一个会话中处理太多不相关的任务。一个会话专注一个主题：
```mermaid
flowchart LR
subgraph "❌ 低效方式"
A1[会话1: 修Bug + 写新功能 + 重构 + 部署]
end
subgraph "✅ 高效方式"
B1[会话1: 修复登录Bug]
B2[会话2: 实现支付功能]
B3[会话3: 重构用户模块]
B4[会话4: 部署到staging]
end
```
#### 策略二：精准的文件引用
避免让 Claude Code 读取整个项目。指定具体文件：
```
# ❌ 太宽泛
"看看这个项目有什么问题"
# ✅ 精准
"检查 backend/src/services/paymentService.ts 中的并发问题，
参照 backend/src/services/orderService.ts 的实现模式"
```
#### 策略三：利用 CLAUDE.md 预加载知识
把经常重复解释的内容写入 CLAUDE.md，避免每次对话都浪费 token 解释：
```markdown
# 常见调试流程
## 数据库连接问题
1. 检查 docker-compose 中 PostgreSQL 是否运行：`docker ps`
2. 验证连接字符串在 `.env` 中是否正确
3. 测试连接：`npm run db:test-connection`
## API 503 错误
1. 检查 Redis 连接状态
2. 查看限流日志：`tail -f logs/rate-limit.log`
3. 确认上游服务是否正常
```
#### 策略四：工具调用结果控制
大型文件读取会消耗大量 token。使用这些技巧控制：
```bash
# 在 CLAUDE.md 或 rules 中添加：
- 读取文件时优先使用 offset 和 limit 参数
- 大文件（> 500 行）只读取相关部分
- 搜索代码优先使用 Grep/Glob，不要 Read 整个项目
- 分析完成后不要重复读取已知内容
```
---
## 第六章：完整实战——构建大型项目的记忆架构
### 6.1 场景描述
假设你负责一个中型 SaaS 项目，团队 5 人使用 Claude Code 协作开发。项目结构：
```
saas-platform/
├── apps/
│ ├── web/ # Next.js 前端
│ ├── api/ # Express 后端
│ └── worker/ # BullMQ 任务处理
├── packages/
│ ├── shared-types/ # 共享 TypeScript 类型
│ └── utils/ # 共享工具函数
├── infra/ # AWS CDK 基础设施
├── docs/ # 项目文档
├── CLAUDE.md
├── CLAUDE.local.md
└── .claude/
├── rules/
├── settings.json
└── commands/ # 自定义斜杠命令
```
### 6.2 步骤一：创建根 CLAUDE.md
```bash
cat > CLAUDE.md << 'EOF'
# SaaS Platform — Claude Code 项目指南
## 架构概览
Monorepo 结构，使用 Turborepo 管理。三个应用 + 两个共享包。
## 技术栈
- 前端: Next.js 14 + React 18 + Tailwind CSS + Zustand
- 后端: Express.js + TypeScript + TypeORM + PostgreSQL
- 任务队列: BullMQ + Redis
- 基础设施: AWS CDK (TypeScript)
- 包管理: pnpm workspace
## 关键命令
```bash
pnpm install # 安装所有依赖
pnpm --filter web dev # 启动前端开发服务器
pnpm --filter api dev # 启动后端开发服务器
pnpm -r test # 运行所有测试
pnpm -r build # 构建所有包
```
## 编码原则
- 类型安全优先：充分利用 TypeScript 严格模式
- 错误不吞咽：所有异步操作必须有错误处理
- 测试驱动：核心业务逻辑先写测试
- 文件不超过 300 行：超过则拆分
## 项目约定
- API 端点遵循 RESTful 规范
- 数据库迁移必须可回滚
- PR 必须通过 CI 才能合并
- 敏感信息使用环境变量，通过 AWS Secrets Manager 管理
EOF
```
### 6.3 步骤二：创建 Rules 文件
```bash
mkdir -p .claude/rules
# 前端规则
cat > .claude/rules/frontend.md << 'EOF'
---
description: Next.js 前端开发规范
globs: ["apps/web/**"]
---
# Next.js 开发规范
## 路由约定
- App Router（不使用 Pages Router）
- 路由参数使用 TypeScript 类型
- Server Component 优先，只在需要交互时使用 Client Component
## 数据获取
- 使用 Server Component 直接查询
- 客户端状态使用 SWR（不是 React Query）
- 表单使用 Server Actions
## 样式
- Tailwind CSS 为主
- 复杂组件使用 CSS Modules
- 设计 token 定义在 tailwind.config.ts
## 性能
- 图片使用 next/image
- 大组件使用 dynamic import
- 字体使用 next/font
EOF
# 后端规则
cat > .claude/rules/backend.md << 'EOF'
---
description: Express 后端 API 开发规范
globs: ["apps/api/**"]
---
# 后端 API 规范
## 分层架构
Router → Controller → Service → Repository
- Router：定义路由和中间件
- Controller：参数校验和响应格式化
- Service：业务逻辑
- Repository：数据库操作
## 数据库
- TypeORM 实体放在 models/
- 复杂查询使用 QueryBuilder
- 迁移文件必须包含 up 和 down
- 连接配置使用环境变量
## API 规范
- 版本化路由：/api/v1/...
- 统一响应格式：{ success, data, error }
- 分页参数：page, pageSize（默认 20）
- 错误码对照表见 docs/error-codes.md
EOF
# 基础设施规则
cat > .claude/rules/infra.md << 'EOF'
---
description: AWS CDK 基础设施规范
globs: ["infra/**"]
---
# AWS CDK 规范
## 环境管理
- 三套环境：dev / staging / prod
- 每套环境独立的 CDK stack
- 状态管理使用 AWS SSM Parameter Store
## 安全
- 所有 secret 使用 AWS Secrets Manager
- S3 bucket 必须启用加密和版本控制
- 安全组规则最小化原则
## 命名规范
- 资源命名格式：{project}-{env}-{resource-type}
- Tag 必须包含：Environment, Team, CostCenter
EOF
# 共享包规则
cat > .claude/rules/shared.md << 'EOF'
---
description: 共享包开发规范
globs: ["packages/**"]
---
# 共享包规范
## 设计原则
- 零副作用：纯类型和工具函数
- 最小依赖：不引入框架级依赖
- 完整导出：所有公共 API 通过 index.ts 导出
## shared-types
- 所有 API 请求/响应类型
- 数据库模型类型（与 TypeORM 实体对应）
- 枚举和常量定义
## utils
- 日期/时间处理
- 字符串工具
- 数据校验（不引入 zod，使用原生 TS 类型守卫）
EOF
```
### 6.4 步骤三：创建本地配置
```bash
# 个人配置（不提交 Git）
cat > CLAUDE.local.md << 'EOF'
# 个人开发配置
## 环境
- Node.js 22.x (使用 nvm)
- 本地 PostgreSQL 端口 5433
- 本地 Redis 端口 6380
## 工作偏好
- 调试时喜欢加 console.log 后删除
- 先用最简实现验证思路，再优化
- 优先写可读性好的代码，性能优化有数据支撑再做
## 当前焦点
- 正在重构支付模块（截止 6/15）
- 用户反馈的搜索性能问题待排查
EOF
# 确保不提交
echo "CLAUDE.local.md" >> .gitignore
```
### 6.5 步骤四：初始化 Memory 系统
在 Claude Code 会话中：
```
> 记住以下信息：我们团队使用 Redis 实现 API 限流，
配额为普通用户 100req/min，VIP 1000req/min。
实现文件在 apps/api/src/middleware/rateLimit.ts
> 记住：支付模块的重构方案已经和产品团队确认，
新方案使用 Stripe Direct 而不是 Stripe Connect，
因为我们的商户模式是单商户而非平台模式。
> 记住我的偏好：修改代码后立即运行相关测试验证，
不要等所有修改完成后才测试。
```
### 6.6 步骤五：验证记忆系统
在新会话中验证：
```
> 我们的 API 限流方案是什么？
（期望：从 memory 中回答 Redis + Token Bucket）
> 支付模块重构选择了哪个 Stripe 方案？
（期望：Stripe Direct，单商户模式）
> 前端组件应该用什么状态管理库？
（期望：从 rules/frontend.md 回答 Zustand）
> 后端的分层架构是什么？
（期望：从 rules/backend.md 回答 Router→Controller→Service→Repository）
```
### 6.7 完整的工作流架构图
```mermaid
flowchart TB
subgraph "会话启动阶段"
A[启动 Claude Code] --> B[加载全局 CLAUDE.md
~/.claude/CLAUDE.md]
B --> C[加载项目 CLAUDE.md
./CLAUDE.md]
C --> D[加载本地 CLAUDE.md
./CLAUDE.local.md]
D --> E[加载 Memory 索引
MEMORY.md]
E --> F[准备就绪]
end
subgraph "任务执行阶段"
F --> G{涉及哪些文件路径?}
G -->|apps/web/| H[激活 frontend.md 规则]
G -->|apps/api/| I[激活 backend.md 规则]
G -->|infra/| J[激活 infra.md 规则]
G -->|packages/| K[激活 shared.md 规则]
H --> L[执行任务]
I --> L
J --> L
K --> L
end
subgraph "知识沉淀阶段"
L --> M{是否发现值得记录的知识?}
M -->|是| N[创建/更新 Memory 文件]
M -->|否| O[继续工作]
N --> P[更新 MEMORY.md 索引]
P --> O
end
subgraph "上下文管理阶段"
O --> Q{上下文是否接近上限?}
Q -->|是| R[执行 /compact]
Q -->|否| S[继续对话]
R --> S
end
style F fill:#22c55e,color:#fff
style L fill:#3b82f6,color:#fff
style N fill:#f59e0b,color:#fff
style R fill:#ef4444,color:#fff
```
---
## 第七章：高级技巧与常见问题
### 7.1 让 Claude Code 自动维护记忆
在 CLAUDE.md 中添加以下指令，让 Claude Code 主动管理记忆：
```markdown
## 记忆管理规则
- 当发现重要的技术决策或架构变更时，主动建议创建 Memory 文件
- 当修正了 Claude Code 的错误理解时，建议更新相关 Memory
- 当完成一个复杂任务后，总结关键知识点并存入 Memory
- 定期检查 MEMORY.md 索引，清理过时的记忆
```
### 7.2 团队共享记忆的最佳实践
```mermaid
flowchart TB
subgraph "Git 管理（团队共享）"
A[CLAUDE.md]
B[".claude/rules/*.md"]
C[".claude/settings.json"]
end
subgraph ".gitignore（个人专属）"
D[CLAUDE.local.md]
E["~/.claude/projects/*/memory/*"]
end
subgraph "Code Review 流程"
F[PR 包含 CLAUDE.md 变更] --> G[团队评审规范变更]
G --> H[确保规则合理且必要]
end
style A fill:#22c55e,color:#fff
style B fill:#22c55e,color:#fff
style D fill:#f59e0b,color:#fff
style E fill:#f59e0b,color:#fff
```
**团队协作建议**：
1. CLAUDE.md 的修改应该通过 PR 流程，团队共同评审
2. Rules 文件分配给各模块负责人维护
3. 定期（每月）清理过时的规则
4. 新成员加入时，CLAUDE.md 作为 onboarding 文档的一部分
### 7.3 常见问题排查
**问题一：Claude Code 忽略了 CLAUDE.md 中的规则**
可能原因：
- 文件编码问题——确保使用 UTF-8 无 BOM
- 文件位置错误——确认在项目根目录
- 规则太模糊——使用更具体的指令，避免"注意代码质量"这类空泛描述
- 上下文压缩后丢失——在被压缩后再次引用规则
解决方案：
```
> /compact 请保留 CLAUDE.md 中的所有编码规范
或者重新加载：
> 请重新读取 CLAUDE.md 并严格遵循其中的规范
```
**问题二：Rules 文件没有生效**
检查清单：
```bash
# 1. 确认文件位置正确
ls -la .claude/rules/
# 2. 确认 frontmatter 格式正确（YAML 语法）
head -5 .claude/rules/frontend.md
# 应该看到 ---
# description: ...
# globs: [...]
# 3. 确认 glob 模式匹配你的文件路径
# 如果 globs 是 ["src/components/**"]
# 那么编辑 src/components/Button.tsx 会激活规则
# 但编辑 lib/utils.ts 不会
# 4. 使用 /memory 命令确认文件被加载
```
**问题三：上下文窗口经常溢出**
优化策略：
1. **减少 CLAUDE.md 体积** — 删除冗余内容，保持精简
2. **使用 rules 替代 CLAUDE.md** — 路径精确匹配意味着不是所有规则都需要同时加载
3. **主动 compact** — 完成子任务后立即 `/compact`
4. **分会话工作** — 不同任务开不同会话
5. **避免读取大文件** — 使用 Grep 搜索特定内容而非 Read 整个文件
**问题四：Memory 文件太多，索引太长**
```markdown
# MEMORY.md 优化策略
## 限制索引条目
- 保持在 20 条以内
- 每条一行，不超过 50 字
- 过时的记忆及时删除
## 使用 [[name]] 交叉引用
- 相关记忆之间建立链接
- Claude Code 会在需要时追踪链接
- 避免在索引中重复内容
## 定期清理
- 每月审查一次记忆文件
- 删除已解决的技术债记录
- 合并相关的碎片化记忆
```
### 7.4 上下文窗口使用的监控技巧
在 CLAUDE.md 中添加以下指令，让 Claude Code 报告上下文使用情况：
```markdown
## 上下文管理
- 当你感觉对话已经很长时，主动提醒用户考虑 /compact
- 当读取大型文件时，报告大概占用的 token 数
- 建议用户使用 Grep/Glob 替代全文件读取来节省上下文
```
---
## 第八章：进阶——自动化记忆管理
### 8.1 使用 Hooks 自动触发记忆更新
在 `.claude/settings.json` 中配置 hooks，在特定事件时自动更新记忆：
```json
{
"hooks": {
"afterSessionEnd": [
{
"type": "command",
"command": "echo '会话结束，检查是否有需要记录的知识点' >> ~/.claude/session-log.txt"
}
]
}
}
```
### 8.2 使用 Cron 任务定期整理记忆
Claude Code 支持 cron 任务来自动化重复性工作：
```
> 每周五下午5点，帮我检查和整理记忆文件：
1. 列出所有 memory 文件
2. 标记超过30天未更新的文件
3. 建议需要清理或合并的记忆
4. 更新 MEMORY.md 索引
```
### 8.3 结构化记忆模板
为常见类型的记忆创建模板，确保一致性：
```markdown
# 技术决策记忆模板
---
name: decision-<简短描述>
description: <一句话描述这个决策>
metadata:
type: project
created: <日期>
status: active | superseded | deprecated
---
## 背景
<为什么需要做这个决策？>
## 选项
1. <选项A> — <优缺点>
2. <选项B> — <优缺点>
## 决策
<最终选择了什么>
## 理由
<为什么这么选>
## 影响
<对项目的影响，需要关注的点>
## 相关文件
- `<文件路径>` — <说明>
## 相关记忆
[[<相关记忆name>]]
```
```markdown
# Bug 排查记录模板
---
name: bug-<简短描述>
description:
metadata:
type: reference
created: <日期>
severity: P0 | P1 | P2 | P3
status: fixed | investigating | wontfix
---
## 现象
## 根因
<深入分析后的根本原因>
## 解决方案
<最终如何修复的>
## 教训
<从中学到了什么，如何避免复发>
## 相关文件
- `<文件路径>` — <修改说明>
```
---
## 延伸阅读
- [Claude Code 官方文档 — Memory](https://code.claude.com/docs/en/memory) — 记忆系统的官方说明
- [Claude Code 官方文档 — Settings](https://code.claude.com/docs/en/settings) — 配置文件层级详解
- [Claude Code 官方文档 — .claude 目录](https://code.claude.com/docs/en/claude-directory) — 完整的目录结构参考
- [Claude Code 官方博客 — Session Management](https://claude.com/blog/using-claude-code-session-management-and-1m-context) — 上下文管理与1M token窗口
- [Claude Code Rules Directory 指南](https://claudefa.st/blog/guide/mechanics/rules-directory) — 模块化规则的深度教程
## 参考来源
1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — Claude Code 官方记忆系统文档，详细说明 CLAUDE.md 层级和 Memory 机制
2. [Claude Code Memory Management: The Complete Guide (2026)](https://medium.com/data-science-collective/claude-code-memory-management-the-complete-guide-2026-b0df6300c4e8) — 社区综合指南，涵盖记忆层级、token 预算、最佳实践
3. [Claude Code Rules Directory: Modular Instructions That Scale](https://claudefa.st/blog/guide/mechanics/rules-directory) — Rules 目录的路径匹配机制和模块化组织策略
4. [The Complete .claude Directory Guide for Claude Code](https://computingforgeeks.com/claude-code-dot-claude-directory-guide/) — .claude 目录的完整结构参考
5. [Claude Code Memory Architecture — ianlpaterson.com](https://ianlpaterson.com/blog/claude-code-memory-architecture/) — 实用的 MEMORY.md + frontmatter 记忆架构设计
## 训练营适用性评估
| 维度 | 评估 |
|------|------|
| **适合训练营类型** | Claude Code 实战训练营（中级班）、AI 辅助开发工作坊、团队协作效率提升营 |
| **预计教学时长** | 3-4 小时（含实操） |
| **学员基础要求** | 已使用 Claude Code 1-2 周，理解基本操作，有至少一个在开发项目 |
| **实操占比** | 60%（大量动手创建 CLAUDE.md、rules 文件、memory 文件） |
| **课后作业** | 为自己的真实项目构建完整的记忆体系（CLAUDE.md + 3+ rules + 5+ memory 文件） |
| **延伸方向** | 可衔接 Hooks 自动化课程、Subagent 开发课程、CI/CD 集成课程 |
> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。
