文档索引

获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面后再继续探索。

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 在每次会话开始时读取它们。

何时添加到 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 处理匹配文件时加载。你也可以将内容拆分为导入来组织，尽管导入的文件仍在启动时加载并进入上下文窗口。

结构：使用 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 一起。

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

要引入 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 worktree 中工作，gitignore 的 CLAUDE.local.md 只存在于你创建它的 worktree 中。要在 worktree 之间共享个人指令，改为从你的主目录导入文件：

# 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 和 .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 文件加载指令。

所有发现的文件被连接到上下文中，而不是相互覆盖。跨目录树，内容从文件系统根目录到你的工作目录排序。对于 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 文件和规则的完整布局，请参阅 Monorepo 和大型仓库。

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           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

没有 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 读取匹配模式的文件时触发，而不是在每次工具使用时。

在 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    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

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

为大型团队管理 CLAUDE.md

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

部署组织范围的 CLAUDE.md

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

1. 在托管策略位置创建文件

   • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
   • Linux 和 WSL: /etc/claude-code/CLAUDE.md
   • Windows: C:\Program Files\ClaudeCode\CLAUDE.md

2. 使用配置管理系统部署

   使用 MDM、组策略、Ansible 或类似工具在开发者机器上分发文件。详见托管设置了解其他组织范围的配置选项。

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 和托管设置服务于不同目的。使用设置进行技术强制执行，使用 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 仓库派生，因此同一仓库中的所有 worktree 和子目录共享一个自动记忆目录。在 git 仓库之外，改用项目根目录。

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

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

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

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

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Concise index, loaded into every session
├── debugging.md       # Detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...                # Any other topic files Claude creates

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

当你要求 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 行为
• 子代理记忆：让子代理维护自己的自动记忆