Claude Code记忆体系与上下文管理深度实战

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[个人偏好<br/>语言/风格/通用规则]
    C --> C1[项目约定<br/>架构/框架/编码规范]
    D --> D1[个人项目配置<br/>不应提交到 Git]
    E --> E1[路径精确匹配<br/>模块化规则文件]
    F --> F1[结构化知识<br/>带 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

# 全局偏好

## 语言与风格
- 默认使用中文回复，代码注释用英文
- 回复简洁明了，避免冗长解释

## 通用规则
- 不要自动 commit，只在明确要求时执行 git commit
- 始终先读取文件再编辑，不要盲目修改
- 优先编辑现有文件而非创建新文件
- 不要提交 secrets、credentials、.env 等敏感文件

## 代码风格
- 使用有意义的变量名
- 函数不超过 50 行
- 添加必要的错误处理

# 项目：电商平台后端

## 技术栈
- Node.js 20 + TypeScript 5.3
- Express.js + typeorm
- PostgreSQL 16 + Redis 7
- Jest 单元测试 + Supertest 集成测试

## 项目结构

## 编码规范
- 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.local.md

# 本地开发配置

## 个人偏好
- 我的本地数据库端口是 5433（非默认）
- 调试时喜欢加详细的 console.log
- 我使用 pnpm 而不是 npm

## 临时笔记
- 正在排查 orders 表的慢查询问题
- payment service 的重试逻辑需要重写
- 已和后端团队确认接口变更方案

pie title CLAUDE.md Token 预算建议（总计 ≤ 2000 tokens）
    "技术栈与项目结构" : 40
    "编码规范" : 30
    "测试与部署要求" : 15
    "Git 规范与注意事项" : 15

.claude/
├── rules/
│   ├── frontend.md        # 前端相关规则
│   ├── backend.md         # 后端相关规则
│   ├── database.md        # 数据库操作规则
│   ├── testing.md         # 测试相关规则
│   ├── security.md        # 安全编码规范
│   └── deployment.md      # 部署相关规则
├── CLAUDE.md              # 项目根指令（仍然保留）
└── settings.json          # 项目设置

---
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

---
description: 数据库操作与迁移规范
globs: ["src/repositories/**", "src/models/**", "migrations/**"]
---

# 数据库规范

## 迁移文件
- 迁移文件名格式：`YYYYMMDDHHMMSS_description.ts`
- 每个迁移必须包含 up 和 down 方法
- 禁止在迁移中使用 ORM 模型，必须使用原始 SQL

## 查询规范
- 所有查询必须使用参数化，禁止字符串拼接
- 分页查询必须包含总数统计
- 批量操作超过 1000 条时使用 batch 处理
- 慢查询（> 500ms）必须添加索引建议注释

## 模型定义
- Entity 字段必须添加注释说明用途
- 关联关系使用 `onDelete` 和 `onUpdate` 明确行为
- 金额字段统一使用 `decimal(19,4)` 类型

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

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

# 创建 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

📋 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)

---
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]]

---
name: prefer-detailed-error-messages
description: 用户偏好：错误信息需要包含完整上下文
metadata:
  type: feedback
---

错误处理代码必须包含完整上下文信息：请求参数、用户 ID、调用链。

**Why:** 多次因为错误信息不足导致排查困难，浪费了团队大量时间。

**How to apply:** 所有 catch 块中的 error message 必须附带上下文对象。使用 `logger.error('message', { context })` 格式。

[[error-handling-standards]]

- [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) — 错误信息需含上下文

graph TB
    A[Memory 文件类型] --> B["👤 user<br/>用户画像"]
    A --> C["💬 feedback<br/>反馈与偏好"]
    A --> D["📋 project<br/>项目知识"]
    A --> E["🔗 reference<br/>外部资源"]

    B --> B1["角色、专业领域、<br/>技术栈偏好"]
    C --> C1["工作方式纠正、<br/>确认的方法、避免的做法"]
    D --> D1["架构决策、技术债、<br/>已知问题、里程碑"]
    E --> E1["URL、仪表盘链接、<br/>工单号、外部文档"]

    style B fill:#3b82f6,color:#fff
    style C fill:#10b981,color:#fff
    style D fill:#f59e0b,color:#fff
    style E fill:#ef4444,color:#fff

# 1. 确认记忆目录存在
ls ~/.claude/projects/*/memory/ 2>/dev/null || echo "目录不存在，Claude Code 会自动创建"

# 2. 在 Claude Code 会话中让 AI 帮你创建记忆
# 输入提示词：
# "记住以下信息：我们团队决定使用 Redis 实现分布式限流，
#  而不是 Nginx 限流，因为需要按用户维度精确控制"

# 3. 验证记忆已创建
# 输入 /memory 命令查看

# 4. 在新会话中验证记忆生效
# 启动新会话，问："我们的限流方案是什么？"
# Claude Code 应该能从记忆中正确回答

graph LR
    A[上下文窗口] --> B[系统提示<br/>~2000 tokens]
    A --> C[CLAUDE.md 文件<br/>~500-2000 tokens]
    A --> D[Rules 文件<br/>~0-1500 tokens]
    A --> E[对话历史<br/>持续增长]
    A --> F[工具调用结果<br/>持续增长]
    A --> G[Memory 文件<br/>~200-500 tokens]

    style E fill:#ef4444,color:#fff
    style F fill:#ef4444,color:#fff

flowchart TD
    A[上下文使用率上升] --> B{达到阈值?}
    B -->|未达到| C[继续正常对话]
    B -->|达到 60%| D[第一层：自动压缩<br/>对话历史摘要]
    B -->|达到 80%| E[第二层：激进压缩<br/>丢弃低优先级内容]
    B -->|达到 95%| F[第三层：强制重置<br/>清空并重新加载]

    D --> G[保留关键指令和最近对话]
    E --> H[只保留 CLAUDE.md 和<br/>最近几轮对话]
    F --> I[从 CLAUDE.md 重新开始<br/>对话历史全部丢失]

    style D fill:#f59e0b,color:#fff
    style E fill:#ef4444,color:#fff
    style F fill:#7f1d1d,color:#fff

> /compact

> /compact 在压缩时请保留关于用户认证模块的所有讨论，因为后面还需要参考

> /clear

> /rewind

flowchart LR
    subgraph "❌ 低效方式"
        A1[会话1: 修Bug + 写新功能 + 重构 + 部署]
    end

    subgraph "✅ 高效方式"
        B1[会话1: 修复登录Bug]
        B2[会话2: 实现支付功能]
        B3[会话3: 重构用户模块]
        B4[会话4: 部署到staging]
    end

# ❌ 太宽泛
"看看这个项目有什么问题"

# ✅ 精准
"检查 backend/src/services/paymentService.ts 中的并发问题，
 参照 backend/src/services/orderService.ts 的实现模式"

# 常见调试流程

## 数据库连接问题
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. 确认上游服务是否正常

# 在 CLAUDE.md 或 rules 中添加：
- 读取文件时优先使用 offset 和 limit 参数
- 大文件（> 500 行）只读取相关部分
- 搜索代码优先使用 Grep/Glob，不要 Read 整个项目
- 分析完成后不要重复读取已知内容

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/      # 自定义斜杠命令

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             # 构建所有包

### 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

# 个人配置（不提交 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

> 记住以下信息：我们团队使用 Redis 实现 API 限流，
  配额为普通用户 100req/min，VIP 1000req/min。
  实现文件在 apps/api/src/middleware/rateLimit.ts

> 记住：支付模块的重构方案已经和产品团队确认，
  新方案使用 Stripe Direct 而不是 Stripe Connect，
  因为我们的商户模式是单商户而非平台模式。

> 记住我的偏好：修改代码后立即运行相关测试验证，
  不要等所有修改完成后才测试。

> 我们的 API 限流方案是什么？
（期望：从 memory 中回答 Redis + Token Bucket）

> 支付模块重构选择了哪个 Stripe 方案？
（期望：Stripe Direct，单商户模式）

> 前端组件应该用什么状态管理库？
（期望：从 rules/frontend.md 回答 Zustand）

> 后端的分层架构是什么？
（期望：从 rules/backend.md 回答 Router→Controller→Service→Repository）

flowchart TB
    subgraph "会话启动阶段"
        A[启动 Claude Code] --> B[加载全局 CLAUDE.md<br/>~/.claude/CLAUDE.md]
        B --> C[加载项目 CLAUDE.md<br/>./CLAUDE.md]
        C --> D[加载本地 CLAUDE.md<br/>./CLAUDE.local.md]
        D --> E[加载 Memory 索引<br/>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

## 记忆管理规则
- 当发现重要的技术决策或架构变更时，主动建议创建 Memory 文件
- 当修正了 Claude Code 的错误理解时，建议更新相关 Memory
- 当完成一个复杂任务后，总结关键知识点并存入 Memory
- 定期检查 MEMORY.md 索引，清理过时的记忆

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

> /compact 请保留 CLAUDE.md 中的所有编码规范

或者重新加载：
> 请重新读取 CLAUDE.md 并严格遵循其中的规范

# 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 命令确认文件被加载

# MEMORY.md 优化策略

## 限制索引条目
- 保持在 20 条以内
- 每条一行，不超过 50 字
- 过时的记忆及时删除

## 使用 [[name]] 交叉引用
- 相关记忆之间建立链接
- Claude Code 会在需要时追踪链接
- 避免在索引中重复内容

## 定期清理
- 每月审查一次记忆文件
- 删除已解决的技术债记录
- 合并相关的碎片化记忆

## 上下文管理
- 当你感觉对话已经很长时，主动提醒用户考虑 /compact
- 当读取大型文件时，报告大概占用的 token 数
- 建议用户使用 Grep/Glob 替代全文件读取来节省上下文

{
  "hooks": {
    "afterSessionEnd": [
      {
        "type": "command",
        "command": "echo '会话结束，检查是否有需要记录的知识点' >> ~/.claude/session-log.txt"
      }
    ]
  }
}

> 每周五下午5点，帮我检查和整理记忆文件：
  1. 列出所有 memory 文件
  2. 标记超过30天未更新的文件
  3. 建议需要清理或合并的记忆
  4. 更新 MEMORY.md 索引

# 技术决策记忆模板
---
name: decision-<简短描述>
description: <一句话描述这个决策>
metadata:
  type: project
  created: <日期>
  status: active | superseded | deprecated
---

## 背景
<为什么需要做这个决策？>

## 选项
1. <选项A> — <优缺点>
2. <选项B> — <优缺点>

## 决策
<最终选择了什么>

## 理由
<为什么这么选>

## 影响
<对项目的影响，需要关注的点>

## 相关文件
- `<文件路径>` — <说明>

## 相关记忆
[[<相关记忆name>]]

# Bug 排查记录模板
---
name: bug-<简短描述>
description: <Bug的一句话描述和最终解决方案>
metadata:
  type: reference
  created: <日期>
  severity: P0 | P1 | P2 | P3
  status: fixed | investigating | wontfix
---

## 现象
<Bug的表现>

## 根因
<深入分析后的根本原因>

## 解决方案
<最终如何修复的>

## 教训
<从中学到了什么，如何避免复发>

## 相关文件
- `<文件路径>` — <修改说明>