Monorepo 的核心挑战是「代码多、依赖复杂、改一处影响多处」—— 这正是 Claude Code 发挥价值的场景，但需要正确配置上下文。
Monorepo 项目结构示例
my-monorepo/ ← 根目录
├── CLAUDE.md ← 全局规范（所有包共享）
├── .claude/
│ └── settings.json
├── package.json ← 根 package.json（pnpm workspaces）
├── turbo.json
├── packages/
│ ├── ui/ ← 共享 UI 组件库
│ │ ├── CLAUDE.md ← UI 包专项规范
│ │ └── src/
│ ├── shared/ ← 共享类型和工具函数
│ │ ├── CLAUDE.md
│ │ └── src/
│ └── api-client/ ← API 客户端 SDK
│ └── src/
└── apps/
├── web/ ← Next.js 前端
│ ├── CLAUDE.md ← Web 应用专项规范
│ └── src/
└── backend/ ← Fastify 后端
├── CLAUDE.md
└── src/
层级 CLAUDE.md 设计
Claude Code 会从当前目录向上查找所有 CLAUDE.md 并合并。
根目录 CLAUDE.md（全局规范）
markdown
# my-monorepo
## 项目概述
全栈 SaaS 应用 Monorepo，包含前端、后端、共享库
## 技术栈
- 构建工具：Turborepo + pnpm workspaces
- 语言：TypeScript 5.x（全栈统一）
- 测试：Vitest（所有包统一）
## 包结构
- packages/ui：可复用 React 组件库（shadcn/ui 风格）
- packages/shared：共享类型定义和工具函数
- packages/api-client：自动生成的 API 客户端
- apps/web：Next.js 15 前端应用
- apps/backend：Fastify + Prisma 后端
## 关键约定（所有包遵守）
- 所有包使用相同的 TypeScript 配置（继承 tsconfig.base.json）
- 包间引用使用 workspace 协议：`"@myapp/ui": "workspace:*"`
- 修改 packages/shared 中的类型后，必须检查所有依赖包的影响
## 跨包修改流程
1. 先修改 packages/shared 中的类型定义
2. 运行 `pnpm build --filter=shared` 编译
3. 检查类型报错：`pnpm tsc -b --noEmit`
4. 逐个修复受影响的包
5. 全量测试：`pnpm test`包级 CLAUDE.md（包专项规范）
markdown
# packages/ui - 共享组件库
## 组件设计原则
- 所有组件必须支持 dark mode（使用 CSS variables）
- Props 接口命名：`<ComponentName>Props`
- 每个组件必须有对应的 Storybook story
- 导出路径：从 `packages/ui/src/index.ts` 统一导出
## 禁止在此包中
- 引入 packages/api-client（组件库不应有业务逻辑）
- 直接使用 fetch 或 axios（由调用方处理数据）跨包访问：--add-dir
bash
# 在 apps/web 目录中工作，同时访问 packages/shared
claude --add-dir ../../packages/shared --add-dir ../../packages/ui
# 现在 Claude 能：
# - 看到 shared 包的类型定义
# - 理解 ui 包的组件 API
# - 做跨包的重构和影响分析跨包重构标准流程
场景：修改共享类型 User，添加 timezone 字段
你：需要给 packages/shared/src/types/user.ts 里的 User 类型
添加 timezone 字段（string，可选）。
请帮我：
1. 修改类型定义
2. 找出所有依赖 User 类型的地方
3. 评估哪些地方需要更新
4. 按优先级排序给出修改计划
Claude：
Step 1：修改类型定义 ✅
packages/shared/src/types/user.ts:
+ timezone?: string;
Step 2：依赖分析（通过搜索找到 23 处引用）
- apps/backend/src/services/user.service.ts（3处）
- apps/web/src/components/UserProfile.tsx（2处）
- packages/api-client/src/endpoints/users.ts（1处）
...
Step 3：需要更新的地方（按影响排序）...
大型 Monorepo 的上下文管理
50+ 包的 Monorepo 不能一次全量读取（Token 不够），需要按需加载：
bash
# 策略：从当前任务涉及的包开始，按需扩展
# 1. 先在根目录定位问题
claude "搜索整个项目里使用了 deprecated_function 的所有文件"
# 2. 定位到具体包后，进入该包工作
cd apps/backend
claude --add-dir ../../packages/shared
# 3. 需要跨包时，明确指定要添加的包
claude --add-dir ../../packages/api-client "api-client 和 backend 的 User 类型不一致，帮我同步"根目录 .claudeignore
# Monorepo 通用忽略配置
**/node_modules/
**/.turbo/
**/dist/
**/.next/
**/build/
**/*.d.ts # 编译生成的类型文件，看源码就够
**/*.js.map
pnpm-lock.yaml # 锁文件不需要 AI 分析
Turborepo + Claude Code 联动
bash
# 提交前验证（Claude 辅助检查 + Turbo 并行构建）
# 先用 Claude 做代码审查
claude -p "审查刚才的改动，重点检查跨包依赖是否正确" --output-format json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['result'])"
# 然后运行 Turbo 全量构建验证
pnpm turbo build test lint --filter=[HEAD^1] # 只构建有变更的包来源：Claude Code 官方文档 - docs.anthropic.com/en/docs/claude-code