第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 永久记住你的项目规范，无需每次重复说明。
没有记忆系统的痛点
# 第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 支持引用其他文件，避免单文件过长：
# 项目规范 @import ./docs/coding-standards.md @import ./docs/api-conventions.md @import ./docs/database-rules.md2.4 CLAUDE.md 结构详解
一个完整的 CLAUDE.md 通常包含以下几个部分：
标准结构模板
# 项目名称 - Claude Code 配置 ## 项目概述 [简短描述项目是什么、做什么] ## 技术栈 [列出使用的语言、框架、工具] ## 目录结构 [关键目录说明] ## 开发规范 [编码规范、命名约定] ## 常用命令 [开发、测试、构建命令] ## 注意事项 [特殊约定、禁止事项] ## Skills 注册 [注册自定义技能]2.5 实战案例：为真实项目配置 CLAUDE.md
案例：电商后端项目
项目背景：一个基于 FastAPI + PostgreSQL 的电商后端，团队5人，使用 Git Flow 工作流。
# 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测试
# 运行所有测试pytest# 只运行单元测试pytest tests/unit/-v# 运行特定测试文件pytest tests/unit/test_user_service.py-v# 生成覆盖率报告pytest--cov=src --cov-report=html类型检查
mypy src/--strictGit 规范
- 分支命名：
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 配置
全局配置适合放置跨项目通用的个人偏好：
# 全局 Claude Code 配置 # 文件位置：~/.claude/CLAUDE.md ## 我的编程偏好 ### 通用规范 - 代码注释使用中文（我是中文母语者） - 函数和变量命名使用英文 - 优先使用函数式编程风格 - 避免过深的嵌套（最多3层） ### 输出格式 - 修改代码时，先解释修改原因，再给出代码 - 给出代码后，说明如何验证修改是否正确 - 如果有多种实现方案，列出优缺点让我选择 ### 安全意识 - 任何涉及用户数据的操作，提醒我考虑隐私合规 - 发现潜在安全漏洞时，优先报告而不是直接修复 ### 我常用的工具 - 版本控制：Git - 容器：Docker + Docker Compose - CI/CD：GitHub Actions2.7 子目录 CLAUDE.md：模块级配置
对于大型项目，可以在特定子目录放置 CLAUDE.md，为该模块提供专属配置：
案例：前端子目录配置
项目结构： my-fullstack-app/ ├── CLAUDE.md ← 项目全局配置 ├── backend/ │ ├── CLAUDE.md ← 后端专属配置 │ └── src/ └── frontend/ ├── CLAUDE.md ← 前端专属配置 └── src/frontend/CLAUDE.md：
# 前端模块配置 ## 技术栈 - 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 ↓ 下次会话自动生效，无需重复说明手动触发记忆写入
# 在对话中明确要求 Claude 记住某件事用户：请记住，我们的 API 基础路径是 /api/v2，不是 /api/v1# Claude Code 会将此信息写入 CLAUDE.md2.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 是否生效
# 方法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
# 在你的项目根目录创建 CLAUDE.mdcdyour-projecttouchCLAUDE.md# 填写以下内容（根据实际情况修改）：cat>CLAUDE.md<<'EOF' # 项目名称 ## 技术栈 - 语言：[你的语言] - 框架：[你的框架] - 数据库：[你的数据库] ## 常用命令 - 启动：[启动命令] - 测试：[测试命令] - 构建：[构建命令] ## 开发规范 - [你的规范1] - [你的规范2] EOF练习2：验证记忆效果
# 启动 Claude Codeclaude# 测试1：询问技术栈用户：我们项目用什么语言？# 测试2：让 Claude 写代码，验证是否遵守规范用户：帮我写一个简单的 Hello World 函数# 观察 Claude 是否自动遵守了 CLAUDE.md 中的规范练习3：创建全局配置
mkdir-p~/.claudecat>~/.claude/CLAUDE.md<<'EOF' # 全局配置 ## 我的偏好 - 代码注释使用中文 - 修改代码前先解释原因 - 提供多种方案时列出优缺点 EOF⬅️ 上一章：第01章 - 底层技术全景导览
➡️ 下一章：第03章 - Sub-Agents 核心概念