AI编程系列之6：CLAUDE.md 三层记忆系统——让 AI 真正“懂“你的项目

cooldream2009

567人浏览 · 2026-07-11 08:41:13

cooldream2009 · 2026-07-11 08:41:13 发布

前言

你有没有过这种经历：明明昨天才告诉 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

在提示符输入：

/init

Claude 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/      # 数据库 schema

4.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”