大型代码库里怎么用 Claude Code

这篇适合谁、读完能做到什么

适合代码库已经大到 Claude 经常读进很多无关文件的团队，或者仓库里有很多包、一个人只负责其中一两个的情况。读完你能决定从哪一层目录启动 Claude，把说明文件拆到各个目录，屏蔽生成代码和 vendor 目录，并知道 worktree 和跨包访问该怎么配。

为什么大仓库要专门调

Claude Code 在任何规模下都能用，但它的默认设置是按小项目调的。仓库一大，默认的说明和文件读取很容易把上下文窗口塞满，和当前任务无关的内容一多，既费 token，也会影响 Claude 的表现^[1]。下面的办法都是围绕这一点展开的。

先想清楚从哪里启动

启动目录决定了 Claude 能直接读写哪些文件，也决定了启动时加载哪些 CLAUDE.md^[1]。

从仓库根目录启动：能访问每一个文件，启动时只加载根目录的 CLAUDE.md，子目录的文件按需加载。适合任务跨多个包或模块的情况^[1]。
从子目录启动：只能访问那个子树，除非你另外授权。启动时加载该目录和它所有祖先目录的 CLAUDE.md。适合任务只限于一个包或模块的情况^[1]。

要注意，.claude/settings.json 不像 CLAUDE.md 那样会从父目录继承，每个目录要各自的配置^[1]。

按目录分层写 CLAUDE.md

Claude Code 在启动时会加载工作目录及其所有父目录里的 CLAUDE.md，子目录里的文件则按需加载。所以常见的拆法是：根目录的文件写全仓库通用的规则，每个包或子系统一份，只写它自己的规范^[1]。

根目录的 CLAUDE.md 可以只放对所有包都适用的规则，比如：

Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example `api: add rate limiting`.
Never edit files under packages/*/generated/. Run `npm run codegen` in the package instead.

怎么确认这些文件有没有被加载？运行 /context all，在 Memory files 列表里查看^[1]。

另一种做法是路径范围规则（path-scoped rules）。它放在 .claude/rules/ 下，只有 Claude 处理匹配 paths: 通配符的文件时才加载。分目录的 CLAUDE.md 则是在启动目录里加载，或者按需加载。两种方式可以按「规范由谁维护、放在哪里看得最清楚」来选^[1]。

如果你从根目录启动，又有某些目录完全用不上，可以用 claudeMdExcludes 把它们的 CLAUDE.md 排除掉。它是一份静态列表，不是按任务切换的开关。要在今天聚焦一个包、明天聚焦另一个包，更简单的办法是换个启动目录^[1]。例如，把下面的配置放进 .claude/settings.local.json，就能跳过另一个团队负责的包：

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

少读无关文件：读取拒绝规则

上下文里的内容不只来自说明文件，文件读取也是一大块。Claude 的内容搜索默认遵守 .gitignore，所以 node_modules/、dist/、build/ 这些已经列在里面的目录，不需要额外设置就能排除在搜索结果之外^[1]。

但如果 vendor 目录或者生成代码是提交进仓库的，.gitignore 管不到它们。这时可以在 permissions.deny 里加 Read 拒绝规则，阻止 Claude 打开这些文件^[1]。例如在 .claude/settings.json 里写：

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

这里的目录规则以 /**/* 结尾，而不是 /**。前者只禁止目录里面的内容，目录本身仍能列出来或进入^[1]。

拒绝规则的覆盖范围要看清楚。它管 Claude 的内置文件工具，也管 Bash 里 cat、head、grep、find 这类被识别的文件命令（当被拒绝的路径作为参数出现时），以及 < file 这样的重定向目标。但它管不到子进程自己打开的文件^[1]。

规则放在哪里，取决于要约束的人。提交到 .claude/settings.json 对仓库里的所有人生效；放在根目录的 .claude/settings.local.json 只对自己生效；如果要强制执行，就放进托管设置，用户和项目设置都覆盖不了它^[1]。

用代码智能代替全文扫描

在大仓库里，找一个符号的定义或调用方，往往要读很多文件、跑很多次 grep。代码智能插件把 Claude 连接到语言服务器（language server），让它直接跳转定义、查找引用，并给出类型错误，不必一个个文件扫。官方插件市场里有 TypeScript、Python、Go、Rust 等常见语言的插件^[1]。

在终端里运行 claude，然后在提示符下输入下面的命令，就能装上 TypeScript 插件：

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

用这类插件时，每位开发者的机器上都要装好对应语言的语言服务器，官方插件市场托管在 GitHub 上，安装时需要能访问 GitHub^[1]。

只检出需要的目录

--worktree 会新建一个 git worktree，让改动和主检出隔离开。默认情况下它会检出整个仓库。仓库很大时，worktree.sparsePaths 会用 git 稀疏检出（sparse-checkout），只把列出的目录加上根目录的文件写到磁盘上，所以 worktree 启动更快，也更省空间^[1]。

在 .claude/settings.json 里可以这样写：

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

这里要列的是目录，不是单个文件。根目录的文件（比如 package.json 和锁文件）总会被检出，但根目录下的目录不会，所以如果 worktree 里要用到根目录的 .claude/settings.json 或 .claude/rules/，要把 .claude 也列进去^[1]。

另外，symlinkDirectories 可以和 sparsePaths 搭配使用，比如把 node_modules 列进去。这样每个 worktree 里的 node_modules/ 会是一个指回主仓库副本的符号链接，而不是磁盘上的另一份拷贝^[1]。

跨包访问和按目录的 skill

如果你从子目录启动，又需要改另一个包里的文件，比如同时改一个 api 和 web 都引用的共享类型，就要授权访问兄弟目录。.claude/settings.json 里的 additionalDirectories 可以做到。相对路径以你启动 Claude 的目录为基准。例如从 packages/api/ 启动时，写上 "../shared" 和 "../web"，就能读写这两个兄弟包^[1]。

授权的方式不同，加载的内容也不同。用 additionalDirectories 添加的目录，不会加载它的 CLAUDE.md、规则文件或 skill。用 --add-dir 或 /add-dir 添加的目录会加载 skill；要让它的 CLAUDE.md 和规则也加载，需要设置环境变量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD，比如 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared^[1]。

每个子目录也可以定义自己的 skill，放在 .claude/skills/ 下，Claude 判断相关时才按需加载。创建一个 skill 目录，比如 mkdir -p packages/api/.claude/skills/api-testing，然后在里面写 SKILL.md^[1]。

skill 多了有个问题：Claude 会读取所有已发现 skill 的名字和描述来挑选，描述太多时，有些 skill 的描述会被截掉。所以描述要写短，开头就用请求里会出现的词^[1]。

限制和常见问题

sparsePaths 和 symlinkDirectories 在创建 worktree 前读取。 它们是从你启动的目录里读的。创建之后，会话的工作目录变成 worktree 根目录，所以子目录里的 additionalDirectories 在 worktree 里不会生效^[1]。
拒绝规则不挡子进程。 子进程自己打开的文件，规则拦不住^[1]。
代码智能插件需要本机的语言服务器。 没装对应的二进制，插件就用不上^[1]。
没有稀疏检出就不要指望节省空间。 只有设了 worktree.sparsePaths，worktree 才只写列出的目录^[1]。