MemoryLake
返回全部文章
Tutorial2026 年 11 月 17 日·11 分钟阅读

如何在大型代码库中设置 Claude Code?哪些 CLAUDE.md 文件在何处加载,如何排除其他包的指令,以及何时将约定放入 skills (2026)

你的 monorepo 有一个 API 包、一个 Web 应用、一个共享库,还有一个没人碰的遗留服务。根目录的 CLAUDE.md 已经膨胀到涵盖了所有内容,导致 Claude 在编辑 API 路由时不断应用 Web 团队的组件规则。与此同时,它在每个会话的前几分钟都在读取生成的文件,以寻找某个类型的定义位置。

Anthropic 在 Claude Code 文档中针对这种情况专门提供了一份指南。它用一句话指出了问题所在:随着代码库的增长,“为小型项目调优的默认设置可能会让上下文窗口充斥着与任务无关的指令和文件读取,从而消耗 token 并降低 Claude 的性能。”

本指南涵盖了该文档推荐的内容:启动目录如何决定加载哪些 CLAUDE.md 文件、如何按目录分层指令、如何排除其他包的指令、如何阻止 Claude 读取不需要的代码、skills 如何发挥作用,以及何时应该将约定完全移出 CLAUDE.md。

启动 Claude 的位置决定了加载内容

第一个决定最简单,影响也最大。文档指出:“启动 claude 的位置决定了 Claude 在无需额外权限授予的情况下可以读取和编辑哪些文件,哪些 CLAUDE.md 文件在启动时加载到上下文中,以及应用哪些项目设置。”

它对比了两种选择:

  • 从仓库根目录启动。 Claude 可以访问每个文件。启动时,它仅加载根目录的 CLAUDE.md,子目录文件按需加载。
  • 从子目录启动。 Claude 可以访问该子树,直到你授予更多权限。启动时,它会加载该目录的 CLAUDE.md 以及所有祖先目录的 CLAUDE.md。

文档建议,当任务跨越多个包时从根目录启动,而当工作范围仅限于一个包时从子目录启动。

有一个细节很容易被忽略:“.claude/settings.json 中的项目设置不会像 CLAUDE.md 文件那样从父目录继承。”指令会从父目录级联,但设置不会。

按目录分层 CLAUDE.md 文件

文档描述了为什么单个根文件会失效:它“往往要么膨胀到涵盖每个子系统的约定,在与当前任务无关的指令上浪费上下文,要么变得过于通用而毫无用处。”

其建议分为两个层级:

  • 根目录 CLAUDE.md:用于适用于所有地方的指令,如编码标准和提交约定。
  • 每个包或子系统一个 CLAUDE.md:用于该领域特定技术栈的约定。

文档中的示例展示了效果。当你从 API 包启动 Claude 时,它会加载该包的 CLAUDE.md 和根目录的 CLAUDE.md,“上下文中不会出现来自 packages/web/ 的指令。”

要检查实际加载了哪些文件,请运行 /context all 并查看 Memory files 下的列表。

文档还提供了三种保持这些文件更新的方法:

  • 在拉取请求中审查 CLAUDE.md 的编辑,就像对待任何其他文档一样。
  • 在重大模型发布后重新审视。 针对旧模型限制而制定的指令,在新模型能够处理该情况后可能会变成负担。
  • 添加一个建议更新的 Stop 钩子。 Stop 钩子会接收会话记录的路径,因此脚本可以在记忆犹新时提出 CLAUDE.md 的修改建议。

按需加载的子目录文件有其自身的尺寸行为,这与根文件不同。我们在关于 Claude Code 中子目录 CLAUDE.md 限制 的指南中介绍过这一点。

按目录的 CLAUDE.md 或路径范围规则

Claude Code 有第二种将指令定位到树中特定部分的方法:在 .claude/rules/ 下使用带有 paths: 通配符的规则文件。文档对比了这两者。

按目录的 CLAUDE.md 与其代码一起位于目录内。当你从该目录启动时,它会在启动时加载,或者按需加载。它适合由目录所有者维护自己约定的团队。

路径范围规则 位于仓库根目录的中央 .claude/ 文件夹中。当 Claude 处理匹配其通配符的文件时,它会加载。它适合希望将所有约定放在一个地方的团队,或者适用于许多分散路径的规则。

我们在关于 什么是 Claude Code 规则 的指南中介绍了规则文件的工作原理。

排除其他包的指令

当你从根目录启动时,每个子目录的 CLAUDE.md 可以在 Claude 接触到那里的文件时按需加载。claudeMdExcludes 设置可以通过路径或通配符跳过特定文件,“以便它们永远不会加载”。

文档建议将其用于你从不工作的目录,例如其他团队的包、遗留代码或第三方库子树。一些细节决定了它是否按你预期的方式工作:

  • 它是静态的。 “排除列表是静态的,不是针对每个任务的开关。”如果每天要专注于不同的包,请从该包启动 Claude,而不是编辑排除项。
  • 模式匹配绝对路径。 使用 **/ 开头的相对风格模式来匹配树中的任何位置。
  • 它也涵盖规则。 排除一个包的文件夹会跳过其下的每个 CLAUDE.md 和规则文件,而根目录 CLAUDE.md 和你工作的包则正常加载。
  • 范围合并。 你可以在用户、项目、本地或托管范围进行设置,数组会跨范围合并,因此团队默认值和个人添加项会结合在一起。
  • 托管文件仍然加载。 如果你的组织部署了托管的 CLAUDE.md,匹配它的模式不会跳过它。

对于仅适用于你的排除项,文档建议使用 .claude/settings.local.json。如果你手动创建该文件,请自行将其添加到 gitignore 中。

阻止 Claude 读取不需要的代码

指令只是填充上下文的一部分。文档指出:“文件读取是另一个随着代码库增长而增加的成本。”

Gitignored 路径。 Claude 的内容搜索默认遵循 .gitignore,因此像 node_modules/、dist/ 和 build/ 这样的路径不会出现在搜索结果中。

已提交的生成代码或第三方代码。 对于已提交的路径,在 permissions.deny 中添加 Read 拒绝规则。将它们放在 .claude/settings.json 中供仓库中的每个人使用,放在 .claude/settings.local.json 中供你自己使用,或者放在托管设置中以在所有地方强制执行。

文档明确指出了限制:“拒绝规则不涵盖自行打开文件的子进程。”

语言服务器查询。 代码智能插件将 Claude 连接到语言服务器,因此它可以跳转到定义并查找引用,“而不是扫描树”。文档称这与排除项和拒绝规则配合良好:后者排除无关内容,而代码智能则防止 Claude 通读剩余内容。

仅检出所需内容,并谨慎添加目录

对于工作树(worktrees),worktree.sparsePaths 设置使用 git sparse-checkout 仅写入列出的目录加上根级文件。如果你希望在工作树内使用根目录的设置和规则,请将 .claude 包含在列表中。

当你从一个包启动并需要访问同级包时,你授予访问权限的方式会改变加载的内容。文档中的表格显示:

  • additionalDirectories 设置:永远不会加载 CLAUDE.md、规则或 skills。
  • --add-dir 标志或 /add-dir 命令:加载 skills,并且仅在设置了 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 环境变量时才加载 CLAUDE.md 和规则。

因此,添加同级包会给 Claude 文件访问权限,但不一定包含该包的约定。如果同级包的规则对任务很重要,请配合环境变量使用 --add-dir。

按目录添加 skills

Skills 适用于仅在相关时才加载的参考资料。文档指出,任何子目录都可以在其自身的 .claude/skills/ 下定义 skills,并随该区域的代码一起提交。其示例:API 包中的 API 测试 skill 和 Web 包中的组件模式 skill。当 Claude 处理某个包中的文件时,它会加载该包的 skill。

使用大量 skills 时有一个陷阱。Claude 通过读取每个发现的 skill 的名称和描述来选择 skill,并且“只有选定 skill 的完整内容会加载到上下文中”。当数量很多时,文档称某些 skill 可能会完全丢失其描述。其建议是:“保持描述简短,并以请求可能包含的词汇开头”。

哪些 skills 在范围内取决于你启动的位置:

  • 从子目录启动:该目录的 skills、直到根目录的每个父目录的 skills,以及用户和企业级 skills。
  • 从根目录启动:根目录 skills 加上 Claude 接触到的每个子目录的 skills,“这可能会累积到数百个”。

对于许多目录共享的 skills,例如 PR 约定或部署检查清单,文档建议放在根目录的 .claude/skills/。

当分层不再能扩展时

文档坦言,按目录的文件并不能解决所有问题:“约定会漂移,文件会过时,而且没人负责根目录。”

其建议是将约定和参考内容从始终加载的 CLAUDE.md 移至按需加载的机制中:

  • Skills:用于在相关时加载的参考资料。
  • Plugins:由平台团队拥有并通过托管设置供所有人安装的 skills、钩子和命令的版本化捆绑包。Plugin skills 使用命名空间,因此不会与按目录的 skills 冲突。
  • MCP 服务器:如果你的组织已经在仓库上运行代码搜索或检索索引。

- 一旦约定存在于插件中,处于不熟悉代码区域的同事可能不知道该应用哪一个。文档建议使用 SessionStart 钩子,将启动目录映射到正确的插件并打印建议,因为 Claude Code 会在第一个提示符之前将钩子的输出添加到 Claude 的上下文中。

跨包的更改

对于涉及多个包的更改(例如共享类型及其每个调用点),文档给出了两种技术。在一个会话中将整个更改交给 Claude,这样每次编辑背后的决策就能保持一致。并且先制定计划:在计划模式下,Claude 将计划写入文件,“Claude Code 在每次压缩后重新注入计划文件,因此计划在对话历史可能丢失的情况下仍能保留”。

人们首先尝试的做法

将所有内容放入根目录 CLAUDE.md。 这会在无关指令上浪费上下文。

按任务编辑 claudeMdExcludes。 它是静态的。应该改为从特定包启动。

期望拒绝规则阻止所有读取。 自行打开文件的子进程不受涵盖。

使用 additionalDirectories 添加同级包并期望加载其 CLAUDE.md。 该设置永远不会加载 CLAUDE.md 或 skills。

编写冗长的 skill 描述。 当 skills 很多时,描述可能会被截断。

解决方案:为你所在的代码加载正确的指令

第 1 步:选择启动位置

对于专注的工作从包目录启动,对于跨包任务从根目录启动。

第 2 步:按目录拆分 CLAUDE.md

在根目录保留全仓库规则,在每个包中保留特定技术栈的约定,然后使用 /context all 进行检查。

第 3 步:排除和拒绝你永远不需要的内容

使用 claudeMdExcludes 排除其他团队的指令,并使用 Read 拒绝规则处理生成代码或第三方代码。

第 4 步:记录每个约定存在的原因

指令文件说明该做什么。背后的决策以及哪些约定正在被废弃,需要它们自己的归宿。

在 MemoryLake 中设置

在大型代码库中,约定分散在许多文件和所有者中。它们背后的决策,例如为什么 API 使用查询构建器,或者为什么某个遗留服务被冻结,是新同事和新会话不断询问的内容。

MemoryLake 是此类项目上下文(如架构决策、包所有权和约定背后的原因)的记忆层,统一保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。

你用自己的语言亲自编写条目。不会从你的 CLAUDE.md 文件、规则或 skills、设置文件、会话或任何供应商的存储中读取、写入或删除任何内容。CLAUDE.md 的加载、排除和 skills 仍按 Anthropic 描述的方式工作。

第 1 步:创建 API 密钥

登录并从控制面板生成密钥。像对待任何其他凭据一样,将其存储在仓库之外。

MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供代理使用
MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供代理使用

第 2 步:上传你的第一批记忆

从你在解决方案第 4 步中编写的内容开始:约定背后的决策,按包分组。每个条目一个决策,并注明其所有者。

MemoryLake 工作区显示已上传的首批文档,列出每个文件变为可搜索记忆的过程
MemoryLake 工作区显示已上传的首批文档,列出每个文件变为可搜索记忆的过程

第 3 步:连接你的 AI 和代理

连接 Claude Code、Codex 和你使用的其他助手。无论会话从哪个包开始,每个助手都可以利用相同的决策。

MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和代理框架
MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和代理框架

这在实践中改变了什么

第一个区别是指令文件变小了。CLAUDE.md 可以专注于“该做什么”,而推理过程则保存在别处。

第二个区别是更容易上手。新同事可以阅读为什么某个包以这种方式工作。

第三个区别是跨工具的一致性。在同一个仓库中工作的 Codex 可以使用相同的决策。

大型代码库中 Claude Code 的最佳实践

在工作所在处启动。 这决定了加载哪些 CLAUDE.md 文件。

按目录分层指令。 根目录用于全局,包目录用于其自身的技术栈。

检查加载内容。 使用 /context all。

排除你从不碰的内容。 claudeMdExcludes 是静态的,因此设置一次即可。

拒绝读取生成代码。 并记住子进程不受涵盖。

保持 skill 描述简短。 以请求可能包含的词汇开头。

将不断增长的约定移至 skills 或插件。 按需加载它们。

结论

Claude Code 根据你启动它的位置加载 CLAUDE.md 文件:从根目录启动仅加载根文件,或者从子目录启动加载该包的文件及其所有祖先文件,其他文件按需加载。Anthropic 的大型代码库指南建议按目录分层指令,使用 claudeMdExcludes 排除你从不工作的文件,阻止读取生成代码,并将 skills 的范围限制在它们服务的包中。

当按目录的文件不再能扩展时,指南建议将约定移入按需加载的 skills、插件或 MCP 服务器中。将这些约定背后的决策保存在你维护的地方,这样它们就不会随文件一起漂移。

常见问题

Claude Code 如何处理 monorepo?

它根据你启动它的位置加载 CLAUDE.md 文件。从包目录启动时,它加载该包的文件及其所有祖先文件。从根目录启动时,它加载根文件,其他文件按需加载。

我应该使用一个 CLAUDE.md 还是多个?

Anthropic 建议使用一个根文件处理全仓库规则,每个包或子系统使用一个文件处理特定技术栈的约定。

如何阻止 Claude 加载另一个团队的 CLAUDE.md?

添加一个 claudeMdExcludes 模式,例如在为你自己准备的 .claude/settings.local.json 中添加。

claudeMdExcludes 会跳过托管的 CLAUDE.md 文件吗?

不会。匹配托管 CLAUDE.md 的模式不会跳过它。

为什么 Claude 不遵循同级包的规则?

因为 additionalDirectories 设置永远不会加载 CLAUDE.md 或 skills。请配合环境变量使用 --add-dir 来加载它们。

如何检查加载了哪些 CLAUDE.md 文件?

运行 /context all 并检查 Memory files 下的列表。

何时应该将约定移入 skills?

当按目录的文件变得难以管理时。Skills 仅在相关时加载。