第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 写了一个 用户 我们用 TypeScript2.2 四种记忆类型Claude Code 提供四种不同层次的记忆机制┌─────────────────────────────────────────────────────────┐ │ 记忆系统层次结构 │ │ │ │ ① 内存记忆In-Context Memory │ │ 当前会话的对话历史会话结束后消失 │ │ │ │ ② 外部记忆External Memory │ │ 文件系统中的持久化信息CLAUDE.md │ │ │ │ ③ 知识记忆Knowledge Memory │ │ 模型训练时学到的通用知识 │ │ │ │ ④ 缓存记忆Cached Memory │ │ Prompt Caching 缓存的 System Prompt │ └─────────────────────────────────────────────────────────┘各类型对比记忆类型持久性范围典型用途内存记忆会话内当前对话临时上下文、中间结果外部记忆永久项目/全局项目规范、团队约定知识记忆永久全局编程语言、框架知识缓存记忆会话间全局降低重复 Token 成本2.3 CLAUDE.md 核心概念什么是 CLAUDE.mdCLAUDE.md 是 Claude Code 的项目配置文件类似于.eslintrcESLint 规则配置pyproject.tomlPython 项目配置.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必须在事务中执行 - 使用异步 Sessionasync with AsyncSession() as session - 禁止在循环中执行数据库查询N1 问题 - 复杂查询必须添加适当索引并在 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--covsrc --cov-reporthtml类型检查mypy src/--strictGit 规范分支命名feature/xxx、fix/xxx、hotfix/xxx提交信息遵循 Conventional Commitsfeat: 添加用户注册功能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/CDGitHub 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.md100-300 行项目 CLAUDE.md200-500 行子目录 CLAUDE.md50-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 读的项目配置文件自然语言描述规范加载顺序全局→项目→子目录优先级递增内容合并配置内容技术栈、架构约定、禁止事项、常用命令AutoMemoryAI 主动将对话中的决策写入 CLAUDE.md 动手练习练习1为你的项目创建 CLAUDE.md# 在你的项目根目录创建 CLAUDE.mdcdyour-projecttouchCLAUDE.md# 填写以下内容根据实际情况修改catCLAUDE.mdEOF # 项目名称 ## 技术栈 - 语言[你的语言] - 框架[你的框架] - 数据库[你的数据库] ## 常用命令 - 启动[启动命令] - 测试[测试命令] - 构建[构建命令] ## 开发规范 - [你的规范1] - [你的规范2] EOF练习2验证记忆效果# 启动 Claude Codeclaude# 测试1询问技术栈用户我们项目用什么语言# 测试2让 Claude 写代码验证是否遵守规范用户帮我写一个简单的 Hello World 函数# 观察 Claude 是否自动遵守了 CLAUDE.md 中的规范练习3创建全局配置mkdir-p~/.claudecat~/.claude/CLAUDE.mdEOF # 全局配置 ## 我的偏好 - 代码注释使用中文 - 修改代码前先解释原因 - 提供多种方案时列出优缺点 EOF⬅️ 上一章第01章 - 底层技术全景导览➡️ 下一章第03章 - Sub-Agents 核心概念