【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 记忆系统解决了什么问题类型没有记忆系统有 CLAUDE.md技术栈信息每次都要说自动加载项目结构Claude 自己探索可能出错直接告知编码规范代码风格不一致统一执行禁止操作靠运气明确约束常用命令靠记忆或查文档随时可用二、核心概念记忆层级结构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 # 在对话中输入 /initClaude 会自动扫描项目目录结构检测技术栈语言、框架、测试工具、构建系统读取现有配置文件package.json, pyproject.toml, etc.生成一份 80% 完整度的 CLAUDE.md 骨架示例在 Node.js 项目中执行 /init 的输出# 项目概述 电商平台后端 API基于 Express TypeScript # 技术栈 - 运行时Node.js 20 LTS - 语言TypeScript 5.xstrict 模式 - 框架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 14App Router - 语言TypeScript 5.xstrict: 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 - ORMSQLAlchemy 2.x异步 Alembic 数据库迁移 - 包管理uv不用 pip - 测试pytest httpx异步 - 代码风格black isort ruff - 类型检查mypystrict 模式 ## 项目结构 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 项目用 uvNode 项目用 pnpm - 编辑器VSCode配置在 .vscode/ - Shellzsh 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 MemoryClaude 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 诊断加载失败如果记忆没有生效按以下顺序检查文件路径正确确保 CLAUDE.md 在项目根目录而不是 .claude/ 子目录文件编码必须是 UTF-8不能有 BOM文件不能为空至少要有实质性内容纯注释不会被加载项目目录匹配确认你在正确的目录下启动 Claude Code# 查看当前工作目录 pwd # 确认 CLAUDE.md 存在 ls -la CLAUDE.md # 查看文件内容 cat CLAUDE.md | head -20总结CLAUDE.md 记忆系统是让 Claude Code 真正成为项目专属 AI 助手的关键四层结构企业 用户 项目 子目录满足从个人到团队的不同需求200 行黄金法则确保记忆内容被完整读取/init 命令帮助快速生成骨架然后手动补充关键约束子目录 CLAUDE.md为敏感模块如 auth提供更强的安全约束把规范写进 CLAUDE.md而不是每次在对话里重复——这是与 Claude Code 高效协作的第一步也是最重要的一步。