【Claude】Claude Code CLAUDE.md 记忆系统完全指南：让 AI 永远记得你的项目规范

【Claude】Claude Code CLAUDE.md 记忆系统完全指南：让 AI 永远记得你的项目规范

前言

你有没有遇到过这种场景：明明上次已经告诉 Claude"我们项目用 TypeScript strict 模式"，下次开新对话时它又开始写没有类型注解的代码？或者每次都要重复解释"我们用 Jest 做测试，不用 Vitest"？

这是因为 Claude Code 的每个会话都是独立的——没有跨会话记忆机制，除非你主动配置。

CLAUDE.md 记忆系统就是解决这个问题的官方方案。通过在项目中放置结构化的 Markdown 文件，你可以让 Claude 在每次会话开始时都自动加载项目背景、编码规范、架构约定，不再需要每次重复说明。

本文基于官方文档与社区最佳实践，带你从零搭建一套高效的 CLAUDE.md 记忆系统。

一、问题现象：为什么需要记忆系统？

1.1 三大典型痛点

痛点一：规范重复解释

第1次对话：Claude, 我们项目用 Python 3.11，包管理器是 uv，不用 pip 第2次对话：Claude 又推荐用 pip install... 第3次对话：Claude 又推荐 pip install...

痛点二：架构决策遗忘

你们的 API 路由都在 /app/routers/ 下，用 FastAPI Claude 写新功能时建了一个新的 routes/ 目录，打破了项目结构

痛点三：特殊规则无从传递

"禁止直接操作数据库，必须通过 Repository 层" "认证逻辑在 /app/auth/ 目录，不要在业务层重复实现" 这些隐性规则只存在于老员工的脑袋里，Claude 不知道

1.2 记忆系统解决了什么

二、核心概念：记忆层级结构

2.1 四层记忆优先级

Claude Code 会自动读取以下位置的记忆文件，优先级从高到低：

优先级 1（最高）：企业级策略 来源：系统管理员配置，只读，不可覆盖 优先级 2：用户级 CLAUDE.md 路径：~/.claude/CLAUDE.md 作用：对该用户的所有项目生效 内容：个人偏好、常用工具、通用编码风格 优先级 3：项目级 CLAUDE.md 路径：[项目根目录]/CLAUDE.md 作用：对当前项目所有成员生效 内容：项目规范、架构说明、禁止操作 优先级 4：子目录 CLAUDE.md 路径：src/CLAUDE.md, tests/CLAUDE.md 等 作用：仅在处理该目录文件时加载 内容：该模块的特殊规则

加载时机：每次新会话开始时，Claude 会自动扫描并加载所有层级的 CLAUDE.md 文件。无需任何命令触发。

2.2 优先级冲突规则

当不同层级存在冲突指令时，更具体的层级优先：

~/.claude/CLAUDE.md 说：代码注释用英文 src/api/CLAUDE.md 说：API 模块注释用中文（面向国内团队） 结果：在 src/api/ 目录工作时，优先使用中文注释

三、快速上手：使用 /init 自动生成

3.1 /init 命令

最快速的入门方式是使用内置命令：

# 启动 Claude Code claude # 在对话中输入 /init

Claude 会自动：

1. 扫描项目目录结构
2. 检测技术栈（语言、框架、测试工具、构建系统）
3. 读取现有配置文件（package.json, pyproject.toml, etc.）
4. 生成一份 80% 完整度的 CLAUDE.md 骨架

示例：在 Node.js 项目中执行 /init 的输出

# 项目概述 电商平台后端 API，基于 Express + TypeScript # 技术栈 - 运行时：Node.js 20 LTS - 语言：TypeScript 5.x（strict 模式） - 框架：Express 4.x - 数据库：PostgreSQL 16 + Prisma ORM - 测试：Jest + Supertest - 包管理：pnpm # 构建命令 - 开发：`pnpm dev` - 构建：`pnpm build` - 测试：`pnpm test` - 类型检查：`pnpm type-check` # 项目结构（自动检测） src/ ├── routes/ # API 路由定义 ├── controllers/ # 业务逻辑 ├── services/ # 服务层 ├── models/ # 数据模型（Prisma） └── middleware/ # 中间件

3.2 手动创建

touch CLAUDE.md # 然后按下文模板编辑

四、CLAUDE.md 最佳结构模板

以下是经过社区验证的高效模板，适合大多数项目：

4.1 通用模板

# 项目名称 - Claude Code 记忆文件 ## 项目概述 [用 2-3 句话说清楚这是什么系统、面向什么用户、核心价值是什么] ## 技术栈 - 语言：[Python 3.11 / TypeScript 5.x / Go 1.22] - 框架：[FastAPI / Next.js 14 / Gin] - 数据库：[PostgreSQL + SQLAlchemy / MySQL + Prisma] - 缓存：[Redis 7] - 测试：[pytest / Jest / Go test] - 包管理：[uv / pnpm / go modules] - 部署：[Docker + k8s / Vercel / AWS] ## 常用命令 ```bash # 启动开发环境 [命令] # 运行测试 [命令] # 代码检查 [命令] # 构建产物 [命令]

项目结构

[重要目录的说明，只列核心目录，不要全量列出] src/ ├── [目录名]/ # [用途说明] └── ...

编码规范

• [规则1：如"函数命名用 snake_case"]
• [规则2：如"每个函数必须有类型注解"]
• [规则3：如"错误必须通过自定义 Exception 类抛出"]

架构约定

• [约定1：如"不允许在 Controller 层直接操作数据库，必须经过 Service 层"]
• [约定2：如"认证逻辑统一在 middleware/auth.py，不在业务代码里重复"]

禁止操作

• [❌ 禁止在代码里硬编码密钥或密码]
• [❌ 禁止直接修改 migration 文件，必须用 alembic 命令生成]
• [❌ 禁止绕过 Service 层直接查数据库]

重要注意事项

• [特殊约束1]
• [特殊约束2]

### 4.2 前端项目模板（React/Next.js） ```markdown # 前端项目记忆文件 ## 技术栈 - 框架：Next.js 14（App Router） - 语言：TypeScript 5.x，strict: true - 样式：Tailwind CSS 3.x，禁止使用内联 style - 状态管理：Zustand（不用 Redux） - 数据获取：TanStack Query v5 - 表单：React Hook Form + Zod 校验 - UI 组件：shadcn/ui（已安装的组件在 components/ui/） - 测试：Vitest + Testing Library - 包管理：pnpm ## 重要约定 - 所有页面组件放在 app/ 目录（App Router 结构） - 可复用组件放在 components/（非 UI 库的自定义组件） - 服务端组件优先，只有需要交互的才加 "use client" - API 调用统一在 lib/api/ 目录，不在组件里直接 fetch - 环境变量：服务端用 process.env.XXX，客户端必须加 NEXT_PUBLIC_ 前缀 ## 命令 ```bash pnpm dev # 开发 pnpm build # 构建 pnpm test # 测试（Vitest） pnpm lint # ESLint 检查 pnpm type-check # TypeScript 类型检查

禁止操作

• ❌ 禁止使用 any 类型（strict 模式，会报错）
• ❌ 禁止在 Server Component 里用 useState/useEffect
• ❌ 禁止在 app/ 目录之外使用 Next.js 路由文件名（page.tsx, layout.tsx）
• ❌ 禁止直接修改 public/ 里的静态资源，要走资源管理流程

### 4.3 后端 Python 项目模板（FastAPI） ```markdown # FastAPI 项目记忆文件 ## 技术栈 - 语言：Python 3.11 - 框架：FastAPI 0.111 - ORM：SQLAlchemy 2.x（异步）+ Alembic 数据库迁移 - 包管理：uv（不用 pip） - 测试：pytest + httpx（异步） - 代码风格：black + isort + ruff - 类型检查：mypy（strict 模式） ## 项目结构 app/ ├── api/ # 路由定义（每个模块一个文件） ├── core/ # 核心配置（settings, db, security） ├── models/ # SQLAlchemy 模型 ├── schemas/ # Pydantic 请求/响应模型 ├── services/ # 业务逻辑（不要在 api/ 里写业务代码） ├── repositories/ # 数据访问层（不要直接在 service 里用 session） └── tests/ # 测试文件，结构镜像 app/ ## 命令 ```bash uv run uvicorn app.main:app --reload # 开发 uv run pytest # 测试 uv run alembic upgrade head # 数据库迁移 uv run ruff check . # Lint uv run mypy app/ # 类型检查

严格约束

• ❌ 禁止在 api/ 层直接操作数据库，必须通过 service → repository
• ❌ 禁止在模型层写业务逻辑
• ❌ 禁止使用同步的数据库操作（必须用 async/await）
• ✅ 所有 API 响应必须用 Pydantic Schema 序列化，禁止返回 ORM 对象
• ✅ 错误码统一定义在 app/core/exceptions.py

--- ## 五、用户级 CLAUDE.md：个人偏好配置 `~/.claude/CLAUDE.md` 对所有项目生效，适合放个人偏好： ```markdown # 个人偏好配置 ## 沟通风格 - 回答尽量简洁，不要重复问题内容 - 代码注释用中文（我的团队是中文环境） - 解释技术概念时举具体例子，不要只说理论 ## 代码风格偏好 - 函数尽量短小，超过 30 行考虑拆分 - 变量名要有意义，不用单字母变量（循环索引除外） - 优先用函数式写法（map/filter/reduce）而不是命令式循环 ## 工具偏好 - 包管理：Python 项目用 uv，Node 项目用 pnpm - 编辑器：VSCode，配置在 .vscode/ - Shell：zsh + oh-my-zsh，配置在 ~/.zshrc ## 常用路径 - 项目目录：~/projects/ - 脚本目录：~/scripts/ - 配置备份：~/dotfiles/ ## 注意事项 - 我的电脑是 Apple Silicon Mac，注意 arm64 兼容性 - Docker 用 OrbStack，不是 Docker Desktop - 如果需要安装软件，优先用 brew

六、子目录 CLAUDE.md：模块级规则

在特定子目录放置 CLAUDE.md，可以为该模块设置专属规则：

示例：src/auth/CLAUDE.md

# 认证模块特殊规则 ## 重要提醒 这是安全敏感模块，修改前请仔细评估影响。 ## 模块职责 - 唯一负责用户身份认证、JWT 生成与验证 - 所有认证相关逻辑只能在这个目录下实现 ## 安全要求 - ❌ 绝对禁止在日志中打印 token 或密码（即使是调试日志） - ❌ 禁止明文存储密码，必须用 bcrypt/argon2 哈希 - ✅ 所有密码相关操作用 constant-time 比较防止时序攻击 - ✅ JWT 过期时间：access token 15分钟，refresh token 7天 ## 测试要求 安全模块的每个函数都必须有对应的单元测试，覆盖率 > 95%。

示例：tests/CLAUDE.md

# 测试目录规则 ## 测试约定 - 测试文件命名：test_[被测模块名].py - 每个测试函数名：test_[功能]_[场景]_[期望结果] 示例：test_login_with_invalid_password_returns_401 ## 测试原则 - 每个测试只测一件事 - 使用 Fixtures，不要在 test 函数里写初始化逻辑 - Mock 外部依赖（数据库、HTTP 请求），不在测试里访问真实服务 ## 禁止操作 - ❌ 禁止在测试里使用真实的数据库连接 - ❌ 禁止测试函数超过 50 行（拆分逻辑到 helpers）

七、Auto Memory：自动记忆更新

7.1 什么是 Auto Memory

Claude Code 支持在对话中自动更新 CLAUDE.md 记忆——当你明确说"记住这个规则"时，Claude 会直接修改记忆文件：

你：记住，我们的 API 统一用 v2 前缀，比如 /api/v2/users Claude：好的，我已将这条规则添加到 CLAUDE.md： "所有 API 端点必须使用 /api/v2/ 前缀"

7.2 手动触发记忆更新

你：把刚才我们讨论的数据库 Schema 设计原则写到 CLAUDE.md 你：更新记忆文件，我们决定不再用 Redux，改用 Zustand 你：在 CLAUDE.md 里记录一下：auth 模块不能被其他模块 import，只能通过事件总线通信

7.3 查看当前记忆内容

你：显示当前加载的所有记忆文件内容 你：当前 CLAUDE.md 的认证相关规则有哪些？

八、性能优化：避免 CLAUDE.md 过于臃肿

8.1 CLAUDE.md 的黄金法则

官方建议：CLAUDE.md 控制在 200 行以内

一旦超过这个长度，Claude 反而会忽略重要内容（因为 token 预算有限，靠后的内容权重降低）。

该写的内容：

• ✅ 构建、测试、lint 命令（最高价值，每次都用到）
• ✅ 关键架构决策（"我们用 monorepo"、"Service 层强制隔离"）
• ✅ 不明显的技术陷阱（"TypeScript strict 模式开了"、"用的是 CJS 而不是 ESM"）
• ✅ 禁止操作清单（越具体越好）
• ✅ 项目特有的命名规范

不该写的内容：

• ❌ 能从配置文件中读取的信息（package.json 里的依赖版本）
• ❌ 完整的 API 文档（放到 docs/ 目录）
• ❌ 讲理论的长段落（只写结论，不写推导过程）
• ❌ 编程语言基础知识（Claude 本身就懂）

8.2 用 @文件引用代替内联内容

当需要提供详细文档时，使用引用而不是粘贴：

## API 设计规范 详见：[docs/api-design.md](docs/api-design.md) ## 数据库 Schema 详见：[docs/database-schema.md](docs/database-schema.md)

这样 CLAUDE.md 保持简短，详细文档在需要时再引用。

8.3 按使用频率排序

把最常用的信息放在文件顶部。Claude 的注意力对文件开头部分更强：

# 最高频使用（放顶部） ## 常用命令 ... # 中频使用 ## 编码规范 ... # 低频参考 ## 部署说明 ...

九、团队协作实践

9.1 文件提交策略

提交到 git（团队共享）： ✅ CLAUDE.md（根目录） ✅ src/*/CLAUDE.md（子目录规则） ✅ .claude/settings.json 不提交 git（个人配置）： ❌ ~/.claude/CLAUDE.md（个人偏好） ❌ .claude/settings.local.json（本地配置）

9.2 新成员入职流程

将 CLAUDE.md 纳入入职必读材料：

## 新同学必读 请在第一次使用 Claude Code 前阅读本文件。 关键约定： 1. 所有功能开发必须在 feature/ 分支进行 2. PR 合并前必须通过 CI（包括测试和类型检查） 3. 数据库变更必须附带 migration 文件 4. 不懂的地方先问团队，不要让 Claude 自己猜

9.3 记忆文件版本控制

像对待代码一样对待 CLAUDE.md：

# 更新记忆文件后，写清楚变更原因 git commit -m "docs(claude): 添加新的认证模块隔离规则 背景：#123 issue 中发现 auth 模块被业务层直接 import 导致循环依赖 变更：明确禁止其他模块直接 import auth，改用事件总线"

十、验证记忆是否生效

10.1 验证方法

开启新会话后，问 Claude： "我们项目用什么包管理器？" "API 路由应该放在哪个目录？" "提交代码前需要做什么检查？" 如果 Claude 能正确回答，说明记忆文件已正常加载。

10.2 诊断加载失败

如果记忆没有生效，按以下顺序检查：

1. 文件路径正确：确保 CLAUDE.md 在项目根目录（而不是 .claude/ 子目录）
2. 文件编码：必须是 UTF-8，不能有 BOM
3. 文件不能为空：至少要有实质性内容（纯注释不会被加载）
4. 项目目录匹配：确认你在正确的目录下启动 Claude Code

# 查看当前工作目录 pwd # 确认 CLAUDE.md 存在 ls -la CLAUDE.md # 查看文件内容 cat CLAUDE.md | head -20

总结

CLAUDE.md 记忆系统是让 Claude Code 真正成为"项目专属 AI 助手"的关键：

1. 四层结构（企业 > 用户 > 项目 > 子目录）满足从个人到团队的不同需求
2. 200 行黄金法则确保记忆内容被完整读取
3. /init 命令帮助快速生成骨架，然后手动补充关键约束
4. 子目录 CLAUDE.md为敏感模块（如 auth）提供更强的安全约束

把规范写进 CLAUDE.md，而不是每次在对话里重复——这是与 Claude Code 高效协作的第一步，也是最重要的一步。