Claude Code 大型代码库配置指南:聚焦上下文、减少 token 浪费

本文是对官方文档「Set up Claude Code in a monorepo or large codebase」的中文要点摘要,完整内容以原文为准。原文链接:https://code.claude.com/docs/en/large-codebases

在大型代码库或 monorepo 中,Claude Code 的默认配置可能把大量无关指令和文件读取塞入上下文窗口,导致 token 浪费和性能下降。官方提供了一套可独立叠加的配置手段,本文逐一梳理。

从哪里启动 claude 很重要

启动 claude 的目录决定三件事:文件访问范围、加载哪些 CLAUDE.md、以及哪份 .claude/settings.json 生效。

.claude/settings.json 不会像 CLAUDE.md 那样向上继承——它只从启动目录加载。因此在根目录和各子目录分别维护各自的 settings 文件。

按目录分层管理 CLAUDE.md

推荐两级结构:

• 根 CLAUDE.md:仓库通用规范(编码标准、提交约定、目录布局)
• 子目录 CLAUDE.md:该目录专属的技术栈约定(测试命令、环境变量、目录结构等)

从 packages/api/ 启动时,Claude 加载根 CLAUDE.md 和 packages/api/CLAUDE.md,packages/web/CLAUDE.md 不进入上下文。这些文件应提交到仓库,由各目录负责人维护。

保持文件更新的几点建议:

• 在 PR 中 review CLAUDE.md 修改,与普通文档一同对待
• 大模型版本升级后重新审查——旧版本的限制性指令可能已经不再需要
• 配置 Stop hook,每次对话结束后自动提议更新 CLAUDE.md

用 claudeMdExcludes 过滤无关文件

从仓库根目录启动时,Claude 在读取某目录文件时会按需加载该目录的 CLAUDE.md。对于永远不会涉及的目录(其他团队的包、遗留代码),可在 .claude/settings.local.json 中配置。Claude Code 自动创建该文件时会把它加入 gitignore;但这里是你手动创建的,需要自己把它加进 gitignore:

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

支持 glob 语法,匹配绝对路径;相对风格的 pattern 需以 **/ 开头。Managed policy 的 CLAUDE.md 不受此设置影响。

用 Read deny 规则屏蔽构建产物

.gitignore 中的路径默认不参与内容搜索,但已提交的 vendored 代码和生成文件需手动屏蔽。在 .claude/settings.json 中添加 Read deny 规则:

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

这些规则会拦截 Claude 的内置文件工具以及 cat、head、grep、find 等 Bash 命令对应的路径参数。提交到 .claude/settings.json 可让整个团队共享;在 worktree 场景下还需在仓库根目录的 settings 中放一份副本(见下节)。

用代码智能插件减少文件读取

在大型代码库中,定位符号定义或引用需要大量文件读取。安装 code intelligence 插件后,Claude 可直接通过 language server 跳转定义、查找引用:

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

官方市场支持 TypeScript、Python、Go、Rust 等主流语言。若需全团队统一启用,在 settings.json 的 enabledPlugins 字段中声明。此功能与 claudeMdExcludes 和 Read deny 规则互补:后者挡住无关内容,前者让 Claude 不必逐文件扫描来定位符号。

worktree 稀疏检出

--worktree 标志在新 git worktree 中启动会话以隔离修改,默认检出整个仓库。通过 worktree.sparsePaths 只写入任务所需的目录:

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

symlinkDirectories 将 node_modules 做成指向主检出的符号链接,避免多个 worktree 重复占用磁盘。须注意:.claude 必须显式列入 sparsePaths,否则仓库根目录的 settings、rules 和 skills 不会进入 worktree。

sparsePaths 和 symlinkDirectories 在 worktree 创建前从启动目录读取;创建后工作目录切换为 worktree 根目录,因此 deny 规则等其他 settings 需要放在仓库根目录的 .claude/settings.json 中才能在 worktree 内生效。

跨包/跨仓库访问

从子目录启动时,通过 additionalDirectories(提交到 settings,适合团队共享)或 --add-dir(启动时临时授权)授予其他目录的读写权限:

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

两者的区别:

若需同时加载 CLAUDE.md,需设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。

按目录定义 Skills

Skills 放在目录的 .claude/skills/ 下,按需加载——处理 API 代码时不加载前端 skills,反之亦然。SKILL.md 的 frontmatter 中 description 要简短并以触发关键词开头:技能列表多时 description 会被截断,Claude 依靠这些关键词决定是否加载该技能。

多目录共用的 skills(如 PR 规范、部署清单)放在仓库根目录的 .claude/skills/ 中。如需版本管理或跨仓库共用,打包成 plugin——plugin skills 使用 plugin-name:skill-name 命名空间,不会与目录级 skills 冲突。

可通过 OpenTelemetry logs exporter 配合 OTEL_LOG_TOOL_DETAILS=1 监控哪些 skills 被调用(skill_activated 事件),识别可以合并或废弃的技能。

大规模时:插件化统一治理

当分层 CLAUDE.md 难以治理(内容漂移、文件过时、无人维护)时,可将约定迁移到按需加载的机制:

• Skills:仅在任务相关时加载的参考资料
• Plugins:平台团队统一维护的版本化 skills/hooks/commands 包
• MCP servers:对接已有的代码搜索或 RAG 索引,让 Claude 查询而非直接读文件

配合 SessionStart hook,可在会话开始时打印当前目录对应的插件推荐,Claude 会在第一条回复中转达给用户。

跨包变更的规划建议

• 单次会话给出全部变更范围:将共享类型修改和所有调用方一并交给 Claude,保证决策一致性
• 先生成计划并写入文件:长会话的上下文可能被压缩,保存到 markdown 文件的计划在上下文轮换后仍然有效