Claude Code 学习站
Mingyu's Library

学习站 / 实战 Tip / E · 配置与选型

大仓库 monorepo

仓库百万行、几十个 package,Claude 的上下文很快被无关代码和别的团队的约定填满——解法是给它划作用域。

大仓库配置的核心思路只有一句:让 Claude 只看见当前任务相关的那部分。手段有四类——CLAUDE.md 分层、启动位置选作用域、deny 规则挡无关读取、探索走隔离上下文,层层叠加而不是互相替代。

一句话结论

结论 根目录 CLAUDE.md 只讲全仓布局和通用约定(200 行内),每个 package 放自己的 CLAUDE.md(子目录文件按需加载不占启动上下文);单包任务从包目录启动 Claude 缩小作用域;再用 claudeMdExcludes 排除别的团队的文件、用 Read deny 规则挡住 dist/build/vendored 代码。

做法步骤

  1. 分层 CLAUDE.md:根讲全局,包讲局部。官方Claude Code 启动时加载工作目录及所有祖先目录的 CLAUDE.md;子目录的 CLAUDE.md 不在启动时加载,而是当 Claude 用 Read 工具读到那个目录的文件时按需载入。所以正确分工是:根 CLAUDE.md 写仓库结构、全局编码/提交约定;packages/api/CLAUDE.md 写该包的测试命令、目录结构、局部规矩。都提交进仓库让全队继承。单文件目标 200 行内,超了就把参考材料挪到 skill 或 .claude/rules/(规则可用 paths: frontmatter 只在匹配文件时加载,详见 D4 CLAUDE.md 与 rules)。
  2. 用启动位置选作用域。官方从哪里运行 claude 决定文件访问范围和载入哪些 CLAUDE.md:跨包任务从仓库根启动(能读所有文件,只载根 CLAUDE.md,子目录的按需来);单包任务从 packages/api/ 启动(只载该包 + 祖先的 CLAUDE.md,别的包完全不进上下文)。注意 .claude/settings.json 项目设置只从启动目录加载、不像 CLAUDE.md 那样从父目录继承。从子目录启动后要跨包改文件,用 --add-dir ../shared 或在设置里配 additionalDirectories。
  3. 排除无关内容:两个开关。官方其一,claudeMdExcludes(放 .claude/settings.local.json 保持个人生效)按 glob 跳过别的团队的 CLAUDE.md,如 "**/packages/web/**";管理策略下发的 CLAUDE.md 不可排除。其二,内容搜索默认尊重 .gitignore,已忽略的 node_modules/、dist/ 不会进搜索结果;但对已提交的生成代码和 vendored 依赖,要加 Read deny 规则,例如 "Read(./**/dist/**)"、"Read(./**/*.generated.*)"、"Read(./vendor/**)",Claude 连打开都不会打开。
  4. 搜索与上下文策略。官方两招减少「为找一个符号读几十个文件」:装语言对应的 code intelligence 插件(/plugin install typescript-lsp@claude-plugins-official),让 Claude 走 language server 跳定义/找引用而不是全文扫描;大范围探索交给 subagent,在独立上下文里读文件、只把结论带回主会话(D10 Subagents)。跨包大改动前先 plan 并让 Claude 把计划写成 markdown 文件——长会话会压缩上下文,落盘的计划不会丢。
  5. 可选进阶。官方worktree 隔离开发时,worktree.sparsePaths 让新 worktree 只检出列出的目录(记得包含 .claude),symlinkDirectories 把 node_modules 软链回主检出;每个包还可以放自己的 .claude/skills/,API 包的测试套路只在做 API 任务时载入。配好后跑 /context,在 Memory files 一栏确认载入的正是你预期的那几个文件。

可直接抄的 prompt

这是一个 monorepo,帮我做大仓库配置:

1. 读根目录结构和 packages/ 下各包的用途,在仓库根写一个 200 行以内的
   CLAUDE.md:只讲仓库布局、各包一句话说明、全局约定(包管理器、提交规范、
   「在包目录跑命令而不是根目录」这类规则);
2. 给我正在做的包 packages/<包名> 写它自己的 CLAUDE.md:构建/测试/迁移
   命令、目录结构、该包特有的约定;
3. 在启动目录的 .claude/settings.json 里加 permissions.deny 的 Read 规则,
   挡住 dist/、build/、*.generated.* 和 vendored 代码;
4. 列出你创建/修改的所有文件。我之后会重启会话并用 /context 验证
   Memory files 里只载入了预期的文件。

来源与最后核实日期