在大型 Monorepo 中使用 AI 智能体

在 Monorepo 中,AI 智能体很容易迷失在错误的子项目里——正确的 CLAUDE.md 结构能让它保持专注。

大型仓库中的问题

Monorepo 通常包含许多子项目:一个后端、一个前端、共享库。用一个 CLAUDE.md 文件涵盖所有内容,要么会变得非常庞大(每次会话都会占用任务根本不需要的上下文),要么会过于笼统,起不到真正的帮助作用。

解决方案:多个 CLAUDE.md 文件

与其用一个文件涵盖所有内容,不如为每个子项目建立单独的 CLAUDE.md。根目录下的文件包含通用规则(提交风格、大致结构)。每个子项目都有自己的文件,记录其特定的命令和约定。

加载机制

如果你在根目录启动智能体,它启动时只会加载根目录的 CLAUDE.md;子文件夹中的文件只有在智能体实际读取那里的文件时才会加载。如果你直接在某个子项目中启动它,它会获得该文件夹及所有上级文件夹的 CLAUDE.md——但默认情况下只能访问这个子树。

强制聚焦

对于明确属于某个子项目的任务,直接在那里启动智能体比在根目录启动更划算。这样能自动让上下文和文件访问范围保持精简——你不必在每次任务时都解释仓库的哪些部分现在是无关的。

示例

一个包含 packages/api、packages/web 和 packages/shared 的 Monorepo,会有一个根 CLAUDE.md("三个包:api(Node/Express)、web(React/Vite)、shared(TS 工具库)。命令始终在对应的包文件夹中执行。"),再加上一个独立的 packages/api/CLAUDE.md,记录 API 特定的测试命令。如果智能体直接在 packages/api/ 中启动,它能看到这两个文件——但看不到 packages/web/ 中的任何内容。

小测验

如果你直接在 Monorepo 的某个子文件夹(例如 packages/api/)中启动 Claude Code,而不是在根目录启动,默认会发生什么?