CLAUDE.md 记忆系统

为什么它是项目中最重要的文件

Claude Code 每次启动时，会自动读取项目根目录下的 CLAUDE.md 文件。这个文件相当于你给 Claude 的"项目地图"——告诉它这个项目是什么、怎么开发、有哪些坑要避免。

没有 CLAUDE.md 的时候，Claude 每次都要重新理解你的项目。有了它，Claude 一进来就知道：

用什么命令启动开发服务器
代码风格有什么要求
哪些操作绝对不能做
之前踩过哪些坑

这就是为什么老手的第一件事永远是写好 CLAUDE.md——它能让你跟 Claude 的每次对话都站在更高的起点上。

从护栏开始，别写手册

很多人一上来就想把 CLAUDE.md 写成一个完整的项目文档。不要这样做。

CLAUDE.md 的核心目的是记录 Claude 容易犯的错误，而不是写一份完整的技术文档。Claude 已经懂很多东西了，你不需要教它什么是 React。

正确的思路：每次 Claude 犯了一个错误，你就在 CLAUDE.md 里加一条。比如：

Claude 老是用 npm 但你的项目用 pnpm → 加一条
Claude 喜欢给函数加多余的 try-catch → 加一条
Claude 总是忘记你的项目用了特殊的目录结构 → 加一条

这些"护栏"比任何文档都有用。

该写什么 / 不该写什么

该写	不该写
开发命令（`pnpm dev`、`pnpm test`）	完整的 API 文档
代码风格规范（命名规则、import 顺序）	项目架构全文描述
常见陷阱（"不要用 `any` 类型"）	第三方库的使用教程
不要做的事情（"不要修改 migration 文件"）	临时的调试信息
项目特殊约定（"路由文件都放在 app/ 下"）	已经过时的信息
环境配置要点（"数据库用远程 Supabase"）	所有文件的详细说明

原则：写 Claude 不知道的、容易搞错的东西。它已经知道的，不用重复。

完整 CLAUDE.md 示例

下面是一个 Next.js + Drizzle 项目的真实 CLAUDE.md，你可以参考这个格式：

# CLAUDE.md

## 项目概述
技能范（SkillsFan）是一个 AI 技能库平台，基于 Next.js 16 + Drizzle ORM + Supabase。

## 开发命令
- `pnpm dev` — 启动开发服务器（Turbopack）
- `pnpm build` — 生产构建
- `pnpm db:generate` — 生成数据库迁移
- `pnpm db:migrate` — 执行迁移
- `pnpm db:studio` — 打开数据库管理界面
- `pnpm lint` — 代码检查
- `pnpm format` — 格式化代码

## 代码风格
- 使用 TypeScript，严格模式
- 组件用函数式写法，不用 class
- 样式用 Tailwind CSS，不写自定义 CSS
- import 顺序：React → 第三方库 → 内部模块 → 类型
- 文件命名：组件用 PascalCase，工具用 kebab-case

## 常见陷阱
- 数据库用远程 Supabase，首次连接可能慢 2-5 秒，不要以为是 Bug
- 修改 schema 后必须跑 `pnpm db:generate && pnpm db:migrate`
- `public/imgs/` 有强缓存，换图片要改文件名
- 构建时 `scripts/` 目录不参与编译，不要从 src 里 import scripts 的内容

## 不要做
- 不要用 `npm`，这个项目用 `pnpm`
- 不要修改 `src/config/db/migrations/` 下的已有迁移文件
- 不要在组件里直接操作数据库，通过 `src/shared/models/` 的函数
- 不要用 `any` 类型，实在不知道类型就用 `unknown`
- 不要主动 push 到 GitHub，等我确认

注意几个特点：

简洁：整个文件不到 50 行，大约 2000 tokens
可操作：每一条都是明确的指令，不是模糊的描述
负面清单："不要做"列表往往比"要做"列表更有用

层级结构

CLAUDE.md 支持多级放置，Claude 会按优先级读取：

~/.claude/CLAUDE.md              ← 全局配置，所有项目生效
项目根目录/CLAUDE.md              ← 项目级配置，最常用
项目根目录/src/CLAUDE.md          ← 子目录级，针对特定模块
项目根目录/tests/CLAUDE.md        ← 子目录级，针对测试规范

全局 ~/.claude/CLAUDE.md：写你的个人偏好，比如"始终用中文回复"、"commit message 用英文"等。这些在所有项目中都生效。

项目根目录 CLAUDE.md：写项目相关的配置，这是最核心的文件。

子目录 CLAUDE.md：当某个子目录有特殊规则时使用。比如 tests/CLAUDE.md 里可以写："测试文件命名用 *.test.ts 格式，每个测试用 describe + it 结构"。

你还可以在 CLAUDE.md 中用 @ 引用其他文件：

## 详细架构
@docs/architecture.md

这样可以把长内容拆分出去，保持 CLAUDE.md 主文件的精简。

Auto Memory：自动记忆

除了手写 CLAUDE.md，Claude Code 还有一个自动记忆系统（Auto Memory）。当你在对话中纠正 Claude 的行为时，它会自动把这些纠正记录下来，下次不再犯同样的错。

维度	手写 CLAUDE.md	Auto Memory
适合内容	项目规则、开发命令、架构约定	个人偏好、交互习惯、临时纠正
存储位置	项目根目录 `CLAUDE.md`	`~/.claude/memory/` 目录
维护方式	手动编辑	Claude 自动添加
生效范围	当前项目	所有项目（全局）
适合场景	团队协作、项目规范	个人使用习惯

两者是互补的关系：

CLAUDE.md 是你主动写的"项目宪法"，团队成员都能看到和遵守
Auto Memory 是 Claude 自动积累的"个人笔记"，记录你的个人习惯

迭代飞轮

不要期望一次就写出完美的 CLAUDE.md。它是一个渐进迭代的过程：

第一周：空文件起步

# CLAUDE.md
## 开发命令
- `pnpm dev` — 启动开发服务器

就这么一条也行。先建上这个文件，习惯它的存在。

第二周：护栏初现

Claude 犯了几次错后，你开始往里加规则：

## 不要做
- 不要用 npm，用 pnpm
- 不要在 API 路由里写业务逻辑，放 services 目录

第一个月：飞轮启动

文件慢慢丰富起来，Claude 的表现也越来越好。你发现跟 Claude 协作的效率明显提高了——很多之前要反复纠正的问题，现在一次都不出了。

# CLAUDE.md
## 项目概述
[...]
## 开发命令
[...]
## 代码风格
[...]
## 常见陷阱
[...]
## 不要做
[...]

之后：持续迭代

每隔一两周审视一下 CLAUDE.md：

删掉已经不适用的规则
合并重复的条目
补充新发现的陷阱

[!NOTE] 保持精简很重要。太长的 CLAUDE.md 反而会降低效果——Claude 的注意力也是有限的，关键信息会被淹没在大量文字中。建议控制在 2500 tokens 以内（大约 50-80 行）。

一句话总结

空文件开始，每次犯错加一条，保持精简。

不需要一上来就写得很完善。跟 Claude 协作的过程本身就在帮你积累这些规则。你的 CLAUDE.md 会随着项目一起成长，最终变成团队最有价值的文档之一。

CLAUDE.md 记忆系统

On this page