# Claude Code 大型代码库与 Monorepo

> 在大型仓库、单体代码库和 Monorepo 中控制 Claude Code 的上下文、文件读取、Worktree、跨包访问和目录级技能。

URL: https://docs.passion8.cc/docs/claude-code/large-codebases
Language: zh-CN
Publisher: Passion8

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




Passion8 网关只处理模型请求,不会替你缩小本地仓库上下文。大型仓库的性能和成本优化仍然要在 Claude Code 本地配置里完成。




## 启动位置决定边界

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

| 启动位置 | 文件访问 | 启动时加载的说明 | 适合场景 |
| --- | --- | --- | --- |
| 仓库根目录 | 默认可访问整个仓库 | 根 `CLAUDE.md`; 子目录说明按需加载 | 跨包改动、全局重构、架构梳理 |
| 子目录 | 默认只访问该子树 | 子目录 `CLAUDE.md` 加上所有父级 `CLAUDE.md` | 单包开发、单服务排错、降低上下文 |

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

## 分层 `CLAUDE.md`

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

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

示例:

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

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

## 排除无关说明

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

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

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

## 限制文件读取

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

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

这些规则会阻止 Claude Code 的读取工具打开对应路径,也会约束常见的 `cat`、`head`、`grep`、`find` 命令。它不会从递归搜索结果里隐藏路径名,但能阻止继续读取内容。更多权限写法见 [权限与模式](https://docs.passion8.cc/docs/claude-code/permissions)。

## 用代码智能减少扫描

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

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

语言服务器需要每个开发者本机有对应二进制。受限网络下,可以把插件市场放在内部 Git 或本地路径。插件和 Skills 的分发方式见 [插件与 Skills](https://docs.passion8.cc/docs/claude-code/plugins)。

## 稀疏 Worktree

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

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

注意点:

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

并行 Worktree 的策略见 [Worktrees 并行工作区](https://docs.passion8.cc/docs/claude-code/worktrees) 和 [多代理、后台与 Workflows](https://docs.passion8.cc/docs/claude-code/parallel-agents)。

## 跨包访问

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

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

也可以一次性传参:

```bash
claude --add-dir ../shared
```

| 方式 | 加载额外目录的 `CLAUDE.md` 和 rules | 加载 Skills | 适合 |
| --- | --- | --- | --- |
| `additionalDirectories` | 不加载 | 不加载 | 团队固定跨包访问 |
| `--add-dir` 或 `/add-dir` | 需要额外环境变量 | 会加载 | 临时跨目录任务 |

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

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

## 目录级 Skills

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

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

`SKILL.md` 示例:

```markdown
---
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`,但关键计划要落到文件,这样压缩后仍然可恢复。
- 费用敏感时先看 [成本优化](https://docs.passion8.cc/docs/claude-code/cost-saving) 和 [Prompt 缓存](https://docs.passion8.cc/docs/claude-code/prompt-caching)。

## 官方参考

- [Set up Claude Code in a monorepo or large codebase](https://code.claude.com/docs/en/large-codebases.md)
- [Memory and project instructions](https://code.claude.com/docs/en/memory.md)
- [Permissions](https://code.claude.com/docs/en/permissions.md)
- [Worktrees](https://code.claude.com/docs/en/worktrees.md)

## 推荐起点



- [只改一个包](https://docs.passion8.cc/docs/claude-code/context): 从子目录启动,让上下文自然缩小,再按需 add-dir。
- [跨包并行开发](https://docs.passion8.cc/docs/claude-code/worktrees): 用 Worktree 和 sparsePaths 控制磁盘与上下文范围。
- [团队统一规则](https://docs.passion8.cc/docs/claude-code/enterprise-admin): 用托管 settings、插件和 MCP 统一治理。
- [企业部署总览](https://docs.passion8.cc/docs/claude-code/enterprise-deployment-overview): 把大型仓库策略纳入组织 rollout 和 managed settings。
- [安全限制读取](https://docs.passion8.cc/docs/claude-code/permissions): 用 Read deny 和权限模式阻止读取敏感或生成文件。