目录
- 前言
- 1. 为什么"通用 AI"和"懂你的 AI"是两个物种
- 2. 三个层级的 CLAUDE.md
- 2.1 文件夹级（最高优先级）
- 2.2 项目级（团队共享）
- 2.3 全局级（个人偏好）
- 2.4 三层叠加生效
- 3. 用 /init 自动生成项目级 CLAUDE.md
- 3.1 /init 的工作原理
- 3.2 /init 之后必做：人工校对
- 4. 模板实战：5 个必写模块
- 4.1 技术栈（写明版本号）
- 4.2 目录结构
- 4.3 编码规范
- 4.4 当前进度
- 4.5 禁忌清单（最少被问到的问题）
- 5. 第二层记忆：Auto Memory
- 5.1 启用 Auto Memory
- 5.2 Auto Memory 会记什么
- 5.3 Auto Memory 的使用手感
- 5.4 CLAUDE.md vs Auto Memory 的本质区别
- 6. 最佳实践：只放"顶层不变原则"
- 结语
- 参考资料
前言
你有没有过这种经历：明明昨天才告诉 Claude Code “我们项目用 TypeScript 严格模式”，今天开新会话它又问"用 JavaScript 还是 TypeScript"？明明上次你吐槽过"不要用 class 组件"，它这次又写了一个？
这不是 AI 记性差，而是你没有给它一个记笔记的地方。
解决方案就是CLAUDE.md——一个放在项目里的"记忆文件"。这一篇我会彻底讲清楚：它分几层、怎么用、有多强大。
1. 为什么"通用 AI"和"懂你的 AI"是两个物种
先举一个反例。
假设你正在做一个电商网站，前端用 Next.js 14 + TypeScript，后端用 Next.js API Routes，数据库是 Prisma + PostgreSQL，UI 组件库用 shadcn/ui，代码风格要求函数式组件、API 返回统一格式{ success, data, error }。
不开 CLAUDE.md 的对话：
你：帮我加一个商品分类的 CRUD 接口 AI：好的，请问你用什么技术栈？后端用 Express 还是 Koa？数据库用 MySQL 还是 MongoDB？ 你：Next.js API Routes + Prisma + PostgreSQL AI：好的。请问命名规范呢？返回值格式有要求吗？ 你：函数式、{success, data, error} AI：好的，请问 UI 用什么组件库？ 你：shadcn/ui ... （光是把项目背景讲一遍就花了 5 分钟）开了 CLAUDE.md 之后的对话：
你：帮我加一个商品分类的 CRUD 接口 AI：好的，我看到项目用 Prisma + PostgreSQL，命名规范是函数式、{success, data, error} 格式。 我会按这些规范写，预计要改两个文件：/api/admin/categories/route.ts 和 /app/admin/categories/page.tsx。是否开始？ 你：开始差距显而易见：CLAUDE.md 把"反复解释"变成了"自动理解"。它不是省了几句话的事，而是把你的项目从"AI 的一次性外包"变成"AI 长期协作的同事"。
打个比方：通用 AI 就像你每天去医院都要重新跟医生说一遍病史；懂你的 AI 就像你的家庭医生，他有一份完整的病历档案。
2. 三个层级的 CLAUDE.md
官方为 CLAUDE.md 设计了三个层级，它们会同时生效、不冲突。下面我按从高到低的优先级讲解。
2.1 文件夹级（最高优先级）
放在某个子目录下的 CLAUDE.md。比如：
src/payment/CLAUDE.md—— 写支付模块踩过的坑src/components/admin/CLAUDE.md—— 写后台组件的命名约定prisma/CLAUDE.md—— 写数据库迁移的注意事项
当 Claude Code 在这个目录下工作时，会自动读取这一层。它的优先级最高，因为它最贴近当前任务的上下文。
2.2 项目级（团队共享）
放在项目根目录的 CLAUDE.md（不是.claude/文件夹下）。它的内容通常是：
- 项目技术栈（具体到版本号）
- 项目目录结构
- 编码规范
- 当前开发状态
- 注意事项和禁区
这一层可以提交到 Git，团队成员共享。它是 CLAUDE.md 体系的核心。
2.3 全局级（个人偏好）
放在~/.claude/CLAUDE.md（用户主目录下）。它对所有项目都生效，适合写个人偏好：
- “请永远用中文回答”
- “我是前端工程师，主要做 React 项目”
- “不要给我看 emoji”
- “解释代码时请用比喻，不要用术语堆砌”
2.4 三层叠加生效
三层 CLAUDE.md 不是互斥的，而是叠加生效。优先级是：文件夹级 > 项目级 > 全局级。
举个例子：
- 全局级说：“我喜欢用中文回答”
- 项目级说：“API 返回 { success, data, error }”
- 文件夹级说：“payment 模块必须用事务”
当你在src/payment/目录下让 AI 写支付逻辑时，它会同时遵守这三条——中文回答、统一返回格式、用事务。
关键认知：CLAUDE.md 的"三层"不是选一个用，而是像乐高积木一样叠加。你可以一层都不写（裸用），也可以三层都写（强定制）。一般建议至少写项目级这一层。
3. 用 /init 自动生成项目级 CLAUDE.md
如果你不知道 CLAUDE.md 该写什么，最简单的姿势是用 Claude Code 的/init命令。
3.1 /init 的工作原理
进入项目目录，启动 Claude Code：
$cd~/my-project $ claude在提示符输入：
/initClaude Code 会启动一个只读的分析过程：
- 扫描项目目录结构
- 读取
package.json（如果有） - 读取关键配置文件（如
tsconfig.json、tailwind.config.js） - 推测项目的技术栈和约定
- 在项目根目录生成一份
CLAUDE.md初稿
3.2 /init 之后必做：人工校对
/init生成的是机器视角的 CLAUDE.md——它可能漏掉一些只有你知道的事。比如：
- “这个项目还在开发中，不要修改
prisma/migrations/2024xxx/下的迁移文件” - “部署到 Vercel，环境变量在 Vercel 控制台管理”
- “团队约定：所有 PR 必须经过另一个工程师 review”
你需要在生成的基础上手动补充这些"只有人才知道的上下文"。我个人的经验是：先/init，再花 5-10 分钟调整。
提示：官方建议项目有一定规模再
/init效果更好。一个空目录让 AI 扫，它扫不出什么东西，生成的 CLAUDE.md 会很空。
4. 模板实战：5 个必写模块
下面是我在真实项目里用的 CLAUDE.md 模板，按 5 个模块组织。你可以直接复制，再根据自己项目修改。
4.1 技术栈（写明版本号）
## 技术栈 - 框架：Next.js 16 (App Router) + TypeScript 5 - 样式：TailwindCSS 4 - 数据库：Prisma 5 + SQLite（开发）/ PostgreSQL（生产） - 认证：自制 Cookie Session + bcryptjs - 测试：Vitest + Testing Library为什么必须写版本号？不同版本 API 差异巨大。比如 Next.js 13→14 升级时，App Router 的 params 从同步改成异步。不写版本号，AI 可能用过时的 API 写代码。
4.2 目录结构
## 项目结构 src/ ├── app/ # Next.js App Router 页面 │ ├── api/ # API 路由 │ └── (admin)/ # 后台页面分组 ├── components/ # React 组件 │ ├── ui/ # 通用 UI 组件 │ └── features/ # 业务组件 ├── lib/ # 工具函数 └── prisma/ # 数据库 schema4.3 编码规范
## 编码规范 - 组件：函数式 + React Hooks，不使用 class 组件 - 文件命名：kebab-case（如 product-card.tsx） - 组件命名：PascalCase（如 ProductCard） - API 返回统一格式：{ success: boolean, data?: any, error?: string } - 错误处理：使用 try-catch，错误统一抛到 API 层4.4 当前进度
## 当前开发状态 - [x] 项目初始化 - [x] 数据库 Schema 设计 - [/] 商品 CRUD API（进行中） - [ ] 购物车功能 - [ ] 订单系统 - [ ] 部署上线这一段的作用是让 AI 知道项目当前在哪里。你今天做完一个功能，就更新一下进度；明天 AI 接手时就不会"失忆"。
4.5 禁忌清单（最少被问到的问题）
## 注意事项 - 不要修改 prisma/migrations/ 下的迁移文件 - 不要把 .env 提交到 Git - 密码字段永远不通过 API 返回 - 修改数据库前先和团队确认 - 所有新功能先创建 Git 分支再开发经验：禁忌清单是性价比最高的部分。AI 经常会做一些"看起来合理但不符合项目惯例"的事——比如把数据库密码写进前端代码。禁忌清单能 80% 地避免这种问题。
5. 第二层记忆：Auto Memory
CLAUDE.md 写好了，但有些事情你没意识到要写，AI 怎么记？
这就是 Auto Memory 的价值——它是 Claude Code 自己的笔记本。
5.1 启用 Auto Memory
在 cc 会话中输入：
/memory在弹出的菜单里选第一个选项"启用 Auto Memory"。启用后菜单里会多出"打开自动记忆文件夹"选项。
5.2 Auto Memory 会记什么
Auto Memory 会在四种情况下自动记录：
| 类型 | 含义 | 举例 |
|---|---|---|
user | 关于你 | 你的角色、偏好（如"不喜欢深色 UI"） |
feedback | 你给过的反馈 | “不要这样做”、“对，就这样” |
project | 项目相关 | 进度、决策、技术选型 |
reference | 外部资源索引 | “某份设计文档在 docs/design.md” |
典型场景：你今天告诉 Claude Code “我们项目用 TailwindCSS 4，不要写 CSS 文件”。一周后开新会话，你没在 CLAUDE.md 里写这条——但 Auto Memory 记下了，所以 AI 不会犯老错误。
5.3 Auto Memory 的使用手感
几个重要细节：
- 它只在当前项目生效（文件存在项目目录下），换项目需重新积累
- 启用后 cc不会每次都把所有记忆全部加载进上下文，只会读一份
memory.md索引——遇到具体问题才去读对应的子文件，占 token 很少 - 随时可以按
Ctrl+O在会话中查看实际被调用过的记忆内容 - 记错了就直接跟它说：“忘掉刚刚说的不喜欢深色主题”，它会自己删掉
5.4 CLAUDE.md vs Auto Memory 的本质区别
一句话总结：CLAUDE.md 是你主动立下的规矩，Auto Memory 是 AI 默默记下的笔记。
- CLAUDE.md：第一优先级、全量注入的明规则
- Auto Memory：第二优先级、按需注入的隐规则
两者配合，cc 越用越懂你。
6. 最佳实践：只放"顶层不变原则"
最后说一个反直觉的真相：CLAUDE.md 越短越好。
很多新手喜欢往 CLAUDE.md 里塞 200 行——每一条规范都写进去。结果呢？AI 反而表现变差。因为：
- 太长导致 AI 注意力分散——规范太多，AI 会"挑着遵守"
- 太具体导致维护成本高——你换了一个库，规范就过时了
- 太多规则相互冲突——比如"用 functional programming"和"用面向对象设计模式"很难同时遵守
卡帕西（Andrej Karpathy，AI 大牛）发布的「claude.skills」项目只有几百行通用规则，却在 GitHub 拿了 10 万+ Star。他的核心思路是：只写"顶层、不变、必须严守"的东西。
那什么是"顶层不变原则"？我自己的判断标准有 3 条：
- 跨会话不变：不管我今天做什么项目，这条规则都适用
- 跨任务不变：不管是写前端还是后端，这条规则都成立
- 违反后果严重：如果 AI 不遵守，会出大乱子
举几个符合这 3 条的例子：
- “密码字段永远不通过 API 返回”——跨会话、跨任务、违反后果严重 ✓
- “不要把 .env 提交到 Git”——跨会话、跨任务、违反后果严重 ✓
- “所有 API 返回统一 { success, data, error } 格式”——跨任务，但不算"严重"，可以放项目级
举几个不该放进 CLAUDE.md 的例子：
- “按钮的圆角用 rounded-md”——太具体，UI 风格会变
- “购物车要支持优惠券”——这是产品需求，不是规范
- “PostgreSQL 用 15 版本”——太具体，部署时再说
多体素原则（Multi-Voxel Principle）：把项目知识切成独立的小块（体素），需要时按需加载，而不是一次性全塞进大脑。
结语
CLAUDE.md 三层记忆系统是 Claude Code 最被低估的功能之一。很多人装了 Claude Code 却不用 CLAUDE.md，结果每周都要花几十分钟重复解释项目背景。
我的建议是：
- 第一个项目——用
/init生成项目级 CLAUDE.md，5 分钟校对 - 每周——花 10 分钟更新"当前进度"和"禁忌清单"两个模块
- 每月——清理一次全局 CLAUDE.md，把过时的个人偏好删掉
这个习惯坚持一个月，你会发现 Claude Code 的"反应"越来越像你肚子里的蛔虫。
参考资料
1 https://www.bilibili.com/video/BV1RPET6tEp2
2 https://claude.ai/
