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 自己的笔记本"。两者都作为上下文注入，而非硬性执行的配置——要强制拦截某个动作，应改用 PreToolUse 钩子，而不是只写在 CLAUDE.md 里。

理解这一点能避免最常见的误解：很多人以为写在 CLAUDE.md 里的"禁止提交 main 分支"会被铁板钉钉地执行，实际上它只是"强烈建议"。需要强制时，请走 settings.json 的 permissions.deny 或钩子。

二、选择 CLAUDE.md 的投放位置

CLAUDE.md 可放在多处，按作用域从宽到窄依次加载，越具体的越靠后（也越优先）：

加载顺序口诀：从文件系统根向下，先宽后窄，最后是当前工作目录。同一目录内，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，输入：

/init

Claude 会派出子代理扫描代码库，提取构建命令、测试方式、约定，生成一份初稿 CLAUDE.md。如果文件已存在，/init 会给出改进建议而非覆盖。

预期结果

生成类似下面的文件：

# 项目：payment-api

## 构建与测试
- 安装依赖：`pnpm install`
- 跑测试：`pnpm test`
- 启动开发服务器：`pnpm dev`

## 代码风格
- 使用 2 空格缩进
- 函数命名用 camelCase，类型用 PascalCase

## 架构
- 路由处理在 src/api/handlers/
- 数据访问层在 src/repositories/

想要更结构化的交互式流程，设置环境变量后再跑：

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）：

4. 一致性（Consistency）：两条矛盾的规则，Claude 可能随机挑一条。定期审查 CLAUDE.md、子目录 CLAUDE.md、.claude/rules/，删掉过时或冲突的内容。

一个可直接用的模板

# 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。导入的文件会在启动时展开并入上下文。

# 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 导入它即可，避免双份维护：

@AGENTS.md

## Claude Code 专属
- 改动 src/billing/ 前用 plan 模式

或直接软链（Windows 需管理员/开发者模式，否则用 import）：

ln -s AGENTS.md CLAUDE.md

注意：拆分到 @ 导入只改善组织，不减少上下文占用——导入的文件照样在启动时进上下文。要真正省 token，看下一步的路径规则。

六、第四步：.claude/rules/ 按需、按路径投放规则

大项目里，并非每条规则都要常驻上下文。.claude/rules/ 目录让你把指令拆成单主题文件，还能用 YAML frontmatter 的 paths 字段只在处理匹配文件时才加载。

目录结构

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）

---
paths:
  - src/api/**/*.ts
  - src/api/**/*.tsx
---

# API 开发规则
- 所有端点必须做入参校验
- 使用统一错误响应格式 src/lib/errors.ts
- 必须写 OpenAPI 注释

glob 模式速查

路径规则在 Claude 读取匹配文件时触发，而非每次工具调用都触发。需要"调用时才上"的任务型指令，请改用 Skills（只在被调用或被判定相关时加载）。

跨项目共享规则（软链）

.claude/rules/ 支持软链，可维护一套共享规则链到多个项目，循环软链会被安全处理：

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

存储位置

每个项目一个目录：

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁索引，每次会话加载前 200 行 / 25KB
├── debugging.md       # 详细调试模式（按需读）
├── api-conventions.md # API 设计决策（按需读）
└── ...

• 项目路径从 Git 仓库派生，所以同一 repo 的所有 worktree 和子目录共享一个记忆目录
• 非 Git 目录则用项目根
• 25KB / 200 行上限只作用于 MEMORY.md；主题文件（如 debugging.md）启动时不加载，Claude 需要时才用文件工具按需读

想换存储位置，在任意 settings.json 设：

{ "autoMemoryDirectory": "~/my-custom-memory-dir" }

值必须是绝对路径或以 ~/ 开头。

主动让它记

直接说人话即可：

记住：这个项目的 API 测试需要本地 Redis 实例

永远用 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 正在读写记忆目录。

八、记忆加载全景：一张流程图

flowchart TD
    A[启动 Claude Code] --> B[读取托管策略 CLAUDE.md<br/>不可被排除]
    B --> C[读取用户级 ~/.claude/CLAUDE.md<br/>+ ~/.claude/rules/*.md]
    C --> D[向上遍历目录树<br/>逐级拼接各层 CLAUDE.md]
    D --> E[当前目录 CLAUDE.md<br/>.claude/CLAUDE.md]
    E --> F[CLAUDE.local.md<br/>每层最后追加]
    F --> G[展开 @ 导入<br/>最多 4 跳]
    G --> H[加载 .claude/rules/*.md<br/>无 paths 字段者常驻]
    H --> I[加载 auto memory<br/>MEMORY.md 前 200 行 / 25KB]
    I --> J[会话开始]
    J --> K{Claude 读取子目录文件?}
    K -->|是| L[按需加载该子目录<br/>CLAUDE.md + 匹配的路径规则]
    K -->|动到匹配路径文件| M[触发对应 paths 规则]
    L --> N[正常工作]
    M --> N

九、实战案例：给一个 Node.js API 配三层记忆

目标：把"团队约定 + 个人偏好 + 按目录规则 + 自动积累"全部跑通。

场景设定

payment-api 是 TypeScript 服务，团队 5 人共用，你个人习惯用 pnpm，且 src/api/ 有特殊的校验要求。

步骤 1：生成项目骨架

mkdir payment-api && cd payment-api
git init
claude
# 会话内输入 /init，让它扫描并生成 .claude/CLAUDE.md

步骤 2：写团队共享的 .claude/CLAUDE.md

# 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（不入库）

echo "CLAUDE.local.md" >> .gitignore

.claude 之外的项目根新建 CLAUDE.local.md：

# 个人本地偏好
- 我的沙箱地址：http://localhost:8080
- 测试数据用 fixtures/local-seed.json

步骤 4：加路径规则 .claude/rules/api.md

---
paths:
  - src/api/**/*.ts
---

# API 规则
- 所有端点必须入参校验
- 用 src/lib/errors.ts 的统一错误格式
- 必须写 OpenAPI 注释

这样只有动 src/api/ 下的 TS 文件时才吃 API 规则，平时不占上下文。

步骤 5：让 Claude 记住一条跨会话教训

会话里直接说：

记住：CI 里 pnpm install 会因为 lockfile 不一致失败，改完依赖务必跑 pnpm install --frozen-lockfile 验证

Claude 写入 ~/.claude/projects/<本项目>/memory/MEMORY.md。下次新会话，前 200 行自动加载，这条坑就不再踩。

步骤 6：验证加载链路

/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。要加载：

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：

{
  "claudeMd": "提交前务必跑 `make lint`。\n永远不要直接 push 到 main。"
}

claudeMd 只在托管/策略层生效，写在用户/项目/本地 settings 里无效。

分工：技术强制（拦截工具/命令/路径、沙箱、环境变量、登录锁定）走 managed settings；行为引导（代码风格、合规提醒）走托管 CLAUDE.md。

用 claudeMdExcludes 排除噪音

大型 monorepo 里，别的团队的 CLAUDE.md 可能干扰你。在 .claude/settings.local.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 官方文档 — 记忆系统一手权威说明，覆盖 CLAUDE.md、auto memory、.claude/rules/、组织级部署与排错，本文核心事实来源。
2. CLAUDE.md Files and Memory Hierarchy — DeepWiki — 社区整理的 CLAUDE.md 记忆层级与加载顺序图解，便于建立心智模型。
3. Claude Code Memory System: MEMORY.md, Topic Files, and Automated Maintenance — Ian Paterson — 用纯 Markdown + cron 维护持久记忆系统的实战，对 auto memory 工程化有启发。
4. CLAUDE.md Best Practices: The Complete 2026 Guide — dev.to — CLAUDE.md 与 AGENTS.md 跨工具标准对比及写作最佳实践。
5. Claude Code & Agent Memory: Best Practices for 2026 — Orchestrator.dev — 分层记忆架构与高信号指令层设计的深度分析，适合进阶组织级配置。

[!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 等场景全覆盖。