存储指令和记忆

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

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

将其保持为 Claude 应该在每个会话中保持的事实：构建命令、约定、项目布局、“总是做 X”规则

如果一个条目是多步骤过程或仅对代码库的一部分重要，将其移到 skill 或 路径范围规则 中

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

• 工作目录上方目录层次结构中的 CLAUDE.md 和 CLAUDE.local.md 文件在启动时完整加载

• 子目录中的文件在 Claude 读取这些目录中的文件时按需加载

  有关完整的解析顺序，请参阅 CLAUDE.md 文件如何加载
  
  https://code.claude.com/docs/zh-CN/memory#how-claude-md-files-load
  

对于大型项目，可以使用 项目规则 将指令分解为特定主题的文件

规则让你将指令范围限定到特定文件类型或子目录

https://code.claude.com/docs/zh-CN/memory#organize-rules-with-claude/rules/

项目 CLAUDE.md 可以存储在 ./CLAUDE.md 或 ./.claude/CLAUDE.md 中

• 运行 /init 自动生成起始 CLAUDE.md。Claude 分析你的代码库并创建一个包含构建命令、测试指令和它发现的项目约定的文件
  • 如果 CLAUDE.md 已存在，/init 会建议改进而不是覆盖它
  • 从那里进行细化，添加 Claude 不会自己发现的指令
• 设置 CLAUDE_CODE_NEW_INIT=1 以启用交互式多阶段流程
  • /init 询问要设置哪些工件：CLAUDE.md 文件、skills 和 hooks
  • 使用 subagent 探索你的代码库，通过后续问题填补空白，并在写入任何文件之前呈现可审查的提案

注意：创建此文件并添加适用于在项目上工作的任何人的指令：构建和测试命令、编码标准、架构决策、命名约定和常见工作流

这些指令通过版本控制与你的团队共享，因此请关注项目级标准而不是个人偏好

CLAUDE.md 文件在每个会话开始时加载到上下文窗口中，与对话一起消耗令牌。上下文窗口可视化显示 CLAUDE.md 相对于其余启动上下文的加载位置

因为它们是上下文而不是强制配置，编写指令的方式会影响 Claude 遵循它们的可靠性

具体、简洁、结构良好的指令效果最好

• 大小：每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度

  如果你的指令变得很大，使用 路径范围规则 以便指令仅在 Claude 处理匹配文件时加载
  
  也可以将内容分割成 导入 以便组织，尽管导入的文件仍然加载并在启动时进入上下文窗口
  

• 结构：使用 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 中的任何地方使用 @ 语法引用它们：

  有关项目概述，请参阅 @README，有关此项目的可用 npm 命令，请参阅 @package.json
  

  # 其他指令
  - git 工作流 @docs/git-instructions.md
  

• 对于不想签入版本控制的私人项目偏好，在项目根目录创建 CLAUDE.local.md
  • 它与 CLAUDE.md 一起加载并以相同方式处理
  • 将 CLAUDE.local.md 添加到你的 .gitignore 以便它不被提交
    • 运行 /init 并选择个人选项会为你做这个

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

  # 个人偏好
  - @~/.claude/my-project-instructions.md
  

  Claude Code 第一次在项目中遇到外部导入时，它会显示一个批准对话框，列出这些文件
  
  如果你拒绝，导入保持禁用状态，对话框不会再出现
  

有关组织指令的更结构化方法，请参阅 .claude/rules/

Claude Code 读取 CLAUDE.md，而不是 AGENTS.md

• 如果你的存储库已经为其他编码代理使用 AGENTS.md，创建一个导入它的 CLAUDE.md，这样两个工具都可以读取相同的指令而无需重复

• 也可以在导入下方添加 Claude 特定的指令。Claude 在会话开始时加载导入的文件，然后附加其余部分：

  @AGENTS.md
  
  ## Claude Code
  
  对 `src/billing/` 下的更改使用 Plan Mode。
  

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

ln -s AGENTS.md CLAUDE.md

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

在已经有 AGENTS.md 的存储库中运行 /init 会读取它并将相关部分合并到生成的 CLAUDE.md 中

它也读取其他工具配置，如 .cursorrules、.devin/rules/ 和 .windsurfrules

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 文件和规则的完整布局，请参阅 Monorepos 和大型存储库

https://code.claude.com/docs/zh-CN/large-codebases

块级 HTML 注释（<!– maintainer notes –>）在 CLAUDE.md 文件中在内容注入到 Claude 的上下文之前被剥离

使用它们为人类维护者留下笔记，而不在它们上花费上下文令牌

代码块内的注释被保留。当直接用 Read 工具打开 CLAUDE.md 文件时，注释保持可见

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

规则在每个会话或打开匹配文件时加载到上下文中

对于不需要始终在上下文中的特定任务指令，改用 skills，它仅在你调用它们或 Claude 确定它们与你的提示相关时加载

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

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

{
    "autoMemoryEnabled": false
}

要通过环境变量禁用自动记忆，设置:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

每个项目在 ~/.claude/projects/<project>/memory/ 获得自己的记忆目录

• <project> 路径来自 git 存储库，因此同一存储库中的所有 worktrees 和子目录共享一个自动记忆目录

  在 git 存储库外，改用项目根目录
  

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

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

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

当在项目的 .claude/settings.json 或 .claude/settings.local.json 中设置时，该值仅在接受该文件夹的工作区信任对话后才被采用

这与管理 hooks 的门相同

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

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

MEMORY.md 充当记忆目录的索引

Claude 在会话中读取和写入此目录中的文件，使用 MEMORY.md 跟踪存储的内容

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

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 从会话中浏览和打开记忆文件

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

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

如果指令是必须在特定点运行的内容，例如在每次提交之前或每次文件编辑之后，请将其写成 hook 代替

Hooks 在固定的生命周期事件处作为 shell 命令执行，并且无论 Claude 决定做什么都适用

对于想要在系统提示级别的指令，使用 –append-system-prompt

• 这必须在每次调用时传递，因此它更适合脚本和自动化而不是交互式使用

使用 InstructionsLoaded hook 记录确切加载了哪些指令文件、何时加载以及为什么

这对于调试特定路径规则或子目录中的延迟加载文件很有用

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

超过 200 行的文件消耗更多上下文并可能降低遵守度。使用 路径范围规则 仅在 Claude 处理匹配文件时加载指令，或修剪不是每个会话都需要的内容

分割到 @path 导入 有助于组织，但不会减少上下文，因为导入的文件在启动时加载

项目根 CLAUDE.md 在压缩中存活：在 /compact 之后

• Claude 从磁盘重新读取它并将其重新注入到会话中
• 子目录中的嵌套 CLAUDE.md 文件不会自动重新注入；它们在 Claude 下次读取该子目录中的文件时重新加载。

如果指令在压缩后消失，它要么仅在对话中给出，要么位于尚未重新加载的嵌套 CLAUDE.md 中

将仅对话的指令添加到 CLAUDE.md 以使其持久化

有关完整的细分，请参阅 什么在压缩中存活

https://code.claude.com/docs/zh-CN/context-window#what-survives-compaction