Claude Code 每次会话都从空上下文开始，但两种机制让知识跨会话传递：CLAUDE.md（你写的持久指令，按目录层级自动加载）和 Auto Memory（Claude 根据你的纠正自动写入的笔记）。CLAUDE.md 支持 @import 导入其他文件、.claude/rules/ 路径限定规则、AGENTS.md 别名兼容。配置好这两种机制，能让 Claude 在不同项目中保持一致的行为风格，不用每次重复解释同样的事。

Claude Code 记忆系统 - CLAUDE.md 配置、Rules 规则与自动记忆 #

Claude Code 每次会话都从全新的上下文开始，但两种机制可以让知识跨会话传递：

• CLAUDE.md 文件：你写的持久指令，每次会话开始时自动读取
• 自动记忆（Auto Memory）：Claude 根据你的纠正和偏好自动写入的笔记

页面涵盖以下内容：

• 如何编写和组织 CLAUDE.md 文件
• 使用 .claude/rules/ 将规则限定到特定文件类型
• 配置自动记忆 让 Claude 自动记录笔记
• 排查指令不被遵循的问题

CLAUDE.md vs 自动记忆 #

Claude Code 有两套互补的记忆系统，都在每次对话开始时加载。Claude 把它们当作上下文而非强制配置。指令写得越具体、越简洁，Claude 遵循得越一致。

需要引导 Claude 行为时用 CLAUDE.md。自动记忆让 Claude 从你的纠正中学习，无需手动操作。

子代理也可以维护独立的自动记忆，详见子代理配置。

CLAUDE.md 文件 #

CLAUDE.md 文件是给 Claude 持久指令的 Markdown 文件，适用于项目、个人工作流或整个组织。纯文本编写，Claude 在每次会话开始时读取。

何时添加到 CLAUDE.md #

把 CLAUDE.md 当成你不想反复解释的内容的存放地。以下情况建议添加：

• Claude 犯了同一个错误第二次
• 代码审查发现了 Claude 本应知道的项目知识
• 你在聊天中输入了上次会话也输入过的同样纠正或说明
• 新队友需要同样的上下文才能高效工作

只保留 Claude 在每次会话中都需要掌握的事实：构建命令、约定、项目布局、"始终做 X"的规则。如果是多步骤流程或只在某个代码区域才相关的内容，移到 skill 或路径限定规则中。

选择 CLAUDE.md 的位置 #

CLAUDE.md 可以放在多个位置，每个位置有不同的作用域。下面按加载顺序排列，从最宽到最具体：项目指令在用户指令之后出现。

工作目录以上层级中的 CLAUDE.md 和 CLAUDE.local.md 在启动时完整加载。子目录中的文件在 Claude 读取这些目录中的文件时才按需加载。完整的解析顺序见 CLAUDE.md 加载机制。

对于大型项目，可以用项目规则将指令拆分到不同主题的文件中，规则可以限定到特定文件类型或子目录。

设置项目 CLAUDE.md #

项目 CLAUDE.md 可以放在 ./CLAUDE.md 或 ./.claude/CLAUDE.md。创建这个文件并添加适用于所有项目成员的指令：构建和测试命令、编码规范、架构决策、命名约定和常见工作流。这些指令通过版本控制与团队共享，所以聚焦于项目级标准，而不是个人偏好。

运行 /init 可以自动生成初始 CLAUDE.md。Claude 分析你的代码库，生成包含构建命令、测试指令和发现的项目约定的文件。如果 CLAUDE.md 已存在，/init 会建议改进而非覆盖。之后根据 Claude 无法自行发现的指令进行完善。

设置 CLAUDE_CODE_NEW_INIT=1 启用交互式多阶段流程。/init 会询问要设置哪些制品：CLAUDE.md 文件、技能和钩子。然后它用子代理探索代码库，通过追问填补空白，并在写入文件前呈现一个可审阅的提案。

编写有效的指令 #

CLAUDE.md 文件在每次会话开始时加载到上下文窗口，与对话一起消耗token。由于它们是上下文而非强制配置，指令的写法影响 Claude 遵循的可靠性。具体、简洁、结构良好的指令效果最好。

大小：每个 CLAUDE.md 文件目标控制在200行以内。文件越长，上下文消耗越多，遵守率越低。如果指令越来越多，用路径限定规则让指令只在 Claude 处理匹配文件时才加载。也可以通过 import 拆分文件来组织，但引入的文件仍然会在启动时加载进入上下文。

结构：用 Markdown 标题和列表分组相关指令。Claude 扫描结构的方式和读者一样——有组织的分节比密集段落更容易遵守。

具体性：写出具体可验证的指令。例如：

• “使用 2 空格缩进"而不是"正确格式化代码”
• “提交前运行 npm test"而不是"测试你的改动”
• "API 处理器放在 src/api/handlers/“而不是"保持文件有组织”

一致性：如果两条规则互相矛盾，Claude 可能随机选一条。定期检查 CLAUDE.md、子目录中的嵌套 CLAUDE.md 和 .claude/rules/ 文件，删除过时或冲突的指令。在 monorepo 中，使用 claudeMdExcludes 跳过其他团队不相关的 CLAUDE.md。

引入外部文件 #

CLAUDE.md 文件可以用 @path/to/import 语法引入额外文件。被引入的文件在会话开始时随 CLAUDE.md 一起展开加载到上下文中。

支持相对路径和绝对路径。相对路径相对于包含 import 的文件解析，而不是工作目录。引入文件可以递归引入其他文件，最多嵌套5层。

在 CLAUDE.md 中用 @ 语法引用 README、package.json 和工作流指南：

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

对于不应提交到版本控制的私有项目偏好，在项目根目录创建 CLAUDE.local.md。它和 CLAUDE.md 一起加载，效果相同。把 CLAUDE.local.md 加入 .gitignore；运行 /init 并选择个人选项时会自动完成这一步。

如果你在同一仓库的多个 git worktree 中工作，被 gitignore 的 CLAUDE.local.md 只存在于你创建它的 worktree 中。要跨 worktree 共享个人指令，改为从主目录引入：

# Individual Preferences
- @~/.claude/my-project-instructions.md

Claude Code 首次遇到项目中的外部 import 时，会显示一个批准对话框列出文件。如果拒绝，import 保持禁用且对话框不再出现。

要更结构化的组织方式，见 .claude/rules/。

AGENTS.md 兼容 #

Claude Code 读取 CLAUDE.md，不读取 AGENTS.md。如果你的仓库已经在用 AGENTS.md（供其他编程代理使用），可以创建一个引入它的 CLAUDE.md，让两个工具读取相同的指令而不重复维护。在引入下面还可以加 Claude 专属指令：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

如果不需要加 Claude 专属内容，也可以用符号链接：

ln -s AGENTS.md CLAUDE.md

在 Windows 上创建符号链接需要管理员权限或开发者模式，建议用 @AGENTS.md 引入。

在已有 AGENTS.md 的仓库中运行 /init 会读取它并将相关内容合并到生成的 CLAUDE.md 中。它也会读取其他工具的配置如 .cursorrules 和 .windsurfrules。

CLAUDE.md 加载机制 #

Claude Code 从当前工作目录向上遍历目录树，在沿途每个目录中查找 CLAUDE.md 和 CLAUDE.local.md 文件。如果你在 foo/bar/ 中运行 Claude Code，它会加载 foo/bar/CLAUDE.md、foo/CLAUDE.md 以及它们旁边的 CLAUDE.local.md 文件。

所有找到的文件被拼接进上下文，而不是相互覆盖。在目录树中，内容从文件系统根向下到工作目录排序。在 foo/bar/ 的例子中，foo/CLAUDE.md 在 foo/bar/CLAUDE.md 之前出现，所以离启动目录更近的指令最后被读取。在每个目录内，CLAUDE.local.md 追加在 CLAUDE.md 之后，所以你的个人笔记是 Claude 在该层级读到的最后内容。

Claude 也会发现当前工作目录的子目录下的 CLAUDE.md 和 CLAUDE.local.md 文件，但不在启动时加载，而是当 Claude 读取那些子目录的文件时才引入。

如果你在大型 monorepo 中工作，可能会加载其他团队的 CLAUDE.md，使用 claudeMdExcludes 跳过它们。

CLAUDE.md 文件中的块级 HTML 注释（<!-- maintainer notes -->）在注入到 Claude 上下文前会被去掉。用它们给人类维护者留注释，而不消耗上下文 token。代码块内的注释不受影响。当你直接用 Read 工具打开 CLAUDE.md 文件时，注释仍然可见。

从额外目录加载 #

--add-dir 标志让 Claude 访问主工作目录之外的其它目录。默认情况下，这些目录中的 CLAUDE.md 文件不会被加载。

要从额外目录也加载记忆文件，设置环境变量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD：

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

这会从额外目录加载 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md 和 CLAUDE.local.md。如果你在 --setting-sources 中排除了 local，则跳过 CLAUDE.local.md。

用 .claude/rules/ 组织规则 #

对于大型项目，可以用 .claude/rules/ 目录把指令组织到多个文件。这使指令模块化，团队更容易维护。规则还可以限定到特定文件路径，只在 Claude 处理匹配文件时才加载到上下文，减少噪音并节省上下文空间。

规则在每次会话或打开匹配文件时加载到上下文。对于不需要始终在上下文中的任务专用指令，使用 skills 替代，skills 只在调用时或 Claude 认为相关时才加载。

设置规则 #

在项目的 .claude/rules/ 目录中放 Markdown 文件。每个文件覆盖一个主题，文件名要描述性，如 testing.md 或 api-design.md。所有 .md 文件会被递归发现，所以你可以把规则组织到子目录如 frontend/ 或 backend/：

your-project/
├── .claude/
│   ├── CLAUDE.md           # 主项目指令
│   └── rules/
│       ├── code-style.md   # 代码风格规范
│       ├── testing.md      # 测试约定
│       └── security.md     # 安全要求

没有 paths frontmatter 的规则在启动时加载，优先级与 .claude/CLAUDE.md 相同。

路径限定规则 #

规则可以用 YAML frontmatter 的 paths 字段限定作用范围。这些条件规则只在 Claude 处理匹配指定模式的文件时才应用。

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

没有 paths 字段的规则无条件加载，适用于所有文件。路径限定规则在 Claude 读取匹配模式的文件时触发，而非每次工具使用。

在 paths 字段中使用 glob 模式匹配不同扩展名、目录或任意组合：

可以指定多个模式，并用大括号扩展匹配多个扩展名：

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

用符号链接跨项目共享规则 #

.claude/rules/ 目录支持符号链接，所以你可以在多个项目中维护并链接一套共享规则。符号链接被正常解析加载，循环符号链接会被检测并妥善处理。

此示例链接了一个共享目录和一个单独文件：

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

用户级规则 #

~/.claude/rules/ 中的个人规则适用于你机器上的每个项目。用于非项目特定的偏好：

~/.claude/rules/
├── preferences.md    # 你的个人编码偏好
└── workflows.md      # 你的首选工作流

用户级规则在项目规则之前加载，项目规则优先级更高。

管理大型团队的 CLAUDE.md #

对于跨团队部署 Claude Code 的组织，可以集中管理指令并控制哪些 CLAUDE.md 文件被加载。

部署组织级 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

使用 MDM、Group Policy、Ansible 或类似工具将文件分发到开发者机器。详见托管设置了解其他组织级配置选项。

claudeMd 键允许你将托管 CLAUDE.md 的内容直接放在 managed-settings.json 中，而无需部署单独的文件。

作用域：机器上的每个 Claude Code 会话，在每个仓库中。对于仓库特定的指导，改为提交项目 CLAUDE.md。

优先级：与托管 CLAUDE.md 文件相同。在用户、项目或本地设置之前加载。

生效位置：仅托管和政策设置。在用户、项目或本地设置中设置 claudeMd 无效。

以下示例将行为指令直接添加到托管设置文件中：

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

托管 CLAUDE.md 和托管设置用途不同。设置用于技术强制执行，CLAUDE.md 用于行为指导：

设置规则由客户端强制执行，无论 Claude 决定做什么。CLAUDE.md 指令塑造 Claude 的行为，但不是硬性执行层。

排除特定 CLAUDE.md 文件 #

在大型 monorepo 中，上级目录的 CLAUDE.md 文件可能包含与你工作无关的指令。claudeMdExcludes 设置允许你按路径或 glob 模式跳过特定文件。

此示例排除了顶级 CLAUDE.md 和一个父文件夹的 rules 目录。添加到 .claude/settings.local.json 中使排除仅应用于本地机器：

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

模式使用 glob 语法匹配绝对文件路径。你可以在任何设置层配置 claudeMdExcludes：用户、项目、本地或托管政策。数组跨层合并。

托管政策 CLAUDE.md 不能被排除。这确保组织级指令始终应用，无论个人设置如何。

自动记忆 #

自动记忆让 Claude 在会话之间自动积累知识，无需你手动写任何东西。Claude 会保存它认为有用的笔记：构建命令、调试发现、架构说明、代码风格偏好和工作流习惯。Claude 不会每次会话都保存，而是根据信息在未来会话中的有用性来决定是否记录。

自动记忆需要 Claude Code v2.1.59 或更高版本。用 claude --version 检查你的版本。

开关自动记忆 #

自动记忆默认开启。要切换，在会话中运行 /memory 并使用自动记忆开关，或在项目设置中设置 autoMemoryEnabled：

{
  "autoMemoryEnabled": false
}

通过环境变量禁用自动记忆：设置 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

存储位置 #

每个项目有独立的记忆目录：~/.claude/projects/<project>/memory/。<project> 路径从 git 仓库派生，所以同一仓库的所有 worktree 和子目录共享一个自动记忆目录。在 git 仓库之外，使用项目根目录。

要将自动记忆存到不同位置，在用户设置 ~/.claude/settings.json 中设置 autoMemoryDirectory：

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

值必须是绝对路径或始于 ~/。此设置从政策和用户设置以及 --settings 标志接收。不从项目或本地设置接收，因为这两个文件都位于项目目录内，克隆的仓库可能重定向自动记忆写入到敏感位置。

目录包含一个 MEMORY.md 入口文件和可选的主题文件：

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁索引，每次会话都加载
├── debugging.md       # 调试模式的详细笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 创建的其他主题文件

MEMORY.md 作为记忆目录的索引。Claude 在整个会话中读写此目录中的文件，用 MEMORY.md 跟踪每个文件存储了什么。

自动记忆是机器本地的。同一 git 仓库的所有 worktree 和子目录共享一个自动记忆目录。文件不会跨机器或云端环境共享。

工作原理 #

MEMORY.md 的前 200 行，或前 25KB（以先到者为准），在每次对话开始时加载。超过此阈值的内容不会在会话启动时加载。Claude 通过将详细笔记移动到单独的主题文件来保持 MEMORY.md 简洁。

此限制仅适用于 MEMORY.md。CLAUDE.md 文件无论多长都完整加载，但较短的文件产生更好的遵守率。

主题文件如 debugging.md 或 patterns.md 不会在启动时加载。Claude 在需要时使用标准文件工具按需读取。

Claude 在你的会话期间读写记忆文件。当你在 Claude Code 界面中看到"Writing memory"或"Recalled memory"时，Claude 正在主动更新或读取 ~/.claude/projects/<project>/memory/。

查看和编辑记忆 #

自动记忆文件是纯文本 Markdown，可以随时编辑或删除。从会话中运行 /memory 来浏览和打开记忆文件。

用 /memory 查看和编辑 #

/memory 命令列出当前会话中加载的所有 CLAUDE.md、CLAUDE.local.md 和 rules 文件，提供自动记忆的开关，并提供打开自动记忆文件夹的链接。选择任何文件在编辑器中打开。

当你要求 Claude 记住某事时，比如"始终使用 pnpm，不要用 npm"或"记住：API 测试需要本地 Redis 实例"，Claude 会将其保存到自动记忆。要改为添加到 CLAUDE.md，直接告诉 Claude"把这个加到 CLAUDE.md"，或通过 /memory 自行编辑文件。

排查记忆问题 #

以下是 CLAUDE.md 和自动记忆最常见的问题及调试方法。

Claude 不遵循我的 CLAUDE.md #

CLAUDE.md 内容作为用户消息在系统提示之后传递，而不是系统提示本身的一部分。Claude 读取并尝试遵循，但对于模糊或冲突的指令，没有严格合规的保证。

调试方法：

• 运行 /memory 确认你的 CLAUDE.md 和 CLAUDE.local.md 文件已被加载。如果文件未列出，Claude 无法看到它。
• 检查相关的 CLAUDE.md 是否放在你的会话会加载的位置（见选择 CLAUDE.md 的位置）。
• 让指令更具体。"使用 2 空格缩进"比"格式化代码"有效得多。
• 查找 CLAUDE.md 文件间的冲突指令。如果两个文件对同一行为给出不同指导，Claude 可能随机选一个。

如果指令必须在特定点执行，例如每次提交前或每次文件编辑后，改为写成钩子。钩子作为 shell 命令在固定生命周期事件执行，无论 Claude 决定做什么都生效。

对于希望放在系统提示级别的指令，使用 --append-system-prompt。这必须在每次调用时传递，所以更适合脚本和自动化而非交互式使用。

使用 InstructionsLoaded 钩子 来记录加载了哪些指令文件、何时加载以及原因。这对调试路径限定规则或子目录中的延迟加载文件很有用。

我不知道自动记忆保存了什么 #

运行 /memory 并选择自动记忆文件夹来浏览 Claude 保存的内容。所有内容都是可读、可编辑、可删除的纯文本 Markdown。

我的 CLAUDE.md 太大了 #

超过 200 行的文件消耗更多上下文，可能降低遵守率。使用路径限定规则让指令只在 Claude 处理匹配文件时才加载，或修剪不需要每次会话都保留的内容。拆分为 @path imports 有助于组织，但不会减少上下文消耗，因为引入的文件在启动时加载。

/compact 后指令似乎丢失了 #

项目根目录的 CLAUDE.md 在压缩后存活：/compact 后，Claude 从磁盘重新读取并重新注入会话。子目录中的嵌套 CLAUDE.md 不会自动重新注入；它们会在 Claude 下次读取该子目录的文件时重新加载。

如果压缩后某条指令消失了，它要么只存在于对话中，要么位于尚未重新加载的嵌套 CLAUDE.md 中。将仅对话的指令加入 CLAUDE.md 使其持久。详见压缩后什么会存活。

有关大小、结构和具体性的指导，见编写有效的指令。

相关资源 #

• 调试你的配置：诊断 CLAUDE.md 或设置为何不生效
• 技能：打包可按需加载的可复用工作流
• 设置：用设置文件配置 Claude Code 行为
• 子代理记忆：让子代理维护独立的自动记忆

常见问题 #

Claude 不遵循 CLAUDE.md 里的指令怎么办？ #

运行 /memory 确认文件已被加载。检查文件位置是否正确（项目根目录、.claude/ 或用户目录）。让指令更具体，比如把"格式化代码"改成"使用 2 空格缩进"。检查是否有多个 CLAUDE.md 文件包含冲突的指令。如果问题持续，考虑用钩子（hook）代替 CLAUDE.md 来强制执行必须执行的命令。

自动记忆和 CLAUDE.md 有什么区别？ #

CLAUDE.md 是你手动编写并提交到版本控制的持久指令，适合编码规范、项目架构等需要确定性遵守的内容。自动记忆是 Claude 根据你的纠正和偏好自动生成的笔记，适合构建命令、调试发现这类不需要你手动维护的信息。两种机制在每次会话开始时都加载，但 CLAUDE.md 完整加载，自动记忆只加载前 200 行或 25KB。

在 monorepo 中加载了其他团队的 CLAUDE.md 怎么解决？ #

在 .claude/settings.local.json 中使用 claudeMdExcludes 设置跳过指定路径的文件。例如 "claudeMdExcludes": ["**/other-team/**/CLAUDE.md"]。托管政策级别的 CLAUDE.md 不能被排除。