Claude 如何记住您的项目

使用 CLAUDE.md 或 AGENTS.md 文件为 Claude 提供持久指令，并让 Claude 通过自动记忆自动积累学习。

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

• CLAUDE.md 文件：您编写的指令，为 Claude 提供持久上下文。Claude 也可以读取存储库的 AGENTS.md 文件，单独使用或与 CLAUDE.md 一起使用
• 自动记忆：Claude 根据您的更正和偏好自己编写的笔记

本页面涵盖以下内容：

• 编写和组织 CLAUDE.md 文件
• 使用现有 AGENTS.md 作为您的项目指令，单独使用或与 CLAUDE.md 一起使用
• 使用 .claude/rules/ 将规则范围限定为特定文件类型
• 配置自动记忆，以便 Claude 自动记笔记
• 故障排除当指令未被遵循时

CLAUDE.md 与自动记忆

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

当你想指导 Claude 的行为时，使用 CLAUDE.md 文件。自动记忆让 Claude 从你的更正中学习，无需手动操作。

Subagents 也可以维护自己的自动记忆。有关详细信息，请参阅 subagent 配置。

CLAUDE.md 文件

CLAUDE.md 文件是 markdown 文件，为 Claude 提供项目、个人工作流或整个组织的持久指令。您用纯文本编写这些文件；Claude 在每个会话开始时读取它们。如果您的存储库改用 AGENTS.md，请参阅 AGENTS.md。

何时添加到 CLAUDE.md

将 CLAUDE.md 视为您写下本来需要重新解释的内容的地方。在以下情况下添加到它：

• Claude 第二次犯同样的错误
• 代码审查发现 Claude 应该了解的关于此代码库的内容
• 您在聊天中输入的相同更正或澄清是您上一个会话中输入的
• 新队友需要相同的上下文才能提高生产力

将其保持为 Claude 应该在每个会话中保留的事实：构建命令、约定、项目布局、"始终执行 X"规则。如果条目是多步骤过程或仅对代码库的一部分重要，请将其移至 skill 或 path-scoped rule 代替。扩展概述 涵盖何时使用每种机制。

选择 CLAUDE.md 文件的位置

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

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

对于大型项目，您可以使用 project rules 将指令分解为特定主题的文件。规则允许您将指令范围限定为特定文件类型或子目录。

设置项目 CLAUDE.md

项目 CLAUDE.md 可以存储在 ./CLAUDE.md 或 ./.claude/CLAUDE.md 中。创建此文件并添加适用于在项目上工作的任何人的指令：构建和测试命令、编码标准、架构决策、命名约定和常见工作流。这些指令通过版本控制与您的团队共享，因此请关注项目级标准而不是个人偏好。要确认文件已加载，请在会话中运行 /context 并检查 Memory files 下的列表。

编写有效的指令

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

大小：每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度。如果您的指令变得很大，请使用 path-scoped rules，以便指令仅在 Claude 处理匹配文件时加载。您也可以将内容拆分为 imports 以便组织，尽管导入的文件仍然加载并在启动时进入上下文窗口。

结构：使用 markdown 标题和项目符号来分组相关指令。Claude 扫描结构的方式与读者相同：有组织的部分比密集段落更容易遵循。

具体性：编写具体到足以验证的指令。例如：

• "使用 2 空格缩进"而不是"正确格式化代码"
• "在提交前运行 npm test"而不是"测试您的更改"
• "API 处理程序位于 src/api/handlers/"而不是"保持文件有组织"

一致性：如果两条规则相互矛盾，Claude 可能会任意选择一条。定期审查您的 CLAUDE.md 文件、子目录中的嵌套 CLAUDE.md 文件和 .claude/rules/，以删除过时或冲突的指令。在 monorepos 中，使用 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 以便不提交它。设置 CLAUDE_CODE_NEW_INIT=1 后，运行 /init 并选择个人选项会为您执行此操作。

如果您在同一存储库的多个 git worktrees 中工作，gitignored CLAUDE.local.md 仅存在于您创建它的 worktree 中。要在 worktrees 中共享个人指令，请改为从您的主目录导入文件：

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

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 的位置的指令最后读取。在每个目录中，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 的上下文之前被剥离。使用它们为人类维护者留下笔记，而不在注释上花费上下文令牌。代码块内的注释被保留。当您直接使用 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

内联形式为该单次启动在 Bash 或 Zsh 中设置变量。要为每个会话保持它，请将其添加到 ~/.claude/settings.json 中的 env 块，如 设置环境变量 中所示。

这从其他目录加载 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md 和 CLAUDE.local.md。如果您从 --setting-sources 中排除 local，则跳过 CLAUDE.local.md。

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

对于较大的项目，您可以使用 .claude/rules/ 目录将指令组织到多个文件中。这使指令模块化并更容易让团队维护。规则也可以 范围限定到特定文件路径，因此它们仅在 Claude 处理匹配文件时加载到上下文中，减少噪音并节省上下文空间。

设置规则

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

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

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

如果您从 --setting-sources 中排除 project，项目规则被跳过。在 v2.1.211 之前，加载按需的规则，包括路径范围规则和嵌套 .claude/rules/ 目录中的规则，即使 project 被排除也会加载。

路径特定规则

规则可以使用带有 paths 字段的 YAML frontmatter 范围限定到特定文件。这些条件规则仅在 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"
---

每个大括号组将扩展的模式数量相乘：src/*.{ts,tsx} 扩展为两个模式，{a,b}/{c,d}/*.{ts,tsx} 扩展为八个。为了保持扩展有界，规则的整个 paths 列表共享一个 1,000 个扩展模式和 4 MiB 的预算，没有大括号的模式不计入其中。

Claude Code 使用任何会超过预算的未展开模式，其字面大括号不匹配任何文件。在 v2.1.217 之前，具有许多大括号组的 paths 值在启动时使 CLI 停滞或崩溃。

Glob 语法将 [ 视为括号表达式的开始，例如 [abc]。具有无法读作括号表达式的 [ 的模式，例如 photos [2024/**，是无效的：它不匹配任何内容，规则的其他模式继续工作。要匹配文件名中的字面 [，请将其转义为 photos \[2024/**。在 v2.1.207 之前，一个无效模式使 Read 工具对规则被评估的每个文件失败，而不是不匹配任何内容。

规则 frontmatter 参考

使用 YAML frontmatter 在文件顶部的 --- 标记之间配置规则。paths 是 Claude Code 从规则中读取的唯一字段；任何其他字段都被忽略而不出现错误。Claude Code 在将规则加载到上下文之前删除 frontmatter。

如果标记之间的 YAML 不解析，Claude Code 忽略 frontmatter 并加载规则，就像它没有 paths 一样。运行 claude --debug 查看解析错误。

使用符号链接在项目间共享规则

.claude/rules/ 目录支持符号链接，因此您可以维护一组共享规则并将它们链接到多个项目中。循环符号链接被检测并妥善处理。

Claude Code 将其目标在工作目录外的符号链接视为 external import。链接的规则不加载，直到您批准项目的外部导入，之后仅加载没有 paths 字段 的规则。Claude Code 仅当项目内存文件使用 @path 导入工作目录外的文件时才要求该批准，而不是仅针对符号链接。要加载共享规则而不需要该批准，请将它们保存在 ~/.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    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

Claude Code 在项目规则之前加载用户级规则，因此项目规则在 Claude 的上下文中出现在用户规则之后。两个集合都不会覆盖另一个：如果用户规则和项目规则冲突，Claude 可能会遵循任一个，因此保持两者一致。

为大型团队管理 CLAUDE.md

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

部署组织范围的 CLAUDE.md

组织可以部署一个集中管理的 CLAUDE.md，适用于机器上的所有用户。此文件无法通过个人设置排除。

claudeMd 键允许您将托管 CLAUDE.md 内容直接放入 managed-settings.json 中，而不是部署单独的文件。

范围：机器上的每个 Claude Code 会话，在每个存储库中。对于存储库特定的指导，改为提交项目 CLAUDE.md。

优先级：与托管 CLAUDE.md 文件相同。在用户和项目 CLAUDE.md 之前加载。

在哪里被遵守：仅托管和策略设置。在用户、项目或本地设置中设置 claudeMd 无效。

下面的示例直接在托管设置文件中添加行为指令：

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

托管 CLAUDE.md 和 managed settings 服务于不同的目的。使用设置进行技术强制，使用 CLAUDE.md 进行行为指导：

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

排除特定的 CLAUDE.md 文件

在大型 monorepos 中，祖先 CLAUDE.md 文件可能包含与您的工作无关的指令。claudeMdExcludes 设置允许您按路径或 glob 模式跳过特定文件。

此示例排除顶级 CLAUDE.md 和来自父文件夹的规则目录。将其添加到 .claude/settings.local.json 以使排除保持本地到您的机器：

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

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

要排除您通过 symlink 到达的规则文件，无论文件还是其目录是链接，请针对任一路径编写模式：文件在 .claude/rules/ 下的路径或其链接目标。匹配任一路径的模式排除文件。在 v2.1.239 之前，仅匹配链接目标的模式排除文件。

托管策略 CLAUDE.md 文件无法排除。这确保组织范围指令始终适用，无论个人设置如何。

AGENTS.md

Claude Code 可以将 AGENTS.md 作为您的项目说明读取，因此已为其他编码代理设置的存储库无需添加 CLAUDE.md、导入或设置即可工作。此表显示了存储库中指令文件的每种组合下 Claude 默认读取的内容：

要更改默认值，例如让 Claude 始终读取两个文件、仅读取 CLAUDE.md 或仅读取您组织的托管说明，请更改项目说明设置。

Claude Code 何时读取 AGENTS.md

默认情况下，Claude 仅在您的工作目录或其上方没有 CLAUDE.md 时才读取 AGENTS.md。以下是此检查中计数的文件：

• 计数，因此 Claude 读取它们而不是 AGENTS.md：您的工作目录或其上方任何目录中的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md
• 不计数，并继续与 AGENTS.md 一起加载：您的 ~/.claude/CLAUDE.md、您组织的托管 CLAUDE.md 和 .claude/rules/ 文件

当没有计数时，以下是 Claude 读取的内容以及您如何判断：

• 在会话开始时：您的工作目录和其上方目录中的每个 AGENTS.md 和 .claude/AGENTS.md。在交互式会话中，您会看到一行，例如 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 在对话中
• 当 Claude 在子目录中工作时：当 Claude 使用 Read 工具打开该处的文件且该子目录没有三个 CLAUDE.md 文件中的任何一个时，子目录的 AGENTS.md
• 在每个 AGENTS.md 内：@path 导入被展开，claudeMdExcludes 模式适用，跳过项目说明的子代理也会跳过这些文件
• 不读取：AGENTS.local.md、AGENTS.override.md 或 .agents/ 目录下的任何内容

选择加载哪些说明文件

要更改 Claude 读取的文件，请在 Claude Code 会话中键入 /config 以打开设置面板，然后将项目说明设置为以下值之一：

您也可以在设置文件中设置该值，而不是在 /config 中。在 pluginConfigs 中的内置 agents-md 插件的 ID 下添加它，在 ~/.claude/settings.json、--settings 文件或托管设置中。Claude Code 在项目和本地设置文件中忽略它。此示例让 Claude 读取两个文件：

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

您的更改从您发送的下一条消息和每个新会话中应用。

当 AGENTS.md 支持不可用时

在这些会话中，Claude 仅读取 CLAUDE.md 文件，项目说明不会出现在 /config 设置面板中：

• 您使用的是 v2.1.277 之前的 Claude Code 版本
• 您在 /plugin 中禁用了内置 agents-md 插件
• 在某些情况下，这是您从 v2.1.276 或更早版本升级后的第一个会话。Claude 从您的下一个会话开始读取 AGENTS.md

在 v2.1.281 之前，某些会话，例如在 Amazon Bedrock 上或禁用遥测的会话，仅读取 CLAUDE.md 文件。在这些版本上，更新 Claude Code。要在这些会话中向 Claude 提供您的 AGENTS.md，请从 CLAUDE.md 中导入它。

AGENTS.md 与 CLAUDE.md 的区别

通过项目说明设置读取的 AGENTS.md 与 CLAUDE.md 在以下方面有所不同：

删除早期的 AGENTS.md 解决方案

如果您在 Claude Code 自行读取 AGENTS.md 之前设置它来读取 AGENTS.md，以下是对每个常见设置的处理方法：

• 包含 @AGENTS.md 的 CLAUDE.md：您可以保留它。保留导入永远不会让 Claude 读取 AGENTS.md 两次，无论您使用哪个项目说明值。如果 CLAUDE.md 不包含其他内容，请删除它，或如果您的某些会话无法直接加载 AGENTS.md，请保留它。
• 告诉 Claude 用词语读取 AGENTS.md 的 CLAUDE.md：仅当 Claude 决定打开文件时，它才会看到 AGENTS.md。删除 CLAUDE.md 以便 Claude 直接读取 AGENTS.md，或用 @AGENTS.md 导入替换该句子。
• 符号链接到 AGENTS.md 的 CLAUDE.md：无，或删除符号链接。无论哪种方式，Claude 都会读取内容一次。
• 打印 AGENTS.md 的 SessionStart hook：删除它。一旦 Claude 直接读取 AGENTS.md，该 hook 会向上下文添加第二个副本。

与其他编码工具共享一个文件

当 Claude 不直接读取您的 AGENTS.md 时，您仍然可以通过在其旁边的 CLAUDE.md 中放置 @AGENTS.md 导入来将其保留为每个工具共享的一个文件。当您的项目也有 CLAUDE.md 时、当您已将项目说明设置为 claude-md 时，或在无法加载 AGENTS.md的会话中执行此操作。在导入下方添加任何 Claude 特定的说明，Claude 会先读取导入的文件，然后读取其余部分：

@AGENTS.md

## Claude Code

对 `src/billing/` 下的更改使用计划模式。

如果您不需要 Claude 特定的内容，符号链接也可以工作：

ln -s AGENTS.md CLAUDE.md

该命令在成功时不打印任何输出。在选择符号链接而不是导入之前，请检查这些约束：

• 编辑：Claude 通过链接读取 CLAUDE.md，但 Edit 和 Write 工具拒绝通过符号链接写入，拒绝指示 Claude 编辑链接的目标 AGENTS.md
• Windows：如果您或克隆存储库的任何人在 Windows 上工作，请改用 @AGENTS.md 导入。在那里创建符号链接需要管理员权限或开发人员模式，Git 会将提交的符号链接检出为纯文本文件，除非启用了 core.symlinks，这会使该克隆具有一行 CLAUDE.md 代替您的说明

使用任一方法，在您的下一个会话中运行 /context 并确认 CLAUDE.md 出现在内存文件下。

从其他工具迁移说明

运行 /init 会读取其他工具的说明文件并将相关部分合并到生成的 CLAUDE.md 中：

• .cursor/rules/ 或 .cursorrules 中的 Cursor 规则
• .github/copilot-instructions.md 中的 Copilot 规则
• 设置 CLAUDE_CODE_NEW_INIT=1 时：AGENTS.md、.devin/rules/、.windsurf/rules/ 或 .windsurfrules，以及 .clinerules

您也可以运行 /import 将支持的编码代理的配置引入 Claude Code，这会将 AGENTS.md 等说明文件的一次性副本追加到匹配的 CLAUDE.md，并携带 MCP 服务器、命令、子代理和 skills。需要 Claude Code v2.1.213 或更高版本。

自动记忆

自动记忆让 Claude 跨会话积累知识，无需你编写任何内容。在工作时，Claude 为自己保存四种笔记。Claude 在记忆文件的 frontmatter 中用 type 字段记录类型：

• user：你的角色、专业知识和工作偏好
• feedback：你给 Claude 的更正和你确认的方法
• project：正在进行的工作、截止日期和 Claude 无法从代码或 git 历史推导的决策
• reference：在项目外查找信息的位置，例如问题跟踪器或仪表板

Claude 跳过任何它可以从代码库推导的内容，例如架构、文件路径或调试修复。它也跳过你的 CLAUDE.md 文件已经说过的任何内容。

Claude 不会每个会话都保存内容。它根据信息在未来对话中是否有用来决定什么值得记住。

启用或禁用自动记忆

自动记忆默认开启。要切换它，在会话中打开 /memory 并使用自动记忆切换，它将 autoMemoryEnabled 保存到你的用户设置 ~/.claude/settings.json。要为单个项目关闭它，在该项目的设置中设置 autoMemoryEnabled：

{
  "autoMemoryEnabled": false
}

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

存储位置

每个项目在 ~/.claude/projects/<project>/memory/ 获得自己的记忆目录。<project> 路径来自 git 存储库，因此同一存储库中的所有 worktrees 和子目录共享一个自动记忆目录。在 git 存储库外，改用项目根目录。

如果你在 CLAUDE_CONFIG_DIR 旁边设置 CLAUDE_CODE_PROJECT_DIR_NAME，Claude Code 会使用该名称作为 <config dir>/projects/ 下的 <project> 目录，无论你在哪个存储库中启动它，因此使用该配置目录启动的项目共享一个自动记忆目录。需要 Claude Code v2.1.234 或更高版本。

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

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

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

当在项目的 .claude/settings.json 或 .claude/settings.local.json 中设置时，Claude Code 在与设置文件中的 hooks 相同的工作区信任规则下遵守它。当 permissions.blockReadsOutsideWorkingDirectories 开启时，Claude Code 不从存储库提供的设置文件选择的目录加载自动记忆，也不向其保存任何内容，无论该目录位于何处。

目录包含一个 MEMORY.md 索引和每个记忆一个主题文件：

~/.claude/projects/<project>/memory/
├── MEMORY.md           # 索引，每个记忆一行，加载到每个会话
├── user_role.md        # 一个记忆
├── feedback_testing.md # 一个记忆
└── ...                 # Claude 创建的任何其他主题文件

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

自动记忆是机器本地的。同一 git 存储库中的所有 worktrees 和子目录共享一个自动记忆目录。文件不在机器或云环境之间共享。

Claude Code 在 cleanupPeriodDays 保留期后删除旧会话记录，但从该保留清理中排除记忆目录中的记忆文件。MEMORY.md 和主题文件保留到你或 Claude 编辑或删除它们。

它如何工作

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

Claude 写入 MEMORY.md 后，Claude Code 根据 200 行和 25KB 读取限制测量文件。如果文件接近限制，Claude Code 提醒 Claude 缩短它：每个条目保留一行，将详细信息移到主题文件，并合并或删除陈旧条目。如果文件超过限制，写入仍然成功，但 Claude Code 返回一个错误告诉 Claude 重写索引，因为下次加载时超过限制的所有内容都会被丢弃。

此限制仅适用于 MEMORY.md。Claude Code 完整加载最多 4 MiB 的 CLAUDE.md 文件，并跳过更大的文件。较短的文件产生更好的遵守度。

Claude Code 在启动时不加载主题文件，例如 user_role.md 或 feedback_testing.md。Claude 在需要信息时使用其标准文件工具按需读取它们。

主对话的自动记忆不加载到子代理中；例外是分叉，它继承父对话和系统提示。子代理自己的自动记忆（通过子代理 memory 字段启用）是一个单独的目录。

Claude 在你的会话中读取和写入记忆文件。当你在 Claude Code 界面中看到"Saved 2 memories"或"Recalled 2 memories"之类的消息时，Claude 正在主动更新或读取 ~/.claude/projects/<project>/memory/。

当 Claude 写入以 YAML frontmatter 开头的记忆文件时，Claude Code 在 modified frontmatter 字段中记录写入时间为 ISO 8601 时间戳。时间戳显示事实有多新，对你和 Claude 读取记忆时都有用。任何有 frontmatter 的文件在 Claude 下次写入时都会获得该字段，包括在早期版本上创建的文件；Claude Code 永远不会向没有 frontmatter 的文件添加 frontmatter。modified 字段需要 Claude Code v2.1.214 或更高版本。

审计和编辑你的记忆

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

使用 `/memory` 查看和编辑

/memory 命令列出你的 CLAUDE.md、CLAUDE.local.md 和其他内存文件在用户和项目范围内的位置，包括尚不存在的文件的用户和项目 CLAUDE.md 条目。它还让你切换自动记忆开或关，并提供打开自动记忆文件夹的选项。选择任何文件在你的编辑器中打开它；选择一个尚不存在的文件会先创建它。要检查哪些 CLAUDE.md 和规则文件加载到当前会话中，请运行 /context。

VS Code 等 GUI 编辑器在单独的窗口中打开文件，你可以在文件打开时继续使用会话。在 v2.1.216 之前，/memory 会等待你关闭文件后才响应。Vim 等终端编辑器会接管终端，直到你退出。

当你要求 Claude 记住某些内容时，如"总是使用 pnpm，而不是 npm"或"记住 API 测试需要本地 Redis 实例"，Claude 将其保存到自动记忆。要改为添加指令到 CLAUDE.md，直接要求 Claude，如"将其添加到 CLAUDE.md"，或通过 /memory 自己编辑文件。

故障排除记忆问题

这些是 CLAUDE.md 和自动记忆最常见的问题，以及调试步骤。

Claude 不遵循我的 CLAUDE.md

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

要调试：

• 运行 /context 并检查 Memory files 下的列表，以验证你的 CLAUDE.md 和 CLAUDE.local.md 文件已加载。如果 CLAUDE.md 文件未列出，Claude 看不到它。使用 /memory 打开和编辑文件。
• 检查相关 CLAUDE.md 是否在为你的会话加载的位置（参见 选择 CLAUDE.md 文件的位置）。
• 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。
• 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。

如果指令是必须在特定点运行的内容，例如在每次提交之前或每次文件编辑之后，请将其写成 hook 代替。Hooks 在固定的生命周期事件处作为 shell 命令执行，并且无论 Claude 决定做什么都适用。

对于你想要在系统提示级别的指令，使用 --append-system-prompt。你在启动时传递它，因此它更适合脚本和自动化而不是交互式使用。有关它在恢复对话时的行为，请参见 System prompt flags in resumed conversations。

我的 AGENTS.md 未加载

如果你的存储库有 AGENTS.md 而 Claude 似乎不知道它说什么，通常原因是项目路径上某处有 CLAUDE.md。默认情况下，Claude 仅在你的工作目录或其上方没有 CLAUDE.md 或 CLAUDE.local.md 时读取 AGENTS.md。按顺序检查这些：

1. 在你的工作目录或其上方的任何目录中查找 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md，除了你的 ~/.claude/CLAUDE.md。如果你找到一个，Claude 会读取它而不是 AGENTS.md，除非你将 Project instructions 设置为 claude-md-and-agents-md。
2. 运行 claude --version 并确认 v2.1.277 或更高版本。在 v2.1.281 之前，某些会话，例如 Amazon Bedrock 上的会话或禁用遥测的会话，无法加载 AGENTS.md，因此在这些版本上更新到 v2.1.281 或更高版本。
3. 在你的会话中输入 /config 以打开设置面板，并确认 Project instructions 未设置为 claude-md 或 managed-only。如果你根本看不到该设置，你的会话是 无法加载 AGENTS.md 的会话。

要检查 Claude 是否读取了你的 AGENTS.md，运行 /memory 并在列表中查找其路径。

在 v2.1.280 之前，/memory 和 /context 没有列出 Claude 直接读取的 AGENTS.md。在这些版本上，改为询问 Claude 其项目指令说什么。

如果你想保留你找到的 CLAUDE.md，或你的会话无法加载 AGENTS.md，添加一个 CLAUDE.md 在你的 AGENTS.md 旁边来导入它。

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

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

我的 CLAUDE.md 太大了

超过 200 行的文件消耗更多上下文并可能降低遵守度。Claude Code 跳过超过 4 MiB 的文件。使用 path-scoped rules 仅在 Claude 处理匹配文件时加载指令，或修剪不是每个会话都需要的内容。分割到 @path imports 有助于组织，但不会减少上下文，因为导入的文件在启动时加载。

/doctor 检查为已检入的 CLAUDE.md 提议修剪：它删除 Claude 可以从代码库派生的内容，例如目录布局、依赖项列表和架构概览，并保留与工具默认值不同的陷阱、基本原理和约定。修剪检查需要 Claude Code v2.1.206 或更高版本。

在 `/compact` 后指令似乎丢失了

项目根 CLAUDE.md 在压缩中存活：在 /compact 之后，Claude 从磁盘重新读取它并将其重新注入到会话中。子目录中的嵌套 CLAUDE.md 文件和具有 paths: frontmatter 的规则在 Claude 读取它们适用的文件时重新加载。

如果指令在压缩后消失，它要么仅在对话中给出，要么位于尚未重新加载的嵌套 CLAUDE.md 中，或者是尚未匹配文件的路径范围规则。将仅对话的指令添加到 CLAUDE.md 以使其持久化。有关完整的细分，请参阅 What survives compaction。

有关大小、结构和具体性的指导，请参阅 Write effective instructions。

相关资源

• 调试你的配置：诊断为什么 CLAUDE.md 或设置未生效
• Skills：打包按需加载的可重复工作流
• Settings：使用设置文件配置 Claude Code 行为
• Subagent 记忆：让 subagents 维护自己的自动记忆