第02章｜过目不忘：Claude Code 记忆系统与 CLAUDE

第02章｜过目不忘：Claude Code 记忆系统与 CLAUDE.md

学习目标：掌握 Claude Code 的四种记忆类型，深入理解 CLAUDE.md 的配置方法与最佳实践，让 AI 真正"记住"你的项目规范。

2.1 为什么需要记忆系统？

问题场景

想象你每天上班都要向新同事重新介绍项目规范：

"我们用 TypeScript，不用 JavaScript"
"测试框架是 Jest，不是 Mocha"
"提交信息要遵循 Conventional Commits 规范"
"数据库操作必须用事务包裹"

这非常低效。Claude Code 的记忆系统就是为了解决这个问题------让 AI 永久记住你的项目规范，无需每次重复说明。

没有记忆系统的痛点

bash 复制代码

# 第1天
用户：帮我写一个用户注册接口
Claude：（用 JavaScript 写了一个）
用户：我们用 TypeScript！
Claude：好的，改成 TypeScript...

# 第2天（新会话）
用户：帮我写一个登录接口
Claude：（又用 JavaScript 写了一个）
用户：😤 我们用 TypeScript！！！

2.2 四种记忆类型

Claude Code 提供四种不同层次的记忆机制：

复制代码

┌─────────────────────────────────────────────────────────┐
│                   记忆系统层次结构                       │
│                                                         │
│  ① 内存记忆（In-Context Memory）                        │
│     当前会话的对话历史，会话结束后消失                   │
│                                                         │
│  ② 外部记忆（External Memory）                          │
│     文件系统中的持久化信息（CLAUDE.md）                  │
│                                                         │
│  ③ 知识记忆（Knowledge Memory）                         │
│     模型训练时学到的通用知识                             │
│                                                         │
│  ④ 缓存记忆（Cached Memory）                            │
│     Prompt Caching 缓存的 System Prompt                 │
└─────────────────────────────────────────────────────────┘

各类型对比

记忆类型	持久性	范围	典型用途
内存记忆	会话内	当前对话	临时上下文、中间结果
外部记忆	永久	项目/全局	项目规范、团队约定
知识记忆	永久	全局	编程语言、框架知识
缓存记忆	会话间	全局	降低重复 Token 成本

2.3 CLAUDE.md 核心概念

什么是 CLAUDE.md？

CLAUDE.md 是 Claude Code 的项目配置文件，类似于：

.eslintrc（ESLint 规则配置）
pyproject.toml（Python 项目配置）
.editorconfig（编辑器配置）

但 CLAUDE.md 是给 AI 读的，用自然语言描述项目规范、约定和上下文。

加载机制

Claude Code 启动时会自动按以下顺序加载 CLAUDE.md：

复制代码

加载顺序（优先级从低到高）：

1. ~/.claude/CLAUDE.md          ← 全局配置（所有项目共享）
2. /项目根目录/CLAUDE.md        ← 项目配置（当前项目）
3. /当前子目录/CLAUDE.md        ← 局部配置（特定模块）

优先级规则 ：子目录 > 项目根目录 > 全局配置，内容会合并而非覆盖。

文件引用语法

CLAUDE.md 支持引用其他文件，避免单文件过长：

markdown 复制代码

# 项目规范

@import ./docs/coding-standards.md
@import ./docs/api-conventions.md
@import ./docs/database-rules.md

2.4 CLAUDE.md 结构详解

一个完整的 CLAUDE.md 通常包含以下几个部分：

标准结构模板

markdown 复制代码

# 项目名称 - Claude Code 配置

## 项目概述
[简短描述项目是什么、做什么]

## 技术栈
[列出使用的语言、框架、工具]

## 目录结构
[关键目录说明]

## 开发规范
[编码规范、命名约定]

## 常用命令
[开发、测试、构建命令]

## 注意事项
[特殊约定、禁止事项]

## Skills 注册
[注册自定义技能]

2.5 实战案例：为真实项目配置 CLAUDE.md

案例：电商后端项目

项目背景：一个基于 FastAPI + PostgreSQL 的电商后端，团队5人，使用 Git Flow 工作流。

markdown 复制代码

# ShopAPI - Claude Code 配置文件

## 项目概述
ShopAPI 是一个基于 FastAPI 的电商后端服务，提供商品管理、订单处理、用户认证等功能。
当前版本：v2.3.1，生产环境运行在 AWS ECS。

## 技术栈
- **语言**：Python 3.11（严格类型注解，不允许 `Any` 类型）
- **框架**：FastAPI 0.104+
- **数据库**：PostgreSQL 15 + SQLAlchemy 2.0（异步模式）
- **缓存**：Redis 7
- **测试**：pytest + pytest-asyncio
- **代码质量**：ruff（格式化+lint）+ mypy（类型检查）

## 目录结构

src/

├── api/ # 路由层（只做参数校验和响应格式化）

├── services/ # 业务逻辑层（核心业务代码在这里）

├── repositories/ # 数据访问层（所有数据库操作）

├── models/ # SQLAlchemy 模型

├── schemas/ # Pydantic 模型（请求/响应）

└── core/ # 配置、依赖注入、中间件

tests/

├── unit/ # 单元测试（mock 数据库）

└── integration/ # 集成测试（真实数据库）

复制代码

## 开发规范

### 架构规范
- **严格三层架构**：api → service → repository，禁止跨层调用
- api 层不允许直接操作数据库
- service 层不允许直接导入 SQLAlchemy Session
- 所有数据库操作必须在 repository 层

### 数据库规范
- 所有写操作（INSERT/UPDATE/DELETE）必须在事务中执行
- 使用异步 Session：`async with AsyncSession() as session`
- 禁止在循环中执行数据库查询（N+1 问题）
- 复杂查询必须添加适当索引，并在 PR 中说明

### 错误处理规范
- 使用自定义异常类（在 `src/core/exceptions.py` 中定义）
- API 层统一捕获异常并转换为标准响应格式
- 禁止在 service 层返回 HTTP 状态码

### 命名规范
- 文件名：snake_case（如 `user_service.py`）
- 类名：PascalCase（如 `UserService`）
- 函数名：snake_case（如 `get_user_by_id`）
- 常量：UPPER_SNAKE_CASE（如 `MAX_RETRY_COUNT`）
- 数据库表名：复数形式（如 `users`、`orders`）

## 常用命令

### 开发
```bash
# 启动开发服务器
uvicorn src.main:app --reload --port 8000

# 数据库迁移
alembic upgrade head
alembic revision --autogenerate -m "描述"

# 代码格式化
ruff format src/ tests/
ruff check src/ tests/ --fix

测试

bash 复制代码

# 运行所有测试
pytest

# 只运行单元测试
pytest tests/unit/ -v

# 运行特定测试文件
pytest tests/unit/test_user_service.py -v

# 生成覆盖率报告
pytest --cov=src --cov-report=html

类型检查

bash 复制代码

mypy src/ --strict

Git 规范

分支命名：feature/xxx、fix/xxx、hotfix/xxx
提交信息遵循 Conventional Commits：
- feat: 添加用户注册功能
- fix: 修复订单金额计算错误
- refactor: 重构支付服务
PR 必须通过 CI（测试+类型检查+lint）才能合并

注意事项

禁止在代码中硬编码密钥、密码、API Key
禁止在生产代码中使用 print()，统一使用 logger
禁止提交 .env 文件
所有新功能必须有对应的单元测试，覆盖率不低于 80%

修改数据库 Schema 必须同步更新 migration 文件

效果验证

配置好 CLAUDE.md 后，Claude Code 会自动遵守这些规范：

bash 复制代码

# 用户请求
用户：帮我写一个获取用户订单列表的接口

# Claude Code 会自动：
# 1. 在 api/ 层创建路由（只做参数校验）
# 2. 在 services/ 层创建业务逻辑
# 3. 在 repositories/ 层创建数据库查询
# 4. 使用异步 Session
# 5. 添加类型注解
# 6. 创建对应的 Pydantic Schema
# 7. 在 tests/unit/ 创建单元测试

2.6 全局 CLAUDE.md 配置

全局配置适合放置跨项目通用的个人偏好：

markdown 复制代码

# 全局 Claude Code 配置
# 文件位置：~/.claude/CLAUDE.md

## 我的编程偏好

### 通用规范
- 代码注释使用中文（我是中文母语者）
- 函数和变量命名使用英文
- 优先使用函数式编程风格
- 避免过深的嵌套（最多3层）

### 输出格式
- 修改代码时，先解释修改原因，再给出代码
- 给出代码后，说明如何验证修改是否正确
- 如果有多种实现方案，列出优缺点让我选择

### 安全意识
- 任何涉及用户数据的操作，提醒我考虑隐私合规
- 发现潜在安全漏洞时，优先报告而不是直接修复

### 我常用的工具
- 版本控制：Git
- 容器：Docker + Docker Compose
- CI/CD：GitHub Actions

2.7 子目录 CLAUDE.md：模块级配置

对于大型项目，可以在特定子目录放置 CLAUDE.md，为该模块提供专属配置：

案例：前端子目录配置

复制代码

项目结构：
my-fullstack-app/
├── CLAUDE.md              ← 项目全局配置
├── backend/
│   ├── CLAUDE.md          ← 后端专属配置
│   └── src/
└── frontend/
    ├── CLAUDE.md          ← 前端专属配置
    └── src/

frontend/CLAUDE.md：

markdown 复制代码

# 前端模块配置

## 技术栈
- React 18 + TypeScript
- Vite 构建工具
- Tailwind CSS（禁止使用内联 style）
- Zustand 状态管理（禁止使用 Redux）
- React Query 数据获取

## 组件规范
- 所有组件使用函数式组件 + Hooks
- 组件文件名：PascalCase（如 `UserCard.tsx`）
- 每个组件一个文件，禁止在一个文件中定义多个组件
- Props 必须定义 TypeScript 接口

## 目录结构

src/

├── components/ # 通用组件（无业务逻辑）

├── features/ # 功能模块（含业务逻辑）

├── hooks/ # 自定义 Hooks

├── stores/ # Zustand Store

└── utils/ # 工具函数

复制代码

## 禁止事项
- 禁止在组件中直接调用 API（使用 React Query）
- 禁止使用 any 类型
- 禁止使用 class 组件

2.8 AutoMemory：自动记忆机制

Claude Code v2.1.7+ 引入了 AutoMemory 功能，AI 可以主动将重要信息写入 CLAUDE.md。

工作原理

复制代码

用户在对话中说："我们决定把所有 API 响应统一包装成 {code, data, message} 格式"
         ↓
Claude Code 识别这是重要的项目决策
         ↓
自动将此规范追加到 CLAUDE.md
         ↓
下次会话自动生效，无需重复说明

手动触发记忆写入

bash 复制代码

# 在对话中明确要求 Claude 记住某件事
用户：请记住，我们的 API 基础路径是 /api/v2，不是 /api/v1

# Claude Code 会将此信息写入 CLAUDE.md

2.9 CLAUDE.md 最佳实践

✅ 应该写什么

类别	示例
技术选型	"使用 PostgreSQL，不用 MySQL"
架构约定	"三层架构：controller→service→repository"
禁止事项	"禁止在循环中查询数据库"
常用命令	"测试命令：npm test"
项目背景	"这是一个 B2B SaaS 产品，主要用户是企业管理员"
代码风格	"使用 2 空格缩进，不用 Tab"

❌ 不应该写什么

类别	原因
大量代码示例	占用 Token，效果差
过于详细的业务逻辑	应该在代码注释中
频繁变化的信息	维护成本高
敏感信息（密钥等）	安全风险

📏 长度建议

全局 CLAUDE.md：100-300 行
项目 CLAUDE.md：200-500 行
子目录 CLAUDE.md：50-150 行

过长的 CLAUDE.md 会消耗大量 Token，且 AI 可能无法充分关注所有内容。

2.10 调试：验证 CLAUDE.md 是否生效

bash 复制代码

# 方法1：查看当前加载的配置
claude
# 在交互界面输入：
/memory

# 方法2：直接询问 Claude
用户：你知道我们项目的测试命令是什么？
# 如果 CLAUDE.md 配置正确，Claude 应该能回答出来

# 方法3：查看 verbose 输出
claude --verbose
# 启动时会显示加载了哪些 CLAUDE.md 文件

2.11 本章小结

核心概念	要点
四种记忆类型	内存/外部/知识/缓存，各有适用场景
CLAUDE.md 定位	给 AI 读的项目配置文件，自然语言描述规范
加载顺序	全局→项目→子目录，优先级递增，内容合并
配置内容	技术栈、架构约定、禁止事项、常用命令
AutoMemory	AI 主动将对话中的决策写入 CLAUDE.md

🧪 动手练习

练习1：为你的项目创建 CLAUDE.md

bash 复制代码

# 在你的项目根目录创建 CLAUDE.md
cd your-project
touch CLAUDE.md

# 填写以下内容（根据实际情况修改）：
cat > CLAUDE.md << 'EOF'
# 项目名称

## 技术栈
- 语言：[你的语言]
- 框架：[你的框架]
- 数据库：[你的数据库]

## 常用命令
- 启动：[启动命令]
- 测试：[测试命令]
- 构建：[构建命令]

## 开发规范
- [你的规范1]
- [你的规范2]
EOF

练习2：验证记忆效果

bash 复制代码

# 启动 Claude Code
claude

# 测试1：询问技术栈
用户：我们项目用什么语言？

# 测试2：让 Claude 写代码，验证是否遵守规范
用户：帮我写一个简单的 Hello World 函数

# 观察 Claude 是否自动遵守了 CLAUDE.md 中的规范

练习3：创建全局配置

bash 复制代码

mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# 全局配置

## 我的偏好
- 代码注释使用中文
- 修改代码前先解释原因
- 提供多种方案时列出优缺点
EOF

⬅️ 上一章：第01章 - 底层技术全景导览

➡️ 下一章：第03章 - Sub-Agents 核心概念