> 适用人群：刚装好 Claude Code、却每次开新会话都要重新解释"我们用 Fastify 不是 Express"的开发者。学习目标：理解 Claude Code 的记忆机制，写出第一份高质量的 `CLAUDE.md`，并掌握四层记忆层级与 `/init`、`/memory` 两大命令。预计学习时长 45 分钟，跟着做完即可拥有一个"秒懂你项目"的 AI 结对伙伴。 ## 一、前置条件 - 已安装 Claude Code（终端能跑 `claude --version`）；若尚未安装，参考官方 [Claude Code 文档](https://code.claude.com/docs/en/overview)。 - 一个本地代码仓库（任何语言均可，本文以 TypeScript + Fastify 为例）。 - 会基本的终端操作和 Markdown 语法。 - 完全零基础也可跟上——本文不涉及任何编程，只写"规则文档"。 ## 二、痛点：你的 AI 怎么总在"失忆" 假设你刚把一位新同事拉进项目，让他"加一个用户登录接口"。如果他什么背景都不知道，多半会写出你们项目里格格不入的代码——比如用了错误的框架、错误的文件后缀、错误的目录。 Claude Code 默认就是这样一位"失忆同事"。**每一个 Claude Code 会话都以一个全新的、空白的上下文窗口开始**：上一次会话里你反复强调的"我们用 Fastify 不用 Express"、"所有文件必须是 TypeScript"、"接口放在 `src/api/v2/` 下"——全部消失。 结果就是：每次开新会话，你都得把同一套项目约定、技术栈、代码风格重新口述一遍。这件事每天都在重复，是 Claude Code 使用体验里最普遍的磨损点。 好消息是：Claude Code 内置了一整套**记忆系统（memory system）**，专门用来消除这种摩擦。它的核心载体，就是一个名叫 `CLAUDE.md` 的纯文本文件。本文就带你从零搭好它。 ## 三、理解记忆机制：两条腿走路 在动手之前，先建立正确的认知模型。Claude Code 跨会话保留知识，靠的是**两种互补机制**： 1. **`CLAUDE.md` 文件——你主动写的指令**。这是你写给 Claude 的"项目说明书"，明文 Markdown，每次会话启动时被注入到上下文里。 2. **Auto Memory（自动记忆）——Claude 自己积累的学习**。当你在对话里说出"# 记住我们用 pnpm 而不是 npm"这类话，Claude 会判断是否值得长期记住，并自动追加到记忆文件里。 一句话总结：**`CLAUDE.md` 是你喂给它的，auto memory 是它自己悟出来的**。两者都在会话开始时被加载，共同构成 Claude 对你和项目的"长期记忆"。 下面这张图展示了从会话启动到 Claude"想起一切"的完整流程： ```text flowchart TD A[启动 claude 会话] --> B[读取四层 CLAUDE.md] B --> C1[企业级 /etc/claude-code] B --> C2[用户级 ~/.claude/CLAUDE.md] B --> C3[项目级 ./CLAUDE.md] B --> C4[本地级 ./CLAUDE.local.md] B --> C5[规则目录 .claude/rules/*.md] C1 & C2 & C3 & C4 & C5 --> D[合并注入会话上下文] D --> E[叠加 auto memory] E --> F[Claude 带着完整记忆开始工作] G[/init 自动生成] -.-> C3 H[/memory 查看加载情况] -.-> D ``` ## 四、四层记忆层级：谁覆盖谁 Claude Code 的配置采用**作用域（scope）系统**，`CLAUDE.md` 一共有四个层级，优先级从高到低依次为： | 层级 | 文件位置 | 用途 | 是否提交 Git | |------|----------|------|--------------| | **Enterprise 企业级** | 系统级策略目录 | 全公司强制规范（如禁止外发密钥） | 由 IT 管理 | | **User 用户级** | `~/.claude/CLAUDE.md` | 你个人的跨项目偏好（如"始终用中文回复"） | — | | **Project 项目级** | 项目根 `CLAUDE.md` | 团队共享的项目约定 | ✅ 提交，团队共享 | | **Local 本地级** | 项目根 `CLAUDE.local.md` | 你的本地私有偏好 | ❌ 加入 .gitignore | 理解这四层的关键，在于分清**"团队共享"**和**"个人私有"**： - 项目级 `CLAUDE.md` 应该进版本库，是团队契约——所有人都该看到。 - 本地级 `CLAUDE.local.md` 是你自己的"小抄"，比如"我个人喜欢用 4 空格缩进"或"测试时跳过慢用例"，绝不能污染团队约定。 - 用户级 `~/.claude/CLAUDE.md` 适合放跨所有项目都成立的东西，例如回复语言、commit 信息风格。 **优先级规则**：当多层之间出现冲突时，更具体的层级（local > project > user > enterprise）通常以更贴近的方式叠加，但企业级策略具有最高约束力。实践中应避免在多层里写相互矛盾的指令。 ## 五、步骤一：用 `/init` 一键生成首份记忆 最快的入门方式是让 Claude 自己读你的代码库，然后替你写 `CLAUDE.md`。 **操作**：在你的项目根目录下启动 Claude Code，输入： ```text /init ``` **Claude 会做什么**：它会扫描目录结构、识别技术栈（package.json、go.mod、Cargo.toml 等）、查看构建脚本和测试命令，然后生成一份初稿 `CLAUDE.md`，并询问你是否接受。 **预期结果**：项目根目录出现一个 `CLAUDE.md`，大致长这样： ```markdown # 项目：my-api ## 技术栈 - Runtime: Node.js 20 - 语言: TypeScript 5.x（strict 模式） - Web 框架: Fastify 4 - 包管理: pnpm ## 常用命令 - 安装依赖: `pnpm install` - 开发服务器: `pnpm dev` - 运行测试: `pnpm test` - 单文件测试: `pnpm test path/to/file.test.ts` - 代码检查: `pnpm lint` - 构建: `pnpm build` ## 代码风格 - 使用 ESM 导入 - 函数式风格优先，避免 class - ... ``` **这一步的意义**：你拿到了一个真实、可用的起点，而不是面对空白文件无从下笔。后续所有优化都在这份初稿上做加法。 ## 六、步骤二：手写一份高质量的 `CLAUDE.md` `/init` 的初稿只是及格线。真正让 Claude"秒懂"的，是你针对项目特性补充的那些**约定和陷阱**。下面是一个可以直接套用的模板，逐段说明该写什么： ```markdown # 项目说明：my-api ## 项目目标 一句话说清这是做什么的：面向 B 端的多租户 SaaS 后端， 核心域是订单与计费。 ## 技术栈（必须遵守） - 语言: TypeScript，strict 模式，禁用 any - 框架: Fastify 4（不要用 Express！） - ORM: Drizzle - 测试: Vitest - 包管理: pnpm（禁止使用 npm/yarn） ## 目录约定（写新代码时遵守） - 路由处理器: src/api/v2/*.ts - 业务逻辑: src/services/*.ts - 数据访问: src/repositories/*.ts - 不要在 src/api/ 里直接写 SQL ## 代码风格 - 优先函数式风格，避免 class - 错误用 Result 模式返回，不抛异常跨层 - 所有公开函数写 JSDoc ## 构建与测试命令 - 安装: pnpm install - 开发: pnpm dev - 全量测试: pnpm test - 单文件测试: pnpm test src/services/order.test.ts - 检查: pnpm lint && pnpm typecheck ## 已知陷阱（务必注意） - 时区统一用 UTC 存储，展示时再转 - 金额用整数分表示，绝不用浮点 - env 读取必须通过 src/config.ts 的 schema 校验 ## Git 约定 - 提交信息遵循 Conventional Commits - 不要自动 commit，等用户明确指示 ``` **写好它的三条心法**： 1. **写"不该做什么"比写"该做什么"更值钱**。一句"不要用 Express"能省掉无数次错误重生成。 2. **写可执行的命令，而不是描述**。`pnpm test path/to/file` 比"运行测试"有用得多——Claude 能直接复制粘贴执行。 3. **保持精简**。`CLAUDE.md` 会常驻上下文，写得越长越费 token，也越容易被淹没在噪声里。目标是"高密度的事实"，不是长篇大论。 ## 七、步骤三：用 `/memory` 验证记忆是否生效 写完 `CLAUDE.md`，怎么确认它真的被加载了？用这条命令： ```text /memory ``` **它做什么**：列出**当前会话实际加载的全部记忆来源**——包括四层 `CLAUDE.md`、`CLAUDE.local.md`，以及 `.claude/rules/` 目录下的所有规则文件，连同它们的路径和加载状态。 **预期输出**：你会看到一个清单，类似： ```text Enterprise policies: (none) User memory: ~/.claude/CLAUDE.md Project memory: ./CLAUDE.md ✅ Local memory: ./CLAUDE.local.md (not found) Rules: .claude/rules/testing.md ✅ .claude/rules/api-conventions.md ✅ ``` **这一步的意义**：`/memory` 是排错第一工具。当你发现 Claude"又忘了约定"，第一反应就该是 `/memory` 看看那份规则到底有没有被加载——十有八九是路径放错或文件名拼错。 ## 八、步骤四：用 `.claude/rules/` 做模块化记忆 当项目长大，单个 `CLAUDE.md` 会变成又长又难维护的怪物。Claude Code 支持把记忆**拆成多个文件**，放进 `.claude/rules/` 目录。 **关键规则**：`.claude/rules/` 下的**每一个 `.md` 文件都会被自动当作项目记忆加载**，无需你在 `CLAUDE.md` 里引用。 例如这样的目录结构： ```text .claude/ ├── rules/ │ ├── testing.md # 测试约定 │ ├── api-conventions.md # API 设计规范 │ ├── database.md # 数据库与迁移 │ └── git-workflow.md # 分支与提交 └── settings.json ``` 每个文件聚焦一个领域，团队成员各管一摊，维护负担骤降。 **进阶——带作用域的规则（Gated Rules）**：有些规则只在特定场景生效。你可以在规则文件顶部用 frontmatter 限定作用域，比如只在处理测试文件时加载： ```markdown --- description: 测试编写规范 globs: ["**/*.test.ts", "**/*.spec.ts"] --- # 测试规范 - 每个公开函数至少 3 个用例：正常、边界、异常 - 用 describe/it 组织，命名用"应该……" - 禁止真实网络请求，一律 mock ``` 加了 `globs` 之后，这份规则**只在文件路径匹配时才注入上下文**，平时不占 token——这正是"渐进式披露"的精髓：把记忆按需加载，而不是一股脑全塞进去。 ## 九、步骤五：让 Claude 自己学习（Auto Memory） 除了你手写的 `CLAUDE.md`，Claude Code 还能**自动积累学习**。当你在对话里说出以 `#` 开头的一句话，例如： ```text # 我们项目统一用 dayjs 处理日期，不要用 moment ``` Claude 会判断这句话是否值得长期记住。如果值得，它会**自动写入合适的记忆文件**（通常是用户级或项目级 `CLAUDE.md`，取决于内容的作用范围），下次会话就不再需要你提醒。 **适合用 auto memory 的场景**： - 一次性的偏好纠正（"我习惯用 2 空格缩进"）。 - 跨会话反复出现的项目约定。 **不适合的场景**：长篇大论的架构说明——那种老老实实写进 `CLAUDE.md` 或 rules 文件，可控、可 review、可进版本库。auto memory 是"顺手记一笔"，正式文档还得手写。 ## 十、实战案例：从"失忆"到"秒懂" 回到开头那个痛点场景，看看配好记忆系统前后的对比。 **场景**：让 Claude"加一个用户登录接口"。 **配置前**（无 `CLAUDE.md`）： ```text 你: 加一个用户登录接口 Claude: [生成 src/routes/login.js] [用 Express 写路由] [把 SQL 直接写在路由里] [用浮点存金额] ``` 四项全错：框架错、语言错、分层错、数据类型错。你得一处处纠正，反复拉扯。 **配置后**（有高质量 `CLAUDE.md` + rules）： ```text 你: 加一个用户登录接口 Claude: [生成 src/api/v2/auth/login.ts] ✅ 目录约定 [用 Fastify 的 route handler] ✅ 框架 [业务逻辑放 src/services/auth.ts] ✅ 分层 [SQL 抽到 src/repositories/userRepo.ts] ✅ 数据访问 [用整数分表示……此处无金额，跳过] [补了 Vitest 测试用例] ✅ 测试约定 ``` 一次到位。这就是记忆系统的价值：**把团队约定固化成 AI 的肌肉记忆**，让每次会话都站在"老熟人"的起点上，而不是从零开始。 ```mermaid flowchart LR subgraph 配置前 A1[加登录接口] --> A2[生成 login.js] A2 --> A3[用 Express] A3 --> A4[SQL 塞路由里] A4 --> A5[❌ 四项全错 反复纠正] end subgraph 配置后 B1[加登录接口] --> B2[读 CLAUDE.md+rules] B2 --> B3[api/v2/auth/login.ts] B3 --> B4[Fastify 分层] B4 --> B5[补测试用例] B5 --> B6[✅ 一次到位] end ``` ## 十一、进阶：上下文管理与记忆的边界 `CLAUDE.md` 虽好，但它常驻上下文，写多了会挤占有效窗口。这里有两个进阶认知： **1. 60% 规则**。当一次会话的上下文使用量逼近约 60% 时，Claude 的注意力会开始稀释、容易"走神"。这时应及时用 `/compact` 压缩当前会话历史，把核心结论保留、把冗长中间过程折叠。**记忆系统管"跨会话"，`/compact` 管"会话内"**——两者分工不同，别混淆。 **2. 记忆不等于代码**。`CLAUDE.md` 里写的约定，Claude 会**尽量遵守但非强制**。对于绝对不能违反的硬规则（如安全审计、CI 检查），应该用 hooks（在工具调用前后拦截）或 CI 流水线来兜底，而不是只指望 AI 自觉。记忆是"降低出错概率"，hooks 是"出错就拦下"。 **3. 别在记忆里放密钥**。`CLAUDE.md` 会进版本库、会进上下文，任何敏感信息（API key、密码、token）都绝不能写在里面。机密应走环境变量或 secrets 管理工具。 ## 十二、常见问题与解决方案 **Q1：我改了 `CLAUDE.md`，但 Claude 好像没更新？** A：会话启动时一次性加载记忆。如果你在会话中途修改了文件，需要重启会话（或重新进入项目），新内容才生效。用 `/memory` 可随时确认当前加载的是哪份。 **Q2：`/init` 生成的初稿质量不行怎么办？** A：把 `/init` 当草稿，不当终稿。它的价值是给你一个结构化起点；真正决定质量的是你后续补的"已知陷阱"和"目录约定"。也可以直接对 Claude 说"读一下代码库，把测试命令和分层约定补进 CLAUDE.md"。 **Q3：团队里每个人偏好不同，怎么避免冲突？** A：团队共享的写进项目级 `CLAUDE.md`（进 Git）；个人私有偏好写进 `CLAUDE.local.md`（加入 `.gitignore`）。例如"我喜欢 commit 信息带 emoji"这种个人习惯，就该进 local 层。 **Q4：`.claude/rules/` 和 `CLAUDE.md` 内容重复了怎么办？** A：让 `CLAUDE.md` 做"总览 + 入口"，指向具体规则；细节拆进 rules 文件。避免同一句话在多处重复——重复不仅浪费 token，还容易在某处更新后产生不一致。 **Q5：auto memory 会乱写文件吗？** A：auto memory 的写入相对克制，且大多落点在用户级文件。如果你担心失控，可以定期 `git diff` 审查 `CLAUDE.md` 变更，或干脆关闭 auto memory、只用手写记忆，获得完全的可控性。 ## 十三、延伸阅读 - **官方文档 · How Claude remembers your project**： —— 记忆机制的权威说明，含 `/memory`、auto memory 细节。 - **官方文档 · Explore the .claude directory**： —— `.claude` 目录全貌：settings、hooks、skills、commands、rules 都在这里。 - **官方博客 · Using CLAUDE.md files**： —— Anthropic 官方对 CLAUDE.md 最佳实践的阐述。 - **SFEIR Institute · The CLAUDE.md Memory System Tutorial**： —— 逐步教程，适合配合本文实操。 ## 十四、训练营适用性评估 - **适合训练营类型**：Claude Code / AI 辅助开发入门营、团队工程效能提升营、新人 onboarding 训练营。本主题是所有后续高级主题（hooks、skills、子代理）的地基，建议作为**第一个实践模块**。 - **不适合**：纯算法/数据结构营、与 AI 工具无关的传统编程营。 - **预计教学时长**：讲授 20 分钟 + 跟着 `/init` 和手写模板实操 25 分钟，合计 45 分钟。可布置课后作业：为自己的真实项目写一份 `CLAUDE.md` 并用 `/memory` 验证，截图提交。 - **考核点**：能否说出四层记忆层级；能否写出至少包含"陷阱清单 + 可执行命令 + 目录约定"的 `CLAUDE.md`；能否用 gated rules 做按需加载。 - **延伸练习**：把团队现有的 README / CONTRIBUTING 里的约定，迁移进 `.claude/rules/` 模块化规则，观察 Claude 行为变化。 ## 参考来源 1. [How Claude remembers your project — Claude Code Docs](https://code.claude.com/docs/en/memory) — 官方记忆机制说明，含 CLAUDE.md 与 auto memory 两套系统、`/memory` 命令。 2. [Explore the .claude directory — Claude Code Docs](https://code.claude.com/docs/en/claude-directory) — 官方对 `.claude` 目录结构与配置作用域的完整说明。 3. [Using CLAUDE.md files — Anthropic Blog](https://claude.com/blog/using-claude-md-files) — 官方博客，CLAUDE.md 写作最佳实践。 4. [Claude Code Memory System — Developer Toolkit](https://developertoolkit.ai/en/claude-code/advanced-techniques/memory-system/) — 实战视角，含 onboarding 痛点案例与 `.claude/rules/` 模块化用法。 5. [How to Use Claude Code Instructions and Memory — Alex Rusin](https://blog.alexrusin.com/claude-code-instructions-memory-setup-guide/) — 从单文件到多文件规则系统的渐进式搭建指南。 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。