# Claude Code 记忆体系：CLAUDE.md 与自动记忆配置实战 ## 概述本教程面向已装好 Claude Code、想让它"记住"项目约定与个人偏好的开发者。你将掌握 Claude Code 的两层记忆机制——你手写的 `CLAUDE.md` 与 Claude 自动积累的 Auto Memory，学会在用户级、项目级、子目录级精准投放指令，用 `/init`、`@` 导入、`.claude/rules/` 路径规则和 `/memory` 把"每次都要重说的话"变成一次配置、长期生效。全程配有可复制的命令、文件示例与排错清单。 ## 前置条件 - 已安装 Claude Code（任意原生安装方式均可），终端能跑 `claude --version` - 想体验 Auto Memory，版本需 ≥ **v2.1.59** - 一个用于练手的 Git 仓库（本文用 Node.js API 项目演示，语言无关） - 基本熟悉命令行与 Markdown 语法如尚未安装，先在终端执行 `claude --version` 确认版本；低于 2.1.59 时升级后再启用 Auto Memory 相关章节。 --- ## 一、先建立心智模型：两种记忆，各司其职每次启动 Claude Code，上下文窗口都是**全新**的——上一轮对话的内容不会自动带过来。让知识跨会话存活，靠两套互补机制： | 维度 | CLAUDE.md 文件 | Auto Memory（自动记忆） | |---|---|---| | 谁来写 | **你**手写 | **Claude** 自己记 | | 内容 | 指令与规则（编码规范、构建命令、架构） | 学到的模式（调试心得、偏好、坑） | | 作用域 | 项目 / 用户 / 组织 | 单仓库（同 repo 的所有 worktree 共享） | | 加载时机 | 每次会话启动全量加载 | 每次会话加载 `MEMORY.md` 前 200 行或 25KB | | 典型用途 | "用 2 空格缩进""提交前跑 `make lint`" | "这个项目的 API 测试需要本地 Redis""我习惯 pnpm 不用 npm" | 一句话区分：**CLAUDE.md 是"你定的规矩"，Auto Memory 是"Claude 自己的笔记本"**。两者都作为上下文注入，而非硬性执行的配置——要强制拦截某个动作，应改用 `PreToolUse` 钩子，而不是只写在 CLAUDE.md 里。理解这一点能避免最常见的误解：很多人以为写在 CLAUDE.md 里的"禁止提交 main 分支"会被铁板钉钉地执行，实际上它只是"强烈建议"。需要强制时，请走 `settings.json` 的 `permissions.deny` 或钩子。 --- ## 二、选择 CLAUDE.md 的投放位置 CLAUDE.md 可放在多处，**按作用域从宽到窄依次加载**，越具体的越靠后（也越优先）： | 作用域 | 位置 | 用途 | 共享范围 | |---|---|---|---| | 托管策略（组织级） | macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`
Linux/WSL: `/etc/claude-code/CLAUDE.md`
Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | 全公司编码标准、安全策略 | 机器上所有用户 | | 用户级 | `~/.claude/CLAUDE.md` | 跨所有项目的个人偏好 | 仅你自己 | | 项目级 | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 团队共享的项目约定 | 经版本控制共享给团队 | | 本地级 | `./CLAUDE.local.md` | 本机、本项目的私有偏好（加入 `.gitignore`） | 仅你、当前项目 | **加载顺序口诀**：从文件系统根向下，先宽后窄，最后是当前工作目录。同一目录内，`CLAUDE.local.md` 总是追加在 `CLAUDE.md` 之后——也就是说，你写在 local 里的个人注释，是 Claude 在该层级**最后读到**的内容。 ### 目录树向上爬升如果你在 `foo/bar/` 启动 Claude，它会逐级向上检查：`foo/bar/CLAUDE.md`、`foo/CLAUDE.md`，连同各级的 `CLAUDE.local.md`。**所有命中文件会被拼接进上下文**，而非互相覆盖。而**子目录**里的 CLAUDE.md 不会在启动时加载——只有当 Claude 真去读那个子目录里的文件时，才会按需把对应 CLAUDE.md 带进来（懒加载）。 --- ## 三、第一步：用 `/init` 一键生成项目 CLAUDE.md 最省事的起步方式是让 Claude 自己分析代码库。 ### 操作说明在你的项目根目录启动 Claude Code，输入： ```text /init ``` Claude 会派出子代理扫描代码库，提取构建命令、测试方式、约定，生成一份初稿 `CLAUDE.md`。如果文件已存在，`/init` 会**给出改进建议**而非覆盖。 ### 预期结果生成类似下面的文件： ```markdown # 项目：payment-api ## 构建与测试 - 安装依赖：`pnpm install` - 跑测试：`pnpm test` - 启动开发服务器：`pnpm dev` ## 代码风格 - 使用 2 空格缩进 - 函数命名用 camelCase，类型用 PascalCase ## 架构 - 路由处理在 src/api/handlers/ - 数据访问层在 src/repositories/ ``` 想要更结构化的交互式流程，设置环境变量后再跑： ```bash export CLAUDE_CODE_NEW_INIT=1 claude # 会话内输入 /init ``` `CLAUDE_CODE_NEW_INIT=1` 会启用多阶段流程：先问你要不要设置 CLAUDE.md、skills、hooks，再用子代理探索代码库、追问补全缺口，最后给出可审阅的提案才落盘。 ### 常见问题 - **`/init` 没生成文件**：确认你在项目根目录而非子目录启动，且目录可写。 - **生成的命令不对**：`/init` 只能"猜"，把不准的地方手动改掉——它的价值在于提供一个起点。 --- ## 四、第二步：写出"会被遵守"的指令 CLAUDE.md 在每次会话启动时连同对话一起消耗 token。**越具体、越精简、越结构化，遵循率越高**。官方建议：**单文件控制在 200 行以内**。 ### 四条写作原则 1. **精简（Size）**：单文件 < 200 行。超长会吃掉上下文、降低遵循度。要瘦身就用路径规则（见第六步）。 2. **结构化（Structure）**：用 Markdown 标题和列表分组。Claude 扫描结构的方式和人一样，分节比大段文字好读。 3. **具体可验证（Specificity）**： | ❌ 模糊 | ✅ 具体 | |---|---| | "格式化代码" | "用 2 空格缩进" | | "测试你的改动" | "提交前跑 `pnpm test`" | | "保持文件整洁" | "API handler 放在 `src/api/handlers/`" | 4. **一致性（Consistency）**：两条矛盾的规则，Claude 可能随机挑一条。定期审查 CLAUDE.md、子目录 CLAUDE.md、`.claude/rules/`，删掉过时或冲突的内容。 ### 一个可直接用的模板 ```markdown # payment-api 项目约定 ## 角色本项目是处理支付的 Node.js 服务，运行在 Node 20+，TypeScript 严格模式。 ## 命令 - 安装：`pnpm install` - 测试：`pnpm test`（含单测与集成测试，集成测试需本地 Redis） - Lint：`pnpm lint` —— 提交前必须通过 - 构建：`pnpm build` ## 编码规范 - 缩进 2 空格；行尾分号 - 函数 camelCase，接口/类型 PascalCase - 所有金额用分（整数）存储，禁止用浮点 ## 架构与禁区 - 路由：src/api/handlers/ - 数据访问：src/repositories/，禁止在 handler 里直接写 SQL - 金额计算必须走 src/lib/money.ts 的封装 ## 工作流 - 不要自动 git commit，除非我明确说"提交" - 改动 src/billing/ 下文件前先用 plan 模式 ``` --- ## 五、第三步：用 `@` 导入拆分大文件 `@path/to/file` 语法可以把其它文件导入 CLAUDE.md。导入的文件会在启动时**展开并入上下文**。 ```markdown # payment-api See @README.md for overview and @package.json for npm commands. # 附加约定 - git 工作流见 @docs/git-instructions.md ``` **关键细节**： - 相对路径基于**包含 import 的文件**，而非工作目录 - 导入可递归，**最多 4 跳**深度 - 首次遇到项目外部的 import，会弹批准对话框；拒绝后该 import 永久禁用 - 想跨 worktree 共享个人偏好，从家目录导入：`- @~/.claude/my-project-instructions.md` ### 与 AGENTS.md 共存 Claude Code 读的是 `CLAUDE.md`，**不读** `AGENTS.md`。若仓库已用 AGENTS.md 服务其它工具，建一个 CLAUDE.md 导入它即可，避免双份维护： ```markdown @AGENTS.md ## Claude Code 专属 - 改动 src/billing/ 前用 plan 模式 ``` 或直接软链（Windows 需管理员/开发者模式，否则用 import）： ```bash ln -s AGENTS.md CLAUDE.md ``` > 注意：拆分到 `@` 导入只改善**组织**，不减少上下文占用——导入的文件照样在启动时进上下文。要真正省 token，看下一步的路径规则。 --- ## 六、第四步：`.claude/rules/` 按需、按路径投放规则大项目里，并非每条规则都要常驻上下文。`.claude/rules/` 目录让你把指令拆成单主题文件，还能用 YAML frontmatter 的 `paths` 字段**只在处理匹配文件时才加载**。 ### 目录结构 ```text payment-api/ ├── .claude/ │ ├── CLAUDE.md # 主项目指令（每次加载） │ └── rules/ │ ├── code-style.md # 无 paths → 每次加载 │ ├── testing.md # 无 paths → 每次加载 │ ├── api.md # paths → 只在动 src/api 时加载 │ └── security.md # paths → 只在动敏感文件时加载 ``` ### 路径规则示例（`.claude/rules/api.md`） ```markdown --- paths: - src/api/**/*.ts - src/api/**/*.tsx --- # API 开发规则 - 所有端点必须做入参校验 - 使用统一错误响应格式 src/lib/errors.ts - 必须写 OpenAPI 注释 ``` ### glob 模式速查 | 模式 | 匹配 | |---|---| | `**/*.ts` | 任意目录的 TypeScript 文件 | | `src/**/*` | src 下所有文件 | | `*.md` | 项目根的 Markdown | | `src/**/*.{ts,tsx}` | src 下的 ts 与 tsx（花括号展开） | > 路径规则在 **Claude 读取匹配文件时**触发，而非每次工具调用都触发。需要"调用时才上"的任务型指令，请改用 Skills（只在被调用或被判定相关时加载）。 ### 跨项目共享规则（软链） `.claude/rules/` 支持软链，可维护一套共享规则链到多个项目，循环软链会被安全处理： ```bash ln -s ~/shared-claude-rules .claude/rules/shared ln -s ~/company-standards/security.md .claude/rules/security.md ``` 个人全局规则放 `~/.claude/rules/`，对机器上所有项目生效，且**先于项目规则加载**（项目规则优先级更高）。 --- ## 七、第五步：开启 Auto Memory，让 Claude 自己记笔记 Auto Memory 让 Claude 在工作过程中自动积累知识——构建命令、调试心得、架构笔记、风格偏好。它不会每次都记，而是**判断"这条信息在将来是否有用"**才落盘。要求 Claude Code **≥ v2.1.59**。`claude --version` 确认。 ### 默认开启，三种关闭方式默认就是开的。要关： 1. 会话内 `/memory` → 用开关切换 2. 项目 `.claude/settings.json`： ```json { "autoMemoryEnabled": false } ``` 3. 环境变量：`export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` ### 存储位置每个项目一个目录： ```text ~/.claude/projects//memory/ ├── MEMORY.md # 简洁索引，每次会话加载前 200 行 / 25KB ├── debugging.md # 详细调试模式（按需读） ├── api-conventions.md # API 设计决策（按需读） └── ... ``` - 项目路径从 **Git 仓库**派生，所以同一 repo 的所有 worktree 和子目录**共享一个**记忆目录 - 非 Git 目录则用项目根 - 25KB / 200 行上限**只作用于 `MEMORY.md`**；主题文件（如 `debugging.md`）启动时不加载，Claude 需要时才用文件工具按需读想换存储位置，在任意 `settings.json` 设： ```json { "autoMemoryDirectory": "~/my-custom-memory-dir" } ``` 值必须是绝对路径或以 `~/` 开头。 ### 主动让它记直接说人话即可： ```text 记住：这个项目的 API 测试需要本地 Redis 实例 ``` ```text 永远用 pnpm，不要用 npm ``` Claude 会写入 auto memory。想写进 CLAUDE.md 而非 auto memory，就明说："把这条加到 CLAUDE.md"。 ### 查看与审计：`/memory` `/memory` 命令一屏看清当前会话加载了哪些 CLAUDE.md、CLAUDE.local.md、rules 文件，可切换 auto memory 开关，并提供打开 auto memory 文件夹的链接。选中任一文件即在编辑器中打开。看到界面里出现 "Writing memory" / "Recalled memory"，就是 Claude 正在读写记忆目录。 --- ## 八、记忆加载全景：一张流程图 ```mermaid flowchart TD A[启动 Claude Code] --> B[读取托管策略 CLAUDE.md
不可被排除] B --> C[读取用户级 ~/.claude/CLAUDE.md
+ ~/.claude/rules/*.md] C --> D[向上遍历目录树
逐级拼接各层 CLAUDE.md] D --> E[当前目录 CLAUDE.md
.claude/CLAUDE.md] E --> F[CLAUDE.local.md
每层最后追加] F --> G[展开 @ 导入
最多 4 跳] G --> H[加载 .claude/rules/*.md
无 paths 字段者常驻] H --> I[加载 auto memory
MEMORY.md 前 200 行 / 25KB] I --> J[会话开始] J --> K{Claude 读取子目录文件?} K -->|是| L[按需加载该子目录
CLAUDE.md + 匹配的路径规则] K -->|动到匹配路径文件| M[触发对应 paths 规则] L --> N[正常工作] M --> N ``` --- ## 九、实战案例：给一个 Node.js API 配三层记忆目标：把"团队约定 + 个人偏好 + 按目录规则 + 自动积累"全部跑通。 ### 场景设定 `payment-api` 是 TypeScript 服务，团队 5 人共用，你个人习惯用 pnpm，且 `src/api/` 有特殊的校验要求。 ### 步骤 1：生成项目骨架 ```bash mkdir payment-api && cd payment-api git init claude # 会话内输入 /init，让它扫描并生成 .claude/CLAUDE.md ``` ### 步骤 2：写团队共享的 `.claude/CLAUDE.md` ```markdown # payment-api ## 命令 - 安装：`pnpm install` - 测试：`pnpm test`（集成测试需本地 Redis） - Lint：`pnpm lint`，提交前必过 - 构建：`pnpm build` ## 规范 - 缩进 2 空格；行尾分号 - 金额用分（整数），禁止浮点 - 数据访问必须经 src/repositories/，禁止 handler 里写裸 SQL ## 工作流 - 不要自动 commit - 改 src/billing/ 前用 plan 模式 ``` 提交到 Git，团队共享。 ### 步骤 3：写个人本地的 `CLAUDE.local.md`（不入库） ```bash echo "CLAUDE.local.md" >> .gitignore ``` `.claude` 之外的项目根新建 `CLAUDE.local.md`： ```markdown # 个人本地偏好 - 我的沙箱地址：http://localhost:8080 - 测试数据用 fixtures/local-seed.json ``` ### 步骤 4：加路径规则 `.claude/rules/api.md` ```markdown --- paths: - src/api/**/*.ts --- # API 规则 - 所有端点必须入参校验 - 用 src/lib/errors.ts 的统一错误格式 - 必须写 OpenAPI 注释 ``` 这样只有动 `src/api/` 下的 TS 文件时才吃 API 规则，平时不占上下文。 ### 步骤 5：让 Claude 记住一条跨会话教训会话里直接说： ```text 记住：CI 里 pnpm install 会因为 lockfile 不一致失败，改完依赖务必跑 pnpm install --frozen-lockfile 验证 ``` Claude 写入 `~/.claude/projects/<本项目>/memory/MEMORY.md`。下次新会话，前 200 行自动加载，这条坑就不再踩。 ### 步骤 6：验证加载链路 ```text /memory ``` 应能看到：项目 CLAUDE.md、本地 CLAUDE.local.md、`.claude/rules/api.md`、auto memory 文件夹入口。 ### 预期效果 - 新开会话，Claude 立刻知道用 pnpm、金额用分、改 billing 要先 plan - 你说"加个新端点"，它自动遵守 API 规则（因为动了 src/api/） - 它记得 lockfile 那个坑，主动提醒你验证 --- ## 十、排错清单 ### Claude 不遵守我的 CLAUDE.md 1. 跑 `/memory`，确认文件真的被列出来——没列出就等于看不见 2. 检查文件是否在会被加载的位置（见第二步作用域表） 3. 把指令写得更具体（"2 空格缩进"而非"格式化好一点"） 4. 找冲突：两个文件对同一行为给出不同指示时，Claude 可能随机选一个 5. 要"必在固定时机执行"的（如提交前必 lint），改用 hook，别只靠 CLAUDE.md 6. 想"诊断到底加载了哪些指令文件、何时、为何"，挂一个 **InstructionsLoaded 钩子**记录日志——对排查路径规则和子目录懒加载特别有用 ### CLAUDE.md 太大超 200 行会降遵循度。用路径规则把"只在动某类文件时才需要"的指令挪走；或删掉并非每次会话都需要的。**注意**：拆成 `@` 导入只改善组织、不省 token，因为导入文件照样启动时进上下文。 ### `/compact` 之后指令"丢了" - **项目根的 CLAUDE.md 能扛过压缩**：`/compact` 后 Claude 会重新从磁盘读取并再注入 - **子目录的 CLAUDE.md 不会自动重注入**：要等 Claude 再次读取该子目录文件时才重新加载 - 如果某条指令压缩后消失，多半是它只在对话里说过、或住在尚未重新加载的子目录 CLAUDE.md 里——把它提升到项目根 CLAUDE.md 即可持久 ### 不知道 auto memory 记了啥 `/memory` → 选 auto memory 文件夹，纯 Markdown，可读可改可删。 ### 想从额外目录也加载 CLAUDE.md `--add-dir` 加进来的目录默认**不**加载其 CLAUDE.md。要加载： ```bash export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config ``` 这会从额外目录加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md`、`CLAUDE.local.md`。 --- ## 十一、进阶：大团队与组织级管理 ### 部署组织级 CLAUDE.md 把文件放到托管策略位置（如 Linux 的 `/etc/claude-code/CLAUDE.md`），用 MDM/Ansible/组策略下发。**该文件无法被任何个人设置排除**，确保安全策略必达。也可把内容直接写进 `managed-settings.json`： ```json { "claudeMd": "提交前务必跑 `make lint`。\n永远不要直接 push 到 main。" } ``` > `claudeMd` 只在托管/策略层生效，写在用户/项目/本地 settings 里无效。 **分工**：技术强制（拦截工具/命令/路径、沙箱、环境变量、登录锁定）走 managed settings；行为引导（代码风格、合规提醒）走托管 CLAUDE.md。 ### 用 `claudeMdExcludes` 排除噪音大型 monorepo 里，别的团队的 CLAUDE.md 可能干扰你。在 `.claude/settings.local.json`： ```json { "claudeMdExcludes": [ "**/monorepo/CLAUDE.md", "/home/user/monorepo/other-team/.claude/rules/**" ] } ``` 按绝对路径 glob 匹配，各层 settings 的数组合并。托管策略 CLAUDE.md 不可被排除。 --- ## 延伸阅读 - **Claude Code 官方文档 · 记忆系统**：完整覆盖 CLAUDE.md、auto memory、rules、组织级部署。本文一手来源。 - **`.claude/` 目录与上下文窗口**：理解 CLAUDE.md 在启动上下文中的位置，配合 Prompt caching 看 token 占用。 - **Skills 与 Subagent memory**：当指令是多步流程而非"常驻事实"时，应封装成 Skill；子代理也能维护各自的 auto memory。 - **Hooks（PreToolUse / InstructionsLoaded）**：把"必须执行"的规则从软建议升级为硬执行，并记录指令加载日志。 - **`settings.json` 与 Permission modes**：权限拦截、沙箱、`--setting-sources` 等配置项，与 CLAUDE.md 形成"强制 + 引导"双轨。 --- ## 训练营适用性评估 - **适合类型**：Claude Code 入门营（第 1–2 天）、团队工程效能营、企业 AI 编程规范落地营。也适合作为"配置与权限"专题的前置课。 - **教学时长**：讲授 + 跟做约 **90 分钟**（含 `/init`、三层文件、路径规则、auto memory 全流程动手）；进阶组织级管理可再加 30 分钟。 - **学员产出**：每人带走一个配置完整的练手仓库（含 CLAUDE.md、CLAUDE.local.md、至少一条路径规则、可用的 auto memory），可直接迁移到真实项目。 - **难度**：低到中。无需编程基础，但要理解目录结构与 Markdown；组织级章节略偏运维，可选讲。 --- ## 参考来源 1. [How Claude remembers your project — Claude Code 官方文档](https://code.claude.com/docs/en/memory) — 记忆系统一手权威说明，覆盖 CLAUDE.md、auto memory、`.claude/rules/`、组织级部署与排错，本文核心事实来源。 2. [CLAUDE.md Files and Memory Hierarchy — DeepWiki](https://deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide/4.1-claude.md-files-and-memory-hierarchy) — 社区整理的 CLAUDE.md 记忆层级与加载顺序图解，便于建立心智模型。 3. [Claude Code Memory System: MEMORY.md, Topic Files, and Automated Maintenance — Ian Paterson](https://ianlpaterson.com/blog/claude-code-memory-architecture/) — 用纯 Markdown + cron 维护持久记忆系统的实战，对 auto memory 工程化有启发。 4. [CLAUDE.md Best Practices: The Complete 2026 Guide — dev.to](https://dev.to/nishilbhave/claudemd-best-practices-the-complete-2026-guide-435j) — CLAUDE.md 与 AGENTS.md 跨工具标准对比及写作最佳实践。 5. [Claude Code & Agent Memory: Best Practices for 2026 — Orchestrator.dev](https://orchestrator.dev/blog/2026-04-06--claude-code-agent-memory-2026/) — 分层记忆架构与高信号指令层设计的深度分析，适合进阶组织级配置。 > [!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 等场景全覆盖。 ![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)