Claude Code上下文工程：从CLAUDE.md到记忆管理全实战

graph TD
    A[用户输入] --> G[上下文窗口]
    B[CLAUDE.md指令] --> G
    C[对话历史] --> G
    D[工具调用结果] --> G
    E[自动记忆文件] --> G
    F[系统提示] --> G
    G --> H[Claude模型推理]
    H --> I[代码修改/回复]

    style G fill:#f9f,stroke:#333,stroke-width:2px
    style H fill:#bbf,stroke:#333,stroke-width:2px

graph TB
    subgraph 全局级
        A["~/.claude/CLAUDE.md<br/>所有项目共享"]
    end
    subgraph 项目级
        B["项目根目录/CLAUDE.md<br/>当前项目所有成员共享"]
        C["项目根目录/.claude/CLAUDE.md<br/>（推荐位置，同上）"]
    end
    subgraph 目录级
        D["src/CLAUDE.md<br/>仅特定子目录生效"]
        E["tests/CLAUDE.md<br/>仅测试目录生效"]
    end
    A --> B
    B --> D
    B --> E
    A -.->|加载优先级从上到下| B
    B -.-> D

    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#e8f5e9
    style E fill:#e8f5e9

# 全局编码偏好

## 语言
- 默认使用中文回复
- 代码注释使用英文

## 编码风格
- 使用2空格缩进
- 变量名使用camelCase，组件名使用PascalCase
- 优先使用函数式编程风格
- 避免使用any类型（TypeScript）

## Git规范
- 不要自动commit
- commit message使用英文
- 不要提交.env文件

## 通用规则
- 始终先读取文件再编辑
- 优先编辑现有文件而非创建新文件
- 修改代码后主动运行测试

# 方法一：直接创建
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# 全局编码偏好
- 默认使用中文回复
- 代码注释使用英文
- 使用2空格缩进
- 不要自动commit
- 始终先读取文件再编辑
EOF

# 方法二：在Claude Code会话中使用斜杠命令
# 直接在对话中输入：
# /memory
# 然后选择编辑全局指令

# 项目：电商平台后端

## 技术栈
- 运行时：Node.js 20 LTS
- 框架：Fastify 4.x（注意不是Express）
- 数据库：PostgreSQL 16 + Prisma ORM
- 缓存：Redis 7
- 测试：Vitest + Supertest

## 项目架构

## 编码规范
- 每个API路由必须有对应的Schema验证（使用TypeBox）
- 错误处理使用自定义AppError类
- 数据库操作必须放在repository层
- 新增API必须编写集成测试

## 常用命令
- `npm run dev` — 启动开发服务器（端口3001）
- `npm test` — 运行所有测试
- `npm run test:watch` — 监听模式运行测试
- `npx prisma migrate dev` — 运行数据库迁移
- `npx prisma studio` — 打开数据库GUI

## 关键约定
- 不要直接修改prisma/schema.prisma，先讨论变更方案
- 所有时间使用UTC，前端负责时区转换
- API响应格式统一：{ success: boolean, data?: any, error?: string }

# tests/ 目录规则

- 测试文件命名：`*.test.ts`
- 每个测试文件对应一个源文件
- 使用describe/it结构组织测试
- Mock外部依赖，不要调用真实API
- 测试数据库使用独立的test数据库

# src/services/payment/ 目录规则

## 支付流程架构
本模块处理支付核心逻辑，涉及三个阶段：
1. 创建订单 → 验证库存 → 冻结金额
2. 调用支付网关 → 处理回调
3. 确认支付 → 更新库存 → 发送通知

## 重要约束
- 支付金额计算使用decimal.js，绝不用浮点数
- 所有金额单位为分（整数），前端转换为元
- 支付回调必须验证签名
- 不要修改订单状态机以外的状态转换逻辑

graph LR
    subgraph 持久记忆
        A["CLAUDE.md<br/>手动编写<br/>提交到Git"]
    end
    subgraph 自动记忆
        B[".claude/memory/<br/>自动生成<br/>不提交到Git"]
    end
    A --> C[会话启动时加载]
    B --> C
    C --> D[Claude Code运行]

    style A fill:#e1f5fe
    style B fill:#fff9c4

# 在Claude Code对话中使用斜杠命令
/memory

# 或直接查看文件
ls .claude/memory/
cat .claude/memory/*.md

# 每周检查一次记忆文件是否有冲突或过时内容
cat .claude/memory/*.md | less

<!-- 从自动记忆提升到CLAUDE.md的示例 -->

## API设计规范
- RESTful路径使用kebab-case: `/user-profile`, `/order-history`
- 响应状态码严格遵循HTTP语义
- 分页参数统一使用 `?page=1&limit=20`

# 将自动记忆加入.gitignore（因为它是个人化的）
echo ".claude/memory/" >> .gitignore

# 但保留CLAUDE.md（它是团队共享的）
git add CLAUDE.md

graph LR
    A[会话启动<br/>加载CLAUDE.md] --> B[任务执行<br/>上下文增长]
    B --> C{上下文使用率}
    C -->|< 60%| B
    C -->|60-80%| D["建议手动/compact"]
    C -->|> 80%| E["自动压缩触发"]
    D --> F[压缩后继续]
    E --> F
    F --> B

    style C fill:#fff9c4
    style D fill:#ffe0b2
    style E fill:#ffcdd2

# 在Claude Code对话中输入
/compact

# 带自定义压缩指令
/compact 请保留关于支付模块的所有讨论，丢弃CSS样式相关的对话

# 在Claude Code对话中输入
/clear

# 清除后开始新对话，CLAUDE.md中的指令仍然生效

# 在Claude Code对话中输入
/rewind

# Claude会显示对话历史，让你选择回退到哪一步

graph TD
    A[开始新任务] --> B{任务复杂度}
    B -->|简单<br/>修bug/小改动| C[单个会话<br/>完成后/clear]
    B -->|中等<br/>新功能开发| D[单个会话<br/>定期/compact]
    B -->|复杂<br/>架构重构| E[多会话策略<br/>分阶段/clear]

    D --> F{上下文>60%}
    F -->|是| G["/compact<br/>带保留提示"]
    F -->|否| H[继续工作]
    G --> H

    E --> I[阶段1: 分析规划]
    I --> J["/clear"]
    J --> K[阶段2: 实现代码]
    K --> L["/clear"]
    L --> M[阶段3: 测试修复]

    style C fill:#c8e6c9
    style D fill:#fff9c4
    style E fill:#ffccbc

请分析当前认证系统的架构，列出所有需要修改的文件。
不要修改任何代码，只做分析。

基于以下计划重构认证系统：
[粘贴会话一的分析结果]

请先修改核心认证模块 src/services/auth.ts

认证系统重构已完成，现在需要：
1. 运行所有测试
2. 修复失败的测试
3. 补充新的集成测试

# 低效方式（消耗大量上下文Token）
"帮我看看这个项目有什么问题"

# 高效方式（精准定位）
"请阅读 src/services/payment.ts 的第45-80行，这个函数有并发问题"

# 低效方式（可能触发上下文溢出）
"请重构整个认证系统，包括JWT、OAuth、session管理，然后写测试，最后更新文档"

# 高效方式（分阶段执行）
# 第一阶段
"请分析 src/auth/ 目录下所有文件的结构和依赖关系"

# 确认分析结果后
"请重构 auth.service.ts，将JWT逻辑抽取到独立的 jwt.service.ts"

# 逐个文件推进...

# 指定只读取特定文件
"请只看 package.json 和 tsconfig.json，不要读取其他文件"

# 明确排除
"在搜索实现方式时，不要读取 node_modules 和 dist 目录"

# 使用Glob模式的精确指定
"请查看 src/routes/*.ts 中的所有路由定义"

# 查看当前上下文状态（在Claude Code对话中）
/status

# 当接近上限时，主动压缩并给出保留优先级
/compact 保留所有关于数据库schema的讨论，可以丢弃UI样式的讨论

## 上下文管理规则
- 当我说"继续"时，继续上一次未完成的任务
- 当我说"下一个"时，进入计划中的下一个步骤
- 不需要重复你已经知道的信息，直接执行
- 修改文件前不需要展示完整文件内容，只展示变更部分

.claude/
├── CLAUDE.md          # 项目级指令（推荐放这里）
├── settings.json      # Claude Code行为配置
├── memory/            # 自动记忆文件
├── commands/          # 自定义斜杠命令
├── skills/            # 项目级Skills
└── hooks/             # 事件钩子

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(npm publish)"
    ]
  },
  "autoCompact": true,
  "compactThreshold": 0.6
}

my-saas-app/
├── app/               # Next.js App Router
├── components/        # React组件
├── lib/               # 工具函数和共享逻辑
├── prisma/            # 数据库Schema和迁移
├── public/            # 静态资源
├── tests/             # 测试文件
├── package.json
├── next.config.ts
└── tsconfig.json

# 创建全局CLAUDE.md
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# 个人编码偏好

## 通用
- 默认使用中文回复
- 代码注释使用英文
- 使用2空格缩进（TypeScript/JavaScript）
- 优先使用ES模块语法（import/export）
- 变量名使用camelCase，类型/接口使用PascalCase

## Git
- 不要自动commit
- 不要自动git add
- commit message用英文，使用conventional commits格式

## 安全
- 不要提交.env、credentials等敏感文件
- SQL查询必须使用参数化，禁止字符串拼接
- 用户输入必须验证
EOF

cd my-saas-app
cat > CLAUDE.md << 'EOF'
# SaaS应用 - 项目配置

## 技术栈
- 框架：Next.js 15（App Router）
- 语言：TypeScript 5（strict模式）
- 样式：Tailwind CSS 4
- 数据库：PostgreSQL + Prisma 6
- 认证：NextAuth.js v5
- 测试：Vitest + Playwright
- 包管理：pnpm

## 架构约定
- app/目录按功能模块组织，每个模块有自己的page.tsx和layout.tsx
- 组件分为 ui/（通用）和 features/（业务）两个子目录
- lib/db.ts 导出Prisma客户端单例
- lib/auth.ts 导出NextAuth配置
- Server Actions放在对应的app/模块目录下

## 关键规则
- 新页面必须添加loading.tsx和error.tsx
- 数据库变更必须通过Prisma迁移（npx prisma migrate dev）
- API路由使用Route Handler（app/api/）
- 不要使用getServerSideProps或getStaticProps（那是Pages Router）

## 常用命令
- `pnpm dev` — 启动开发服务器
- `pnpm build` — 生产构建
- `pnpm test` — 运行单元测试
- `pnpm test:e2e` — 运行端到端测试
- `npx prisma studio` — 数据库管理界面
- `npx prisma generate` — 重新生成Prisma客户端

## 上下文管理
- 修改文件前先读取确认现有内容
- 修改代码后运行 `pnpm test` 验证
- 当对话超过30轮时提醒我执行 /compact
EOF

# 测试目录配置
mkdir -p tests
cat > tests/CLAUDE.md << 'EOF'
# 测试目录规则

## 单元测试
- 文件放在 tests/unit/ 下，镜像src/目录结构
- 使用 describe/it 结构
- Mock外部依赖（数据库、API调用）
- 每个测试文件对应一个源文件

## E2E测试
- 文件放在 tests/e2e/ 下
- 使用Playwright
- 测试关键用户流程：注册→登录→使用核心功能→登出
- 使用 page.goto('/') 而不是硬编码URL

## 命名
- 测试文件：`*.test.ts` 或 `*.spec.ts`
- 测试描述使用中文，便于团队理解
EOF

# Prisma目录配置
cat > prisma/CLAUDE.md << 'EOF'
# 数据库规则

## Schema约定
- 模型名使用PascalCase
- 字段名使用camelCase
- 每个模型必须有 createdAt 和 updatedAt 字段（使用 @updatedAt）
- 枚举类型定义在文件顶部
- 使用 @@map 指定表名（snake_case）

## 迁移规则
- 小改动可以直接 npx prisma migrate dev
- 大改动（删字段、改类型）先备份讨论
- 迁移后必须更新seed脚本
EOF

# 创建.gitignore条目（个人化的不提交）
cat >> .gitignore << 'EOF'
# Claude Code个人记忆
.claude/memory/
EOF

# 确保项目级配置被团队共享
git add CLAUDE.md tests/CLAUDE.md prisma/CLAUDE.md

claude

请总结你了解到的关于这个项目的所有信息

flowchart TB
    Start[项目启动] --> A[创建全局~/.claude/CLAUDE.md]
    A --> B[创建项目级CLAUDE.md]
    B --> C[创建目录级CLAUDE.md]
    C --> D[配置.gitignore]
    D --> E[提交到Git仓库]

    E --> F[开始日常开发]
    F --> G{任务复杂度}

    G -->|简单任务| H[单会话完成]
    H --> I[完成后/clear]

    G -->|中等任务| J[单会话推进]
    J --> K{上下文>60%}
    K -->|是| L["/compact 带保留提示"]
    K -->|否| M[继续工作]
    L --> M
    M --> N{任务完成}
    N -->|否| K
    N -->|是| O[/clear 新任务]

    G -->|复杂任务| P[拆分为3-5个子任务]
    P --> Q[子任务1: 分析规划]
    Q --> R[/clear]
    R --> S[子任务2: 核心实现]
    S --> T[/compact]
    T --> U[子任务3: 测试修复]
    U --> V[/clear]
    V --> W[全部完成]

    I --> X[项目结束]
    O --> X
    W --> X

    style Start fill:#e8f5e9
    style X fill:#e8f5e9
    style L fill:#fff9c4
    style R fill:#fff9c4
    style T fill:#fff9c4
    style V fill:#fff9c4

## 重要约定（不要压缩丢弃）
- 支付模块必须使用decimal.js处理金额
- 所有API必须经过认证中间件