大型代码库与 Monorepo

大型代码库的问题通常不是 Claude Code 能不能读文件,而是它读了太多和当前任务无关的文件。启动目录、CLAUDE.md 分层、读取权限、Worktree 范围和技能作用域,都会直接影响上下文大小、成本和质量。

#启动位置决定边界

从仓库根目录启动适合跨多个包的任务。从子目录启动适合只改一个服务、一个前端包或一个模块的任务。

项目级 .claude/settings.json 只从启动目录读取,不会像 CLAUDE.md 一样自动继承父目录配置。如果团队常从多个子目录启动 Claude Code,每个子目录需要自己的 settings,或者用托管配置统一下发。

#分层 CLAUDE.md

大型仓库不要把所有规则都塞进根 CLAUDE.md。推荐拆成两层:

• 根 CLAUDE.md: 仓库结构、通用编码规范、提交约定、常用命令入口。
• 子目录 CLAUDE.md: 该包的技术栈、测试命令、数据库约束、组件规范。

示例:

monorepo/
  CLAUDE.md
  packages/
    api/
      CLAUDE.md
      src/
    web/
      CLAUDE.md
      src/
    shared/
      CLAUDE.md
      src/

当你从 packages/api 启动,Claude Code 会看到根规则和 API 包规则,不会把 Web 包规则放进启动上下文。和 记忆与规则 配合时,可以把“永久通用规则”留在根文件,把“路径相关规则”放在子目录或 .claude/rules。

#排除无关说明

如果你必须从仓库根目录启动,但某些包永远和当前工作无关,用 claudeMdExcludes 排除它们的说明文件。

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

这适合个人机器上的 .claude/settings.local.json。团队共享默认值可以放在 .claude/settings.json。托管策略里的 CLAUDE.md 不能被用户排除。

#限制文件读取

.gitignore 会让常规搜索避开 node_modules、dist、build 这类目录。对于已经提交到仓库里的生成代码、供应商 SDK 或历史包,建议加 Read deny。

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

这些规则会阻止 Claude Code 的读取工具打开对应路径,也会约束常见的 cat、head、grep、find 命令。它不会从递归搜索结果里隐藏路径名,但能阻止继续读取内容。更多权限写法见 权限与模式。

#用代码智能减少扫描

在大仓库里查定义、调用方和类型错误时,纯 rg 扫描可能很贵。官方代码智能插件会连接语言服务器,让 Claude Code 直接跳转定义、查引用和读取诊断。

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

语言服务器需要每个开发者本机有对应二进制。受限网络下,可以把插件市场放在内部 Git 或本地路径。插件和 Skills 的分发方式见 插件与 Skills。

#稀疏 Worktree

--worktree 会创建隔离工作区,适合并行任务和回退。大型仓库默认复制整棵树会慢,可以用 worktree.sparsePaths 只检出相关目录。

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

注意点:

• sparsePaths 写目录,不要写单个文件。
• 根级文件会随目录一起检出,根级目录不会自动检出。
• 如果 Worktree 里还需要根 .claude 配置、rules 或 skills,把 .claude 放进列表。
• symlinkDirectories 可以避免每个 Worktree 重复复制 node_modules。

并行 Worktree 的策略见 Worktrees 并行工作区 和 多代理、后台与 Workflows。

#跨包访问

从子目录启动时,Claude Code 默认只能读写该子树。跨包任务可以用 additionalDirectories 或启动参数授权。

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

也可以一次性传参:

claude --add-dir ../shared

如果希望 --add-dir 加载额外目录的 CLAUDE.md,启动时设置:

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

#目录级 Skills

每个子目录都可以有自己的 .claude/skills。Skill 的名称和 description 会参与匹配,正文只在命中时加载,所以适合承载不会每次都用到的长流程。

packages/api/
  .claude/
    skills/
      api-testing/
        SKILL.md

SKILL.md 示例:

---
name: api-testing
description: Testing patterns for packages/api. Use when writing or modifying API tests.
---

## Running tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`

## Patterns

- Use supertest for HTTP assertions.
- Wrap database tests in transactions that roll back.

共享流程可以放在仓库根 .claude/skills。跨仓库或平台团队维护的流程更适合打包成插件。

#跨包任务流程

大型改动不仅要配置得对,还要把任务切得对:

• 先让 Claude Code 探索并写一份计划文件,例如 docs/changes/user-role-plan.md。
• 把共享类型和调用方放在同一个会话里处理,避免每个包重新推导上下文。
• 用子代理做只读探索或不重叠的实现任务,不要让多个 agent 同时写同一批文件。
• 长会话及时 /compact,但关键计划要落到文件,这样压缩后仍然可恢复。
• 费用敏感时先看 成本优化 和 Prompt 缓存。

#官方参考

• Set up Claude Code in a monorepo or large codebase
• Memory and project instructions
• Permissions
• Worktrees

#推荐起点