Claude 如何记住你的项目

通过 CLAUDE.md 文件向 Claude 提供持久化指令，并通过自动记忆功能让 Claude 自动积累学习经验。

每次 Claude Code 会话都以全新的上下文窗口开始。有两种机制可以跨会话传递知识：

• CLAUDE.md 文件：你撰写的指令，为 Claude 提供持久化上下文
• 自动记忆：Claude 根据你的纠正和偏好自行记录的笔记

本文涵盖：

• 编写和组织 CLAUDE.md 文件
• 使用 .claude/rules/ 将规则限定到特定文件类型
• 配置自动记忆，让 Claude 自动做笔记
• 故障排查，当指令未被遵循时

CLAUDE.md 与自动记忆

Claude Code 拥有两种互补的记忆系统。两者都会在每次对话开始时加载。Claude 将它们视为上下文，而非强制配置。若要无论 Claude 如何决定都阻止某个操作，请改用 PreToolUse 钩子。你的指令越具体、越简洁，Claude 遵循它们的一致性就越高。

当你希望引导 Claude 的行为时，使用 CLAUDE.md 文件。自动记忆让 Claude 无需手动操作即可从你的纠正中学习。

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

CLAUDE.md 文件

CLAUDE.md 文件是 markdown 文件，用于为项目、你的个人工作流或整个组织提供持久化指令。你用纯文本撰写这些文件；Claude 在每次会话开始时读取它们。

何时添加到 CLAUDE.md

将 CLAUDE.md 视为你记录"否则需要反复解释"的内容的地方。在以下情况添加：

• Claude 第二次犯同样的错误
• 代码审查发现了 Claude 本该了解的关于此代码库的问题
• 你在聊天中输入了与上次会话相同的纠正或澄清
• 新团队成员需要相同的上下文才能高效工作

只保留 Claude 在每次会话中都应该知道的事实：构建命令、约定、项目布局、"始终执行 X" 的规则。如果某条内容是一个多步骤流程，或仅与代码库的某一部分相关，请将其移至技能或路径限定规则。扩展功能概览涵盖了每种机制的使用时机。

选择 CLAUDE.md 文件的存放位置

CLAUDE.md 文件可以存放在多个位置，每个位置具有不同的范围。下表按加载顺序列出，从最广范围到最具体，因此项目指令会在用户指令之后出现在上下文中。

工作目录上方目录层级中的 CLAUDE.md 和 CLAUDE.local.md 文件在启动时完整加载。子目录中的文件在 Claude 读取这些目录中的文件时按需加载。完整的解析顺序请参阅 CLAUDE.md 文件如何加载。

对于大型项目，你可以使用项目规则将指令拆分为按主题分类的文件。规则允许你将指令限定到特定文件类型或子目录。

设置项目 CLAUDE.md

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

撰写有效的指令

CLAUDE.md 文件在每次会话开始时加载到上下文窗口中，与你的对话一起消耗 token。上下文窗口可视化展示了 CLAUDE.md 相对于其余启动上下文的加载位置。由于它们是上下文而非强制配置，你撰写指令的方式会影响 Claude 遵循它们的可靠性。具体、简洁、结构良好的指令效果最佳。

大小：每个 CLAUDE.md 文件目标控制在 200 行以内。较长的文件会消耗更多上下文并降低遵循度。如果你的指令内容不断增长，请使用路径限定规则，使指令仅在 Claude 处理匹配文件时加载。你也可以将内容拆分为@path 导入以组织内容，但导入的文件仍会在启动时加载并进入上下文窗口。

结构：使用 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 一起展开并加载到上下文中。

允许相对路径和绝对路径。相对路径相对于包含导入的文件解析，而非工作目录。导入的文件可以递归导入其他文件，最大深度为四层。

导入解析会跳过 Markdown 代码跨度和围栏代码块。若要在 CLAUDE.md 中提及路径而不导入它，请用反引号包裹：写作 `@README` 保持文本原样，而反引号外的 @README 会导入文件。

要引入 README、package.json 和工作流指南，请在 CLAUDE.md 的任何位置使用 @ 语法引用它们：

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 工作树中工作，被 git 忽略的 CLAUDE.local.md 只存在于你创建它的工作树中。要跨工作树共享个人指令，请改为从主目录导入文件：

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

若要更有条理地组织指令，请参阅 .claude/rules/。

AGENTS.md

Claude Code 读取 CLAUDE.md，而非 AGENTS.md。如果你的仓库已为其他编码代理使用 AGENTS.md，请创建一个导入它的 CLAUDE.md，以便两个工具读取相同指令而无需重复。你也可以在导入下方添加 Claude 特定的指令。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、.devin/rules/ 和 .windsurfrules。

CLAUDE.md 文件如何加载

Claude Code 通过从当前工作目录向上遍历目录树来读取 CLAUDE.md 文件，沿途检查每个目录中的 CLAUDE.md 和 CLAUDE.local.md 文件。这意味着如果你在 foo/bar/ 中运行 Claude Code，它会加载 foo/bar/CLAUDE.md、foo/CLAUDE.md 以及任何并存的 CLAUDE.local.md 文件。

所有发现的文件会被连接（concatenate）到上下文中，而非相互覆盖。在目录树中，内容按从文件系统根目录到工作目录的顺序排列。对于 foo/bar/ 示例，foo/CLAUDE.md 在上下文中出现在 foo/bar/CLAUDE.md 之前，因此更接近你启动 Claude 位置的指令最后被读取。在每个目录中，CLAUDE.local.md 会追加在 CLAUDE.md 之后，因此你的个人备注是该层级 Claude 最后读取的内容。

Claude 还会发现当前工作目录下方子目录中的 CLAUDE.md 和 CLAUDE.local.md 文件。它们不会在启动时加载，而是在 Claude 读取这些子目录中的文件时被包含。

如果你在大型 monorepo 中工作，其他团队的 CLAUDE.md 文件被意外加载，请使用 claudeMdExcludes 跳过它们。关于根目录和按目录 CLAUDE.md 文件及规则的完整布局，请参阅 Monorepos 和大型仓库。

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 处理匹配文件时加载到上下文中，减少噪音并节省上下文空间。

设置规则

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

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

没有 paths 前置元数据 的规则会在启动时加载，优先级与 .claude/CLAUDE.md 相同。

路径特定规则

规则可以使用带有 paths 字段的 YAML 前置元数据限定到特定文件。这些条件规则仅在 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 读取匹配模式的文件时触发，而非在每次工具使用时触发。从 v2.1.198 开始，当 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，适用于机器上的所有用户。此文件无法通过个人设置排除。

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

范围：机器上的每次 Claude Code 会话，在每个仓库中。对于仓库特定指南，请提交项目 CLAUDE.md。

优先级：与托管 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 和规则目录。将其添加到 .claude/settings.local.json，使排除仅适用于你的机器：

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

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

托管策略 CLAUDE.md 文件无法被排除。这确保组织级指令始终适用，不受个人设置影响。

自动记忆

自动记忆让 Claude 无需你编写任何内容即可跨会话积累知识。Claude 在工作时为自己保存笔记：构建命令、调试洞察、架构笔记、代码风格偏好和工作流习惯。Claude 并非每次会话都保存内容。它会根据信息在未来对话中的有用性来决定是否值得记住。

启用或禁用自动记忆

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

{
  "autoMemoryEnabled": false
}

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

存储位置

每个项目都有自己的记忆目录，位于 ~/.claude/projects/<project>/memory/。<project> 路径派生自 git 仓库，因此同一仓库内的所有工作树和子目录共享一个自动记忆目录。在 git 仓库外，使用项目根目录代替。

要将自动记忆存储在不同位置，请在 settings.json 中设置 autoMemoryDirectory。它从任何设置范围读取：用户、项目、本地、策略或 --settings。

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

该值必须是绝对路径或以 ~/ 开头。当设置在项目的 .claude/settings.json 或 .claude/settings.local.json 中时，只有在你接受该文件夹的工作区信任对话框后才会生效，与钩子受相同的门禁控制。

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

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

MEMORY.md 充当记忆目录的索引。Claude 在整个会话中读取和写入该目录中的文件，使用 MEMORY.md 来跟踪存储内容的位置。

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

工作原理

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 和规则文件，允许你开启或关闭自动记忆，并提供打开自动记忆文件夹的链接。选择任何文件即可在编辑器中打开它。

当你要求 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。这必须在每次调用时传递，因此更适合脚本和自动化，而非交互式使用。

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

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

我的 CLAUDE.md 太大

超过 200 行的文件会消耗更多上下文并可能降低遵循度。使用路径限定规则仅在 Claude 处理匹配文件时加载指令，或修剪非每次会话必需的内容。拆分为 @path 导入有助于组织，但不会减少上下文，因为导入的文件仍在启动时加载。

指令在 /compact 后似乎丢失

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

如果指令在压缩后消失，它要么仅在对话中给出，要么位于尚未重新加载的嵌套 CLAUDE.md 中。将仅对话中的指令添加到 CLAUDE.md 以使其持久化。有关完整说明，请参阅压缩后保留的内容。

有关大小、结构和具体性的指导，请参阅撰写有效的指令。

相关资源

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