在 monorepo 或大型代码库中设置 Claude Code

下面的每个设置都是独立的。它们相互叠加而不是相互替换，因此应用适合你的存储库的任何设置

• 选择从哪里启动 Claude ： 决定了设置文件的位置，所以先阅读它
• 将其整合在一起 ：展示了所有这些设置的组合

有关在任何存储库中保持上下文较小的工作流技术，例如在子代理中运行探索以使文件读取不会进入主对话

请参阅 Claude Code 的最佳实践 https://code.claude.com/docs/zh-CN/best-practices

要向组织中的每个开发者推出基线配置，请参阅为你的组织设置 Claude Code

https://code.claude.com/docs/zh-CN/admin-setup

本页面的示例引用了一个包含三个包的 monorepo。相同的模式适用于大型单树代码库

monorepo/
  CLAUDE.md                     # 根指令
  packages/
    api/
      CLAUDE.md                 # API 特定指令
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # 前端特定指令
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # 共享库指令
      src/

示例使用 packages/api/，替换为自己的子系统目录，例如 src/backend/ 或 lib/core/

按目录的 CLAUDE.md 文件和 .claude/rules/ 下的 路径范围规则 都允许将指令定向到树的一部分。它们在文件位置和加载时间上有所不同

有关也涵盖 skills 的比较，请参阅比较相似功能

https://code.claude.com/docs/zh-CN/features-overview#compare-similar-features

当从存储库根目录启动 Claude 时，每个子目录的 CLAUDE.md 在 Claude 读取该目录中的文件时立即加载

claudeMdExcludes 设置按路径或 glob 模式跳过特定文件，以便它们永远不会加载

对从不处理的目录使用此功能，例如其他团队的包、遗留代码或供应商子树

排除列表是静态的，不是按任务的开关

。要今天专注于一个包，明天专注于另一个包，从该包的目录启动 Claude 而不是编辑排除

如果只想为自己排除这些，将设置放在 .claude/settings.local.json 中

• Claude Code 在创建它时会 gitignore 该文件；由于在这里手动创建它，请将其添加到 gitignore
• 模式使用 glob 语法与绝对文件路径匹配，所以以相对样式模式开头的 **/ 以在树中的任何地方匹配

下面的示例排除其他团队拥有的包：

{
    "claudeMdExcludes": [
        "**/packages/admin-dashboard/**",
        "**/packages/legacy-*/**"
    ]
}

这跳过这些包下的每个 CLAUDE.md 和规则文件

根 CLAUDE.md 和你处理的包仍然正常加载

这些模式涵盖其他常见情况：

• "**/packages/*/CLAUDE.md"：排除每个包的 CLAUDE.md，同时保留根目录
• "packages/web"：排除 web 包下的所有内容，包括规则
• "/home/user/monorepo/legacy/CLAUDE.md"：按绝对路径排除一个特定文件

托管策略 CLAUDE.md 文件无法排除，因此组织范围的指令始终适用

可以在任何设置范围设置 claudeMdExcludes：用户、项目、本地或托管

数组在范围内合并，所以团队可以设置项目级别的默认值，同时个人添加本地覆盖

有关完整的排除文档，请参阅排除特定 CLAUDE.md 文件

1. Claude 的内容搜索默认尊重 .gitignore，所以已列在其中的路径，例如 node_modules/、dist/ 和 build/，无需额外配置就会保持在搜索结果之外
2. 对于已检入的路径，例如供应商 SDK 或提交的生成代码，在 permissions.deny 中 添加 Read 拒绝规则 以阻止 Claude 打开这些文件，即使搜索列出了它们
3. 要为在存储库中工作的每个人应用这些排除，将它们提交到 .claude/settings.json
4. 要保持个人，改用 .claude/settings.local.json
5. 与本页面的其他项目设置一样，这些文件仅从启动目录加载
   • 如果从那里启动 Claude，将它们放在存储库根目录

   • 如果从子目录启动，放在每个包的 .claude/ 中

     要在任何启动目录的每个会话中强制执行相同的拒绝规则，在托管设置中设置它们，用户和项目设置无法覆盖
     

下面的示例阻止构建工件和供应商 SDK：

{
    "permissions": {
        "deny": [
            "Read(./**/dist/**)",
            "Read(./**/build/**)",
            "Read(./**/*.generated.*)",
            "Read(./vendor/**)"
        ]
    }
}

拒绝规则涵盖 Claude 的内置文件工具和识别的 Bash 文件命令，包括 cat、head、grep 和 find，当拒绝的路径作为参数传递时

它们不会从递归搜索的输出中过滤拒绝的路径，也不涵盖自己打开文件的任意子进程

有关完整的模式语法，请参阅Read 和 Edit 权限规则

https://code.claude.com/docs/zh-CN/permissions#read-and-edit

在大型代码库中，查找符号的定义或使用位置可能需要许多文件读取和 grep 调用。代码智能插件将 Claude 连接到语言服务器，以便它可以跳转到定义、查找引用和直接显示类型错误，而不是扫描树

官方市场有 TypeScript、Python、Go、Rust 和其他常见语言的插件。下面的示例安装 TypeScript 插件：

/plugin install typescript-lsp@claude-plugins-official

要为存储库中的每个人启用插件而不是自己安装，将其添加到 enabledPlugins 项目设置

https://code.claude.com/docs/zh-CN/settings#plugin-settings

代码智能插件需要每个开发者机器上的语言的语言服务器二进制文件。查看每种语言需要哪个二进制文件

从官方市场安装需要网络访问 GitHub，市场在那里托管

在受限网络上，从内部 Git 主机或本地路径添加市场

这与上面的 claudeMdExcludes 和 Read 拒绝规则配对良好。那些保持不相关的内容不进入上下文，代码智能保持 Claude 不读取剩余的内容来定位定义

–worktree 标志在新的 git worktree 中启动会话，以便更改与主检出隔离。默认情况下，它检出整个存储库。在大型存储库中， worktree.sparsePaths 设置使用 git sparse-checkout 仅将列出的目录加上根级文件写入磁盘，以便 worktrees 启动更快并使用更少空间

• 如果在此目录中工作的每个人都需要相同的路径，将设置提交到 .claude/settings.json
• 要为自己添加路径，使用 .claude/settings.local.json：列表在范围内合并，所以本地文件可以向提交的列表添加路径但不能删除它们

下面的示例显示提交的文件：

{
    "worktree": {
        "sparsePaths": [
            ".claude",
            "packages/api",
            "packages/shared"
        ]
    }
}

当 Claude 创建 worktree 时，它仅检出 .claude/、packages/api/ 和 packages/shared/ 而不是完整树

sparsePaths 中的路径相对于存储库根目录，无论从哪个子目录启动 Claude

任何目录路径都可以在这里工作，不仅仅是根目录

这对于 子代理 worktree 隔离特别有用。子代理是为子任务生成的并行 Claude 实例，每个在 worktree 中运行的都获得轻量级检出而不是完整树

会话中的所有 worktrees 共享相同的 sparsePaths

所以如果一个子代理需要 packages/api/ 而另一个需要 packages/web/，在配置文件里把两者都加入

在 sparsePaths 中列出目录，而不是单个文件

• 根级文件如 package.json、tsconfig.base.json 和锁文件始终与列出的目录一起检出
• 根级目录不是，所以如果想要存储库根目录的 .claude/settings.json、.claude/rules/ 或 .claude/skills/ 在 worktree 内可用，请在列表中包含 .claude

Sparse checkout 需要 git 在存在 sparse worktree 时在存储库的共享 .git/config 中启用 extensions.worktreeConfig 。Claude Code 在删除最后一个 worktree 后会删除该条目，但仅当 Claude Code 添加了它时。它永远不会删除用户设置的值

在 v2.1.207 之前，该条目在删除最后一个 worktree 后仍然存在

基于 go-git 的工具（如 tea）无法打开存储库，直到运行 git config --unset extensions.worktreeConfig

要避免在 worktrees 中复制大型目录如 node_modules，将 sparsePaths 与同一 .claude/settings.json 中的 symlinkDirectories 配对：

{
    "worktree": {
        "sparsePaths": [
            ".claude",
            "packages/api",
            "packages/shared"
        ],
        "symlinkDirectories": [
            "node_modules"
        ]
    }
}

这创建了一个从每个 worktree 的 node_modules/ 回到主存储库副本的符号链接，而不是在磁盘上复制它

sparsePaths 和 symlinkDirectories 设置在创建 worktree 之前从启动目录读取

创建后，会话的工作目录是 worktree 根，而不是启动的子目录

因此，worktree 内的项目设置从 worktree 根的 .claude/settings.json（存储库根文件的检出副本）加载

将在 worktrees 内需要的任何其他设置（例如权限规则或 hooks）放在存储库根的 .claude/settings.json 中

有关完整的 worktree 设置参考，请参阅 Worktree 设置

当从子目录启动 Claude 时，或当任务跨越多个检出时，本部分适用

如果在单个大型树中从存储库根目录启动，Claude 已经可以访问每个文件，可以跳过此部分

当从 packages/api/ 启动 Claude 时，它可以读取和写入该目录内的文件。如果任务需要跨包更改，例如更新 api 和 web 都导入的共享类型，需要授予对同级目录的访问权限

相同的机制授予对单独检出的存储库的访问权限

.claude/settings.json 中的 additionalDirectories 设置给 Claude 访问工作目录。下面的示例授予对两个同级包的访问权限：

{
    "permissions": {
        "additionalDirectories": [
            "../shared",
            "../web"
        ]
    }
}

相对路径相对于启动 Claude 的目录解析

使用此配置，Claude 可以在从 packages/api/ 工作时读取和编辑 packages/shared/ 和 packages/web/ 中的文件

也可以在运行时不编辑设置而授予访问权限，通过在启动 Claude 时传递 –add-dir ：

claude --add-dir ../shared

无论如何添加目录，Claude 都可以读取和编辑其中的文件。目录的 CLAUDE.md、.claude/rules/ 文件和 skills 是否也加载取决于如何添加它：

要从使用 –add-dir 或 /add-dir 添加的目录加载 CLAUDE.md 和规则文件，设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 环境变量：

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

环境变量对 additionalDirectories 设置中列出的目录没有影响

详见从其他目录加载 https://code.claude.com/docs/zh-CN/memory#load-from-additional-directories

• 对于此区域中的每个人都需要的同级目录，将 additionalDirectories 提交到 .claude/settings.json
• 对于个人选择或一次性访问，使用 .claude/settings.local.json 或在启动时传递 –add-dir

随着 skills 分散在许多目录中，Claude 选择的列表可能会增长很大

Claude 通过读取每个发现的 skill 的名称和描述来选择 skill，只有选定的 skill 的完整内容加载到上下文中

本部分涵盖如何保持该列表较小以及编写在缩短时幸存的描述

哪些 skills 在范围内取决于你从哪里启动 Claude：

• 从子目录如 packages/api/：来自该目录、每个父目录直到存储库根目录以及用户和企业级别的 skills
• 从存储库根目录：来自 Claude 在会话期间接触的每个子目录的 skills，可能累积到数百个
• 在使用 –add-dir 添加同级后：该同级的 skills 也加载
  • additionalDirectories 设置仅授予文件访问权限，不加载 skills

名称始终加载，但当有许多时描述被缩短，这可能会剥离 Claude 用来决定 skill 是否适用的关键字

保持描述简短并以请求会包含的词开头，例如”在 packages/api/ 中编写或修改测试”

对于许多目录共享的 skills，例如 PR 约定或部署检查清单，将它们放在存储库根目录的 .claude/skills/ 中，以便从任何启动目录加载

当共享 skills 需要自己的版本历史或必须跨存储库工作时，改为将它们打包为插件

插件 skills 使用 plugin-name:skill-name 命名空间，所以它们永远不会与按目录的 skills 冲突

平台团队可以在一个地方对它们进行版本化和更新

要查找哪些 skills 未被使用，启用 OpenTelemetry 日志导出器并设置 OTEL_LOG_TOOL_DETAILS=1 以便 skill 名称被逐字记录而不是被编辑

• skill_activated 事件在其 skill.name 属性中记录每个调用
• invocation_trigger 记录命令、Claude 或嵌套 skill 是否调用它，这告诉你要合并或停用什么

一旦约定位于插件中，启动 Claude 的队友就没有关于该区域所有者维护哪个插件的信息

SessionStart hook 可以弥补这个差距，因为 hook 打印到 stdout 的任何内容都会在第一个提示之前添加到 Claude 的上下文中

例如，可以编写一个脚本，从hook 输入读取启动目录

在提交到存储库的路径到插件映射中查找它，并打印建议供 Claude 在其第一个回复中中继