Claude Code 记忆系统完全指南：CLAUDE.md 与 Auto Memory

前言

在使用 Claude Code 进行日常开发时，你是否遇到过这些问题：每次新会话都要重复说明项目结构？Claude 总是忘记你上次交代的编码偏好？或者团队中多人使用 Claude 却各自为政，缺乏统一的规范？

Claude Code 提供了两套互补的记忆机制来解决这些问题：**CLAUDE.md**（你主动编写的指令文件）和 **Auto Memory**（Claude 自动积累的长期知识）。本文将深入剖析这两套系统的工作原理、最佳实践和常见问题排查。

---

一、CLAUDE.md vs Auto Memory：核心区别

| 维度 | CLAUDE.md | Auto Memory |

|------|-----------|-------------|

| **谁写的** | 你（开发者） | Claude（自动记录） |

| **内容** | 编码规范、项目架构、工作流程 | 构建命令、调试经验、代码风格偏好 |

| **作用域** | 项目 / 用户 / 组织 | 每个 Git 仓库独立，跨 worktree 共享 |

| **加载方式** | 每次会话完整加载 | 每次会话加载 MEMORY.md 前 200 行 |

| **用途** | 主动设定规则 | 被动积累知识 |

**核心原则**：CLAUDE.md 是你告诉 Claude 该怎么做，Auto Memory 是 Claude 从你的纠正中学习。

---

二、CLAUDE.md 文件详解

2.1 文件存放位置与作用域

CLAUDE.md 可以放置在不同层级，作用范围从全局到项目逐级收窄：

| 作用域 | 存放路径 | 用途 |

|--------|----------|------|

| **组织策略** | /etc/claude-code/CLAUDE.md（Linux）或 C:\Program Files\ClaudeCode\CLAUDE.md（Windows） | IT 管理员统一下发的公司级规范 |

| **用户全局** | ~/.claude/CLAUDE.md | 个人编码风格偏好，适用于所有项目 |

| **项目共享** | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 团队共享的项目架构和规范 |

| **本地私有** | ./CLAUDE.local.md（应加入 .gitignore） | 个人沙箱配置、本地测试数据 |

2.2 编写有效指令的技巧

CLAUDE.md 是作为用户消息注入上下文的，并非系统提示——所以 Claude 会尽力遵循但不保证 100% 严格执行。要写出有效的指令，记住以下几点：

• **控制篇幅**：目标不超过 200 行。过长会消耗更多上下文 token，降低遵循率
• **结构化**：使用 Markdown 标题和列表组织相关内容
• **具体可验证**：❌ "规范代码格式" → ✅ "使用 2 空格缩进"
• **避免矛盾**：多个 CLAUDE.md 文件间的冲突规则会导致 Claude 随机选择

• 2.3 导入外部文件

  CLAUDE.md 支持通过 @path 语法导入其他文件：

  # 在 CLAUDE.md 中
  @README.md
  @package.json
  @docs/git-instructions.md

  导入的文件会被展开并注入上下文，支持递归导入（最多 4 层深度）。如果不想导入某路径，用反引号包裹即可：` @README `。

  2.4 AGENTS.md 兼容

  如果你的仓库已存在 AGENTS.md，在 CLAUDE.md 中导入它即可两全其美：

  
  @AGENTS.md
  
  ## Claude Code 专属指令
  - 修改 `src/billing/` 下的代码前先制定计划

  也可以用软链接，但 Windows 下需要管理员权限，推荐用 @ 导入。

  2.5 使用 `.claude/rules/` 组织规则

  对于大型项目，可以将指令拆分为多个主题文件：

  
  your-project/
  ├── .claude/
  │   ├── CLAUDE.md
  │   └── rules/
  │       ├── code-style.md
  │       ├── testing.md
  │       └── security.md

  规则文件支持 **路径作用域（path-scoped rules）**，只有编辑匹配文件时才会加载：

  ---
  paths:
    - "src/api/**/*.ts"
    - "lib/**/*.ts"
  ---
  
  # API 开发规则
  - 所有端点必须包含输入验证
  - 使用标准错误响应格式

  支持软链接共享规则集，支持用户级规则（~/.claude/rules/）。

  2.6 大团队管理方案

• **组织级 CLAUDE.md**：通过 MDM/组策略部署到固定路径，无法被用户排除
• **`claudeMd` 配置键**：可将 CLAUDE.md 内容直接放入 `managed-settings.json`
• **排除特定文件**：`claudeMdExcludes` 设置支持 glob 模式排除不需要的 CLAUDE.md

• ---

  三、Auto Memory 自动记忆

  3.1 工作原理

  Auto Memory 是 Claude 在对话过程中自动保存的笔记，存储位置：

  
  ~/.claude/projects/<项目标识>/memory/
  ├── MEMORY.md          # 索引文件，每次会话加载前 200 行
  ├── debugging.md       # 调试经验
  ├── api-conventions.md # API 设计决策
  └── ...

  **关键机制**：

• 同一 Git 仓库的所有 worktree 共享同一份 Auto Memory
• MEMORY.md 前 200 行（或前 25KB）在每次会话启动时加载
• 主题文件（如 `debugging.md`）按需读取，不占用启动上下文

• 3.2 启用/禁用

  默认开启。可通过以下方式控制：

  // settings.json
  {
    "autoMemoryEnabled": false
  }

  或环境变量：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

  自定义存储目录：

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

  3.3 查看和编辑

  在会话中输入 /memory 命令可：

• 查看当前加载的所有 CLAUDE.md 和规则文件
• 开关 Auto Memory
• 打开记忆文件夹浏览/编辑所有记忆文件

• ---

  四、问题排查指南

  4.1 Claude 不遵循 CLAUDE.md

  1. 运行 /memory 确认文件已加载

  2. 检查文件是否在正确的加载路径

  3. 让指令更具体（"用 2 空格缩进" 优于 "格式规范"）

  4. 检查不同层级的 CLAUDE.md 是否存在冲突

  5. 如果必须严格执行，改用 PreToolUse hook

  4.2 CLAUDE.md 过大

• 使用 path-scoped rules 按需加载
• 运行 `/doctor` 自动检测可精简的内容
• 注意：`@import` 不减少上下文消耗

• 4.3 `/compact` 后指令消失

• 项目根目录的 CLAUDE.md 会在 compact 后自动重新加载
• 子目录中的 CLAUDE.md 需等待下次读取该目录时重新加载
• 纯对话中的指令不会持久化——应写入 CLAUDE.md

• ---

  五、最佳实践总结

  1. **CLAUDE.md 放"规则"，Auto Memory 放"学习"**：规则由你主动编写，学习由 Claude 自动积累

  2. **200 行上限**：保持 CLAUDE.md 精简，超出的内容用 path-scoped rules 拆分

  3. **具体化指令**：可验证的指令比模糊的指导有效得多

  4. **定期审查**：清理过时或冲突的指令，运行 /doctor 辅助优化

  5. **CLAUDE.local.md 用于个人偏好**：项目共享的放 CLAUDE.md，个人本地配置放 CLAUDE.local.md 并 gitignore

  6. **善用 @ 导入**：避免重复，但注意导入内容同样消耗上下文

  ---

  *注：本文内容整理自 Claude Code 官方文档，结合实践经验总结而成。Claude Code 版本 v2.1+ 适用。*