2. CLAUDE.md 配置与记忆
用 Claude Code 干活，你可能很快会撞上一个恼人的问题：它没有长期记忆。每开一个新对话，它对你项目的了解就清零一次——上次交代过这个项目用 Vue、回复要用中文、提交前先跑测试，这次又得从头说一遍。重要的项目背景、你的个人偏好，每次重新交代，烦不胜烦。
这一篇就来解决这个问题。Claude Code 有两套机制专门用来跨会话保留信息：一套是你亲手写的 CLAUDE.md，一套是它自己积累的 自动记忆（auto memory）。把这两套用好，AI 就能真正记住你的项目和习惯，再也不用每次从头交代。这是 Claude Code 进阶路上极其关键的一环。
先说说配好之后的实际体感，你就有动力往下读了。没配 CLAUDE.md 时，你让它加个接口，它可能顺手用了 axios，可你项目统一用 fetch，于是又得返工；配好之后，它一上来就照你的技术栈、目录约定、命名风格来写，省掉大量来回纠正。差别不在某一次对话有多惊艳，而在长期协作里，你少说了多少重复的话、少改了多少不该出现的错。
1. 两套记忆系统
先建立整体认知。Claude Code 的记忆分两套，它们互补，而且每次对话开始时都会自动加载进来。
CLAUDE.md 由你来写，是你给 AI 定的项目规章。 里面放那些你希望 AI 在这个项目里始终遵守的指令——编码规范、构建命令、项目架构、固定的协作流程。它代表你主动定下的规则，写什么、改什么都由你说了算。
自动记忆由 Claude 自己写，是它在协作中攒下的经验。 干活过程中，它会把发现的有用信息自动记下来，比如这个项目的构建命令是 pnpm build、上次的 Bug 源于忘了启动 Redis、你习惯用 pnpm 而不是 npm。不用你操心，它自己积累、自己调用。
一个是你定的规章，一个是它攒的经验，两者配合，AI 对项目的熟悉度会随时间越来越高。两者的区别一张表就能看清：
| 维度 | CLAUDE.md | 自动记忆 |
|---|---|---|
| 谁来写 | 你 | Claude 自己 |
| 内容 | 指令、规章 | 协作中发现的经验、习惯 |
| 作用范围 | 项目 / 用户 / 组织 | 按仓库，存在本机 |
| 适合放 | 编码规范、流程、架构 | 构建命令、调试经验、你的偏好 |
下面分别细说。
2. CLAUDE.md 的作用域层级
CLAUDE.md 不是只能放一个地方。它按作用范围分层，从覆盖所有项目到只覆盖一个子目录，范围逐层收窄。理解这个层级，你才能把不同的规矩放到合适的位置，既不会让个人偏好污染团队仓库，也不会让项目规矩散落得到处都是。
日常最常用的是下面三层。用户级放在你用户目录下的 ~/.claude/CLAUDE.md，对你这台机器上的所有项目都生效，适合放跨项目的个人偏好，比如所有回复用中文、习惯用 pnpm 而不是 npm。项目级放在项目根目录的 ./CLAUDE.md（或 ./.claude/CLAUDE.md），只对这个项目生效，而且会随代码仓库一起提交、共享给整个团队，项目的技术栈约定、目录结构、协作流程都该放这里，比如本项目用 Vue 3 + TypeScript、API 处理函数放在 src/api/ 下，这是你最常维护的一层。子目录级放在项目某个子文件夹里的 CLAUDE.md，只在 Claude 读取那个子目录里的文件时才按需加载，不会一直占着上下文，大项目里给某个模块单独定规矩时用得上。
除了这三层，还有两个你迟早会碰到的。一个是 CLAUDE.local.md，放在项目根目录、但只属于你个人，要加进 .gitignore 不提交，适合放你自己的沙箱地址、测试账号这类不该共享的东西。另一个是面向企业的托管层（managed policy），由公司 IT 统一下发、放在系统级目录，用来强制全员遵守的安全合规要求，个人无法覆盖——作为个人开发者你一般用不到，知道有这一层即可。
这么多层，加载时谁说了算？规则是：从范围大的到范围小的依次读取、拼接，越具体的越后读、优先级越高。所以当用户级说用 4 空格缩进、项目级说用 2 空格缩进时，最终生效的是项目级的 2 空格。这个设计很合理：越贴近当前项目的规矩，越应该压过笼统的全局偏好。
举个实际的分配例子帮你落地：你个人偏好的中文回复、pnpm 习惯，放用户级；这个项目用 Vue 3、目录怎么分、提交前跑什么命令，放项目级；后端那个子模块特有的接口规范，放后端目录的子目录级。每条规矩都待在它该在的层，既不会污染团队仓库，也不会在不相关的项目里冒出来。
3. 用 /init 生成初稿
知道放哪了，接下来是怎么写。好消息是你不用从零手写——Claude Code 能扫描项目帮你生成初稿。
在项目目录里启动 Claude Code，敲一个命令：
/init它会自动扫描你的整个项目——看你用了什么技术栈、有哪些构建和测试命令、项目结构是怎样的，然后生成一份 CLAUDE.md 初稿。你在这个基础上再补充、修改，比从白纸开始轻松多了。如果项目里已经有 CLAUDE.md，/init 会建议改进而不是覆盖。生成的初稿一般已经包含项目简介、检测到的技术栈、常用命令、目录结构这几块，框架替你搭好了，你要做的是删掉它猜得不准的、补上它看不出来的，比如团队口头约定、踩过的坑、那些只有你知道的隐性规矩。
这里补一个实用细节：如果想要更可控的生成过程，可以开启交互式初始化——启动前设置环境变量 CLAUDE_CODE_NEW_INIT=1 再运行 /init，它会先问你想生成哪些东西（CLAUDE.md、技能、Hooks），再派一个子任务去探索代码库、就拿不准的地方反问你，最后给出一份可审阅的方案，确认后才落盘，对新项目想一步到位配好很合适。另外，如果仓库里已经有给其他 AI 工具用的 AGENTS.md、.cursorrules 等配置，/init 也会读取、把其中有用的部分并进生成结果，省得你重写一遍。
4. 写好 CLAUDE.md 的原则
生成只是起点，写得好不好直接决定 AI 听话的程度。这里有一点必须先讲清楚：CLAUDE.md 不是强制配置，而是上下文——它的内容作为提示喂给 AI，AI 会尽量遵守，但不保证百分百执行，尤其当指令含糊或自相矛盾时。所以下面几条原则，本质都是在提高 AI 照做的概率。
第一，要具体、能验证。 这是最重要的一条。模糊的指令 AI 没法照办，具体的它才能落地。为什么模糊不行？因为 AI 要把指令翻译成具体动作，翻译空间越大越容易跑偏：你写格式化好代码，它不知道你要几个空格、什么命名风格，只能猜；你写明 2 空格缩进、变量用驼峰命名，它照着做就行，没有猜的余地。
把抽象要求换成可验证的指令，AI 照做的概率立刻提高一截：
| 太空泛，AI 难照办 | 具体可验证，AI 能落地 |
|---|---|
| 格式化好代码 | 用 2 空格缩进 |
| 测试你的改动 | 提交前运行 npm test |
| 文件组织好 | API 处理函数放在 src/api/handlers/ |
第二，要简洁、别太长。 CLAUDE.md 每次对话都整个加载进上下文、占用 token，太长不仅费上下文，还会稀释重点、让 AI 抓不住关键、遵守度下降。官方建议单个文件控制在 200 行以内，只放那些每次对话都该记得的核心规矩；内容真的多，用下一节的拆分手段，而不是把一个文件堆到几百行。
第三，用 Markdown 结构化。 用标题和列表把相关规矩分组，别堆成一大段。结构清晰的指令，AI 和人一样更容易抓住要点。
第四，定期清理、避免冲突。 这条新手常忽略：如果两条规矩互相打架（比如一处说用 pnpm、另一处说用 npm），AI 会随机挑一条执行，行为变得难以预测。项目演进时要定期回头看 CLAUDE.md、子目录里的 CLAUDE.md 和规则文件，把过时、冲突的删掉。
第五，重要的规矩往前放。 把最关键、最不容违反的规矩放在文件靠前的位置，用简短有力的句子写。靠后的细节性规矩 AI 也会读，但靠前的更容易被稳稳记住，这一点和写给人看的文档是一个道理。
一份写得好的项目级 CLAUDE.md 大概长这样：
# 项目说明
本项目是一个 Vue 3 + TypeScript 的待办清单应用。
## 技术约定
- 用 2 空格缩进，变量命名用驼峰式
- 状态管理用 Pinia，不要引入 Vuex
- 组件放在 src/components/，页面放在 src/views/
## 工作流
- 提交代码前先运行 `pnpm test` 和 `pnpm lint`
- 所有和我的对话请用中文回复
## 注意
- 不要擅自引入新的第三方库，需要的话先问我光记原则还是抽象，最快的上手方式是让 Claude Code 自己帮你打磨。用 /init 出了初稿后，直接在对话里让它接着完善：
Prompt：
读一下当前的 CLAUDE.md，结合你对这个项目的理解，帮我补三类内容：
1. 这个项目特有、容易踩坑的约定；
2. 常用的构建、测试、启动命令；
3. 你觉得我漏写、但应该写进去的规矩。
改完把新增的部分单独标出来，等我确认。它会读项目、读现有 CLAUDE.md，给出一份带说明的修改建议，你逐条决定留不留。比起对着空文件硬想该写什么，这种它先提、你再砍的方式高效得多。但有个反方向的提醒：别把它给的建议照单全收，CLAUDE.md 越短越聚焦越好，只留你真正认同、真正常用的规矩，否则文件膨胀反而会拉低 AI 的遵守度。
5. 拆分与规则文件
当规矩越来越多，硬塞进一个 CLAUDE.md 会越过 200 行、稀释重点。Claude Code 提供了几种拆分手段，让你既能把内容分门别类，又不牺牲加载效率。
用 @import 引入其他文件。 在 CLAUDE.md 里写 @路径，就能把另一个文件的内容引进来、启动时一并加载：
代码规范见 @docs/code-style.md，Git 流程见 @docs/git-workflow.md。路径支持相对和绝对，被引入的文件还能再引入别的，最多嵌套四层。要注意，@import 只是帮你把内容分文件管理，并不省上下文——被引入的文件启动时照样全部加载进去。如果只是想在文中提到某个路径而不真的引入，用反引号把它包起来，写成 @README 这样就不会被当成导入。不确定某个文件要不要拆出去？一个经验是，内容超过两屏、或明显属于另一个独立主题，就值得拆成单独文件再引入。
用 .claude/rules/ 按主题拆规则。 比起把所有东西塞进一个 CLAUDE.md，更清爽的做法是在项目里建一个 .claude/rules/ 目录，每个主题一个文件，比如 code-style.md、testing.md、security.md。这些规则默认都会在启动时加载，优先级和项目级 CLAUDE.md 相同。
它真正强大的地方是路径级规则（path-specific rules）：在规则文件顶部用 YAML frontmatter 写上 paths，这条规则就只在 Claude 处理匹配到的文件时才加载，平时不占上下文。比如一份只在改后端 API 时才生效的规则：
---
paths:
- "src/api/**/*.ts"
---
# API 开发规范
- 所有接口必须做入参校验
- 统一用标准错误响应格式这样后端规范只在碰后端代码时进上下文，前端开发时完全不受干扰，既省 token 又减少无关噪音。大项目里这是控制上下文体积的关键手段。
和 AGENTS.md 互通。 如果你的团队已经在用 AGENTS.md（一种多家 AI 工具通用的配置格式），不用维护两份。Claude Code 只读 CLAUDE.md，但你可以在 CLAUDE.md 里写一行 @AGENTS.md 把它引进来，两边就同步了，还能在下面追加 Claude 专属的规矩。
那到底什么时候用 .claude/rules/、什么时候用 CLAUDE.md？一个简单的判断：放之四海都要遵守的项目规矩，写进 CLAUDE.md；只在特定文件、特定目录才需要的规矩，拆进带 paths 的规则文件、让它按需出现。还有一种情况：如果某条内容是一整套操作流程、只在做某类任务时才用到，那它更适合做成技能（Skill）而不是常驻记忆——这点等讲到技能篇再展开。
6. 自动记忆机制
说完你手写的部分，再看 Claude 自己记的那套——自动记忆（auto memory）。较新版本（v2.1.59 及以后）默认开启，它会在帮你干活的过程中，自动把值得记的信息存下来，下次对话还能用上。
你不用做任何操作，它自己判断什么值得记，也不是每次都记。当你在界面上看到 Writing memory（正在写记忆）或 Recalled memory（读取记忆）的提示，就是它在读写自己的记忆库。
这些记忆存在你电脑本地、按项目隔离的目录里：~/.claude/projects/<项目>/memory/。目录里有一个 MEMORY.md 作为索引，每次对话开头只加载它的前 200 行（或前 25KB，谁先到算谁）；更详细的内容拆在各个主题文件里，Claude 用到时才去读。这样的设计保证了记忆再多也不会一次性撑爆上下文。同一个 Git 仓库的所有 worktree、子目录共享同一份自动记忆，但它只存在本机，不会跨机器同步。
打开这个目录，你会看到大致这样的结构：
~/.claude/projects/<项目>/memory/
├── MEMORY.md # 索引，每次对话开头加载
├── build-commands.md # 构建、启动命令
└── debugging.md # 踩过的坑和解决办法MEMORY.md 里通常是一行行很具体的事实，比如这个项目用 pnpm 不用 npm、本地测试要先起 Redis、某个接口用什么方式鉴权。它随着你和 AI 的协作不断更新，用得越久，AI 对项目细节的掌握就越全。
你也可以主动让它记。在对话里直接说一句记住这个项目的测试要先启动本地 Redis，或者以后都用 pnpm、别用 npm，它就会把这条存进自动记忆。如果你希望某条规矩进的是 CLAUDE.md 而不是自动记忆，就明确说把这条加到 CLAUDE.md。
举个主动让它记的实际例子。某次你发现它老忘了测试要先起 Redis，可以直接告诉它：
Prompt：
记一下：以后在这个项目跑测试前，必须先用 docker 启动本地 Redis，
否则集成测试会全挂。它会把这条存进自动记忆，之后再让它跑测试，它就会先带上这一步或提醒你。这种随手一句话的积累，时间长了能省掉大量重复叮嘱。
想看它到底记了什么、或者管理这些记忆，用 /memory：
/memory它会列出当前会话加载的所有 CLAUDE.md、CLAUDE.local.md、规则文件，以及自动记忆文件夹的入口，还能在这里切换自动记忆的开关。这些记忆都是纯文本 Markdown，你随时能打开看、改、删，全程透明可控，不用担心它背着你记了什么。
它也不是什么都记。Claude 会判断某条信息将来还用不用得上，才决定要不要存，所以你不会看到它把每句话都记下来。要是你发现它记了不该记的、或者记错了，直接打开对应文件改掉或删掉即可，下次它就以你改后的版本为准。如果想彻底关掉自动记忆，在 /memory 里切换开关，或在项目 settings.json 里写 "autoMemoryEnabled": false，也可以设环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。
那么什么该写进 CLAUDE.md、什么交给自动记忆？判断很简单：你明确想让团队都遵守、想长期固定的规矩，写进 CLAUDE.md 并提交到仓库；那些零碎的、AI 在协作中自己摸索出来的经验，交给自动记忆去攒。前者是规章，后者是经验，两者配合，AI 对项目的熟悉度会随时间稳步上升。
7. 边界与排错
最后讲两个能帮你少踩坑的点。
CLAUDE.md 管不住的事，交给 Hooks。 前面强调过，CLAUDE.md 是上下文而不是强制规则，AI 大概率遵守但不绝对。如果某条要求是必须在每次提交前执行、每次改完文件后一定要跑某个命令这种不容打折的硬约束，写进 CLAUDE.md 并不保险。这种场景应该用 Hooks——它是在固定时机自动执行的 shell 命令，不管 AI 怎么想都会照跑。Hooks 是后面进阶篇的内容，这里先建立一个判断：要建议就用 CLAUDE.md，要强制就用 Hooks。举个例子，提交前必须跑 lint 这种硬要求，写进 CLAUDE.md 它偶尔可能漏掉，配成 Hooks 就一定会执行、不留侥幸。
AI 不听 CLAUDE.md 时怎么排查。 如果发现 AI 没按 CLAUDE.md 来，按这个顺序查：先用 /memory 确认这个文件到底有没有被加载进来，如果列表里没有它，说明位置不对、AI 根本没看到；确认加载了，再看指令是不是写得太含糊，把抽象要求换成可验证的写法；还不行，就检查用户级、项目级、子目录级几个 CLAUDE.md 之间有没有互相矛盾的规矩。另外有个容易忽略的点：长对话用 /compact 压缩后，项目根目录的 CLAUDE.md 会被自动重新读入，但子目录里的 CLAUDE.md 不会自动回来，要等下次 Claude 再读那个目录的文件时才重新加载。
还有一种常见情况：你在 ~/.claude/CLAUDE.md（用户级）里写了规矩，换个项目却好像不生效。先确认文件路径没写错、确实在用户主目录的 .claude/ 下，再用 /memory 看它有没有被列进加载清单。用户级规矩本该对所有项目生效，路径一旦对了，哪个项目都能读到。
8. 常见问题
Q：CLAUDE.md 要不要提交到 Git？
项目级 CLAUDE.md 应该提交，它是团队共享的项目规章，提交后所有人拉下来都生效。但只属于你个人的 CLAUDE.local.md 要加进 .gitignore 别提交，免得把你的本地路径、测试账号塞给全队。
Q：已经在用 .cursorrules / AGENTS.md，要重写一份吗？
不用。Claude Code 只认 CLAUDE.md，但你可以在 CLAUDE.md 里用 @AGENTS.md 把已有配置引进来，一份内容两边共用。运行 /init 时它也会主动读取 .cursorrules、AGENTS.md 这类配置，并入生成结果。
Q：CLAUDE.md 会让每次对话变贵吗？
会占一点。它每次对话都整个加载进上下文、消耗 token，所以才强调控制在 200 行以内。真正需要大量规则时，用 .claude/rules/ 的路径级规则按需加载，平时不进上下文，就能把这部分开销压到最低。
Q：团队里每个人偏好不一样怎么办？
把团队统一的规矩写进提交的项目级 CLAUDE.md，把个人偏好写进各自的 ~/.claude/CLAUDE.md（用户级）或项目里不提交的 CLAUDE.local.md。三层叠加、互不干扰，既有统一基线，又保留个人空间。
Q：CLAUDE.md 里能写只给人看、不占 AI 上下文的备注吗？
能。用 HTML 块注释 <!-- ... --> 写的内容，会在喂给 AI 之前被剥掉，只留给人看、不消耗 token，适合写维护者备注。
Q：CLAUDE.md 改完要重启 Claude Code 吗？
不用重启程序。它在每次对话开始时读取，开个新对话或 /clear 就会加载到最新内容；长对话中途改的，下次它读相关文件、或 /compact 之后，通常也会重新读入根目录的 CLAUDE.md。
9. 小结
这一篇解决了 Claude Code 每开新会话就对项目一无所知的痛点。核心是两套互补的记忆：CLAUDE.md 是你手写的项目规章，分用户级、项目级、子目录级几层作用域，写的时候越具体、越简洁、越结构化，AI 越听话，内容多了用 @import 和 .claude/rules/ 拆分、还能用路径级规则按需加载；自动记忆则是 Claude 自己积累的经验，默认开启、随用随记，用 /memory 随时查看和管理。
把这套记忆系统配好，你会明显感觉到协作成本在下降——不再反复交代背景，AI 一进项目就清楚你的技术栈、规范和偏好。这里要记住一条边界：CLAUDE.md 负责把你的意图持续传达给 AI，但它是引导而非强制，真正不容打折的规则要靠 Hooks 来兜底。把该写进记忆的和该用机制强制的分清楚，你对 Claude Code 的掌控就上了一个台阶。
关注秀才公众号：IT杨秀才，回复：面试
