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

目录前言1. 为什么通用 AI和懂你的 AI是两个物种2. 三个层级的 CLAUDE.md2.1 文件夹级最高优先级2.2 项目级团队共享2.3 全局级个人偏好2.4 三层叠加生效3. 用 /init 自动生成项目级 CLAUDE.md3.1 /init 的工作原理3.2 /init 之后必做人工校对4. 模板实战5 个必写模块4.1 技术栈写明版本号4.2 目录结构4.3 编码规范4.4 当前进度4.5 禁忌清单最少被问到的问题5. 第二层记忆Auto Memory5.1 启用 Auto Memory5.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 PostgreSQLUI 组件库用 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 MemoryCLAUDE.md 写好了但有些事情你没意识到要写AI 怎么记这就是 Auto Memory 的价值——它是 Claude Code 自己的笔记本。5.1 启用 Auto Memory在 cc 会话中输入/memory在弹出的菜单里选第一个选项启用 Auto Memory。启用后菜单里会多出打开自动记忆文件夹选项。5.2 Auto Memory 会记什么Auto Memory 会在四种情况下自动记录类型含义举例user关于你你的角色、偏好如不喜欢深色 UIfeedback你给过的反馈“不要这样做”、“对就这样”project项目相关进度、决策、技术选型reference外部资源索引“某份设计文档在 docs/design.md”典型场景你今天告诉 Claude Code “我们项目用 TailwindCSS 4不要写 CSS 文件”。一周后开新会话你没在 CLAUDE.md 里写这条——但 Auto Memory 记下了所以 AI 不会犯老错误。5.3 Auto Memory 的使用手感几个重要细节它只在当前项目生效文件存在项目目录下换项目需重新积累启用后 cc不会每次都把所有记忆全部加载进上下文只会读一份memory.md索引——遇到具体问题才去读对应的子文件占 token 很少随时可以按CtrlO在会话中查看实际被调用过的记忆内容记错了就直接跟它说“忘掉刚刚说的不喜欢深色主题”它会自己删掉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 KarpathyAI 大牛发布的「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.md5 分钟校对每周——花 10 分钟更新当前进度和禁忌清单两个模块每月——清理一次全局 CLAUDE.md把过时的个人偏好删掉这个习惯坚持一个月你会发现 Claude Code 的反应越来越像你肚子里的蛔虫。参考资料1 https://www.bilibili.com/video/BV1RPET6tEp22 https://claude.ai/