<!-- title: Claude Code大型代码库与Monorepo全实战 -->
# Claude Code大型代码库与Monorepo全实战

## 概述

本教程面向中高级开发者，系统讲解如何在大型代码库和Monorepo中高效使用Claude Code。你将学会嵌套CLAUDE.md分层架构、Sparse Worktree按需加载、多仓库Workspace协同、Token优化策略，以及企业级代码库的实战工作流。学完后你能在百万行级项目中让Claude Code精准聚焦、降低Token消耗、跨仓协同无障碍。

**适用人群**：有Claude Code基础使用经验，正在或即将在大型项目/多仓库环境中工作的开发者。

## 前置条件

- Claude Code CLI已安装并完成基本配置（版本 ≥ 1.0.30）
- 了解CLAUDE.md基础用法
- 熟悉Git worktree概念
- 至少一个可实操的项目仓库

## 核心挑战：为什么大型代码库需要特殊策略

在小型项目中，Claude Code开箱即用效果很好。但当代码库增长到一定规模时，三个核心问题会急剧恶化：

**1. 上下文窗口爆炸**——百万行代码远超200K token的上下文容量，Claude无法"看到"全部代码。

**2. Token成本失控**——每轮对话加载的无关上下文越多，无效Token消耗越大。社区实测数据显示，未优化的会话Token用量可达优化后的3-5倍。

**3. 聚焦能力下降**——当无关文件充斥上下文时，Claude容易"跑偏"，产生与当前任务无关的修改。

Context Engineering（上下文工程）是2026年的核心方法论：不是让Claude"读更多"，而是精准控制"它读到什么"。

```mermaid
flowchart TB
    subgraph 问题域["大型代码库三大挑战"]
        A["上下文窗口爆炸<br/>200K token << 百万行代码"]
        B["Token成本失控<br/>无关上下文3-5x消耗"]
        C["聚焦能力下降<br/>无关文件导致跑偏"]
    end
    subgraph 解决方案["Context Engineering四层策略"]
        D["L1: 嵌套CLAUDE.md<br/>分层指令架构"]
        E["L2: Sparse Worktree<br/>按需加载代码"]
        F["L3: Workspace协同<br/>多仓库统一视图"]
        G["L4: Token优化<br/>缓存与精简"]
    end
    A --> D
    B --> G
    C --> E
    D --> F
    E --> F
    F --> G
    style 问题域 fill:#fff3e0,stroke:#e65100
    style 解决方案 fill:#e8f5e9,stroke:#1b5e20
```

---

## 第一步：嵌套CLAUDE.md分层架构

### 1.1 理解层级继承机制

Claude Code的CLAUDE.md采用**就近继承**原则：子目录的CLAUDE.md会叠加父目录的指令，而非完全覆盖。这意味着你可以构建一棵精细的指令树。

```
my-monorepo/
├── CLAUDE.md                    # L0: 全局规则（架构约束、编码规范、通用指令）
├── packages/
│   ├── frontend/
│   │   ├── CLAUDE.md            # L1: 前端专属规则
│   │   ├── src/
│   │   │   ├── components/
│   │   │   │   └── CLAUDE.md    # L2: 组件库规则
│   │   │   └── hooks/
│   │   │       └── CLAUDE.md    # L2: Hooks规则
│   │   └── ...
│   ├── backend/
│   │   ├── CLAUDE.md            # L1: 后端专属规则
│   │   ├── src/
│   │   │   ├── api/
│   │   │   │   └── CLAUDE.md    # L2: API层规则
│   │   │   └── models/
│   │   │       └── CLAUDE.md    # L2: 数据模型规则
│   │   └── ...
│   └── shared/
│       ├── CLAUDE.md            # L1: 共享库规则
│       └── ...
├── .claude/
│   └── settings.json            # 项目级Claude Code配置
└── ...
```

### 1.2 编写有效的分层CLAUDE.md

**L0 全局规则（根目录CLAUDE.md）**

```markdown
# 项目概览
这是一个Monorepo项目，使用pnpm workspace管理。

## 技术栈
- 前端: React 19 + TypeScript 5.7 + Vite
- 后端: Node.js 22 + Express + Prisma
- 共享: Zod schema验证

## 全局编码规范
- 使用ESLint严格模式，禁止any类型
- 所有API响应使用shared包中的Zod schema验证
- 组件使用函数式组件 + Hooks
- 测试覆盖率不低于80%

## 架构约束
- packages/frontend不得直接导入packages/backend的代码
- 跨包引用必须通过packages/shared
- API层和业务逻辑层严格分离

## Git规范
- commit格式: type(scope): description
- PR目标分支为develop
```

**L1 前端专属规则（packages/frontend/CLAUDE.md）**

```markdown
# Frontend Package

## 本包结构
- src/components/: UI组件，使用Storybook管理
- src/hooks/: 自定义Hooks
- src/pages/: 页面级组件（路由入口）
- src/services/: API调用层，统一使用shared包的schema

## 关键约定
- 组件文件名使用PascalCase
- 每个组件目录包含: Component.tsx, Component.test.tsx, index.ts
- 样式使用CSS Modules，文件名: Component.module.css
- 状态管理使用Zustand，store文件放在src/stores/

## 常用命令
- pnpm --filter frontend dev: 启动开发服务器
- pnpm --filter frontend test: 运行测试
- pnpm --filter frontend storybook: 启动Storybook

## 常见陷阱
- 不要在组件中直接调用fetch，使用src/services/中的封装
- 路由定义在src/router.tsx，不要在页面组件中嵌套路由
```

**L2 组件库规则（packages/frontend/src/components/CLAUDE.md）**

```markdown
# 组件开发规范

## 设计系统
- 颜色变量定义在src/styles/tokens.css
- 间距使用4px基准网格（4, 8, 12, 16, 24, 32, 48）
- 圆角: sm=4px, md=8px, lg=16px, full=9999px

## 组件模板
创建新组件时，按以下结构组织:
- [ComponentName].tsx: 组件实现
- [ComponentName].test.tsx: 单元测试（使用testing-library）
- [ComponentName].stories.tsx: Storybook story
- index.ts: 导出

## 性能要求
- 列表组件超过100项必须虚拟化
- 图片使用loading="lazy"
- 避免在render中创建内联对象/函数
```

### 1.3 关键原则

| 原则 | 说明 | 示例 |
|------|------|------|
| **就近聚焦** | CLAUDE.md只写与当前目录相关的规则 | 组件目录不写API规范 |
| **避免重复** | 子级只补充，不重述父级已有内容 | 前端包不重复全局技术栈 |
| **实用导向** | 包含具体命令、文件路径、常见陷阱 | 写明pnpm --filter命令 |
| **精简至上** | 每个CLAUDE.md控制在50行以内 | 用表格和列表压缩信息 |

### 1.4 常见问题

**Q: CLAUDE.md层级太深，Claude会加载所有层级吗？**
A: 是的，Claude会加载从根到当前目录的所有CLAUDE.md。这正是精简原则重要的原因——每层只写增量信息。

**Q: 如果子目录没有CLAUDE.md会怎样？**
A: Claude仅使用父级CLAUDE.md，不会报错。不需要每个目录都创建。

---

## 第二步：Sparse Worktree按需加载

### 2.1 为什么需要Sparse Worktree

在大型Monorepo中，你可能只修改其中一个包。如果Claude Code读取整个仓库，大量无关代码会浪费上下文窗口。Sparse Worktree让Git只检出你正在工作的子目录。

### 2.2 设置Sparse Checkout

```bash
# 1. 克隆仓库时直接启用sparse-checkout
git clone --sparse https://github.com/org/my-monorepo.git
cd my-monorepo

# 2. 仅检出前端包
git sparse-checkout set packages/frontend packages/shared

# 3. 验证检出内容
ls packages/
# 输出: frontend/ shared/
# backend/不会出现在磁盘上

# 4. 后续需要添加其他包
git sparse-checkout add packages/backend
```

### 2.3 结合Claude Code使用

```bash
# 在sparse-checkout环境中启动Claude Code
claude

# Claude Code只能"看到"已检出的文件
# 它不会感知到未检出的packages/backend
# 这天然限制了上下文范围
```

### 2.4 Sparse Worktree高级模式：按任务切换

```bash
# 创建一个工作脚本: switch-context.sh
#!/bin/bash
TASK=$1

case $TASK in
  "frontend")
    git sparse-checkout set packages/frontend packages/shared
    echo "切换到前端上下文"
    ;;
  "backend")
    git sparse-checkout set packages/backend packages/shared
    echo "切换到后端上下文"
    ;;
  "full")
    git sparse-checkout disable
    echo "切换到完整上下文"
    ;;
  *)
    echo "用法: ./switch-context.sh frontend|backend|full"
    ;;
esac

# 使用方式
chmod +x switch-context.sh
./switch-context.sh frontend  # 切换到前端工作模式
claude                         # 启动Claude Code
```

### 2.5 预期效果

| 操作 | 完整检出 | Sparse Checkout |
|------|---------|-----------------|
| 磁盘占用 | 2.3GB | 400MB（仅frontend+shared） |
| Claude首次索引时间 | 45s | 8s |
| 上下文浪费 | 高（包含无关包） | 低（仅相关包） |

---

## 第三步：多仓库Workspace协同

### 3.1 问题场景

许多企业采用多仓库（multi-repo）而非Monorepo。当Claude Code只在一个仓库中工作时，它无法感知其他仓库的代码、类型定义和API契约，导致跨仓修改容易出错。

### 3.2 Workspace目录方案

创建一个workspace根目录，将所有相关仓库克隆到统一结构下：

```bash
# 1. 创建workspace根目录
mkdir ~/my-workspace
cd ~/my-workspace

# 2. 克隆所有相关仓库
git clone git@github.com:org/frontend-app.git
git clone git@github.com:org/backend-api.git
git clone git@github.com:org/shared-types.git
git clone git@github.com:org/infra-config.git

# 3. 创建workspace级CLAUDE.md
# 这是关键：告诉Claude Code整个workspace的结构
```

**workspace级CLAUDE.md（~/my-workspace/CLAUDE.md）**

```markdown
# Workspace概览

## 仓库关系
- frontend-app: React前端应用，消费backend-api的接口
- backend-api: Express API服务，使用shared-types定义契约
- shared-types: Zod schema和TypeScript类型定义，前后端共享
- infra-config: Docker/K8s部署配置

## 跨仓库依赖图
- frontend-app → shared-types（类型导入）
- backend-api → shared-types（schema验证）
- infra-config → frontend-app, backend-api（镜像引用）

## 跨仓库修改规则
- 修改shared-types中的schema时，必须同步更新frontend-app和backend-api
- API路径变更时，检查frontend-app/src/services/中所有调用点
- 部署配置变更时，确认infra-config/中的环境变量映射

## 当前聚焦
- [在此标注你当前主要工作的仓库和任务]
```

### 3.3 Bootstrap仓库模式

对于更复杂的场景，可以创建一个专门的bootstrap仓库来管理workspace：

```bash
# bootstrap仓库结构
~/workspace-bootstrap/
├── CLAUDE.md              # workspace级指令
├── manifest.json          # 仓库清单和版本锁定
├── scripts/
│   ├── setup.sh           # 一键克隆所有仓库
│   ├── sync.sh            # 同步所有仓库到最新
│   └── status.sh          # 查看所有仓库状态
└── .claude/
    └── settings.json      # workspace级Claude Code配置
```

**manifest.json示例**

```json
{
  "workspace": "my-product",
  "repos": [
    {
      "name": "frontend-app",
      "url": "git@github.com:org/frontend-app.git",
      "branch": "main",
      "path": "frontend-app"
    },
    {
      "name": "backend-api",
      "url": "git@github.com:org/backend-api.git",
      "branch": "develop",
      "path": "backend-api"
    },
    {
      "name": "shared-types",
      "url": "git@github.com:org/shared-types.git",
      "branch": "main",
      "path": "shared-types"
    }
  ],
  "links": [
    {"from": "frontend-app", "to": "shared-types", "type": "types"},
    {"from": "backend-api", "to": "shared-types", "type": "schemas"}
  ]
}
```

**setup.sh脚本**

```bash
#!/bin/bash
# 从manifest.json读取仓库列表并克隆

MANIFEST="manifest.json"
REPOS=$(jq -r '.repos[] | "\(.url) \(.path) \(.branch)"' "$MANIFEST")

while IFS=' ' read -r url path branch; do
  if [ ! -d "$path" ]; then
    echo "克隆 $path ($branch)..."
    git clone -b "$branch" "$url" "$path"
  else
    echo "✓ $path 已存在，跳过"
  fi
done <<< "$REPOS"

echo "Workspace初始化完成"
```

### 3.4 使用patricio0312rev/workspaces工具

社区开源的workspaces工具提供了更规范的workspace管理：

```bash
# 安装workspaces工具
npm install -g @anthropic/workspaces
# 或直接使用npx
npx @anthropic/workspaces init

# 初始化workspace配置
npx @anthropic/workspaces init --name my-product

# 添加仓库
npx @anthropic/workspaces add frontend-app git@github.com:org/frontend-app.git
npx @anthropic/workspaces add backend-api git@github.com:org/backend-api.git

# 同步所有仓库
npx @anthropic/workspaces sync

# 查看workspace状态
npx @anthropic/workspaces status
```

```mermaid
flowchart LR
    subgraph Workspace["~/my-workspace/"]
        A["CLAUDE.md<br/>workspace级指令"]
        B["frontend-app/"]
        C["backend-api/"]
        D["shared-types/"]
        E["infra-config/"]
    end
    subgraph ClaudeCode["Claude Code会话"]
        F["读取workspace级<br/>CLAUDE.md"]
        G["理解跨仓库依赖"]
        H["执行跨仓库修改"]
    end
    A --> F
    B --> G
    C --> G
    D --> G
    G --> H
    B -.-> H
    C -.-> H
    D -.-> H
    style Workspace fill:#e3f2fd,stroke:#0d47a1
    style ClaudeCode fill:#f3e5f5,stroke:#4a148c
```

---

## 第四步：大型代码库的Token优化实战

### 4.1 Prompt Cache机制理解

Claude Code的Prompt Cache是节省Token的核心机制。理解其工作原理是优化成本的关键：

```
上下文链（从左到右，越靠左越稳定）：
tools → system → CLAUDE.md/skills → messages
```

**核心规则**：从左到右的任何变更都会导致该点之后的缓存失效。具体来说：

| 操作 | 缓存影响 | Token损失 |
|------|---------|-----------|
| 新增对话消息 | messages末尾追加 | 无（缓存命中） |
| 修改CLAUDE.md | CLAUDE.md段失效 | messages段全部重读 |
| 切换模型 | 整条链失效 | 全部重读 |
| 新增MCP服务器 | tools段变更 | 全部重读 |
| 加载新Skill | skills段追加 | messages段重读 |

### 4.2 实战优化策略

**策略一：精简CLAUDE.md，减少缓存失效影响**

```markdown
# ❌ 糟糕的CLAUDE.md（冗长、含大量示例代码）
本项目使用React框架，React是一个用于构建用户界面的JavaScript库...
组件应该遵循以下模式：
```tsx
// 30行示例代码
```
测试应该这样写：
```tsx
// 20行示例代码
```

# ✅ 好的CLAUDE.md（精简、结构化）
## 技术栈: React 19 + TypeScript 5.7
## 组件: 函数式 + Hooks，文件名PascalCase
## 测试: vitest + testing-library，覆盖率≥80%
## 命令: pnpm test | pnpm dev | pnpm build
```

**策略二：使用/compact主动压缩上下文**

```bash
# 在Claude Code会话中
# 当对话变长时，主动压缩
/compact

# 带提示词的压缩，保留关键信息
/compact 保留：API接口定义、数据库schema、当前修改的文件列表
```

**策略三：使用/effort控制思考深度**

```bash
# 简单任务用低effort，节省Token
/effort low    # 快速响应，减少思考Token

# 复杂架构问题用高effort
/effort high   # 深度思考，更全面
```

**策略四：按任务拆分会话**

```
# ❌ 一个会话处理多个不相关任务
"先修复登录页的CSS bug，然后重构数据库层，最后写API文档"

# ✅ 每个任务一个新会话
会话1: "修复登录页的CSS bug"（低effort）
会话2: "重构数据库层"（高effort）
会话3: "编写API文档"（中effort）
```

### 4.3 Token成本测算

以Sonnet 4.6为例（2026年6月定价）：

| 场景 | 未优化 | 优化后 | 节省 |
|------|--------|--------|------|
| 单次代码审查（10轮对话） | ~85K input tokens | ~30K input tokens | 65% |
| 跨文件重构（20轮对话） | ~250K input tokens | ~90K input tokens | 64% |
| 全天开发会话（60轮对话） | ~800K input tokens | ~250K input tokens | 69% |

关键优化杠杆：**减少每轮加载的CLAUDE.md总量** + **及时使用/compact** + **按任务切分会话**。

---

## 第五步：沙箱隔离与安全加固

### 5.1 大型代码库的特殊安全需求

在企业项目中，Claude Code可能有权限访问生产密钥、数据库凭证、客户数据。沙箱隔离不是可选项，而是必须项。

### 5.2 内置沙箱：文件系统与网络隔离

Claude Code内置的沙箱机制提供两层隔离：

**文件系统隔离**

```json
// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(pnpm test:*)",
      "Read(*)",
      "Edit(*)"
    ],
    "deny": [
      "Read(.env.production)",
      "Read(.env.staging)",
      "Read(*.pem)",
      "Read(*.key)",
      "Read(secrets/*)",
      "Bash(rm -rf:*)",
      "Bash(curl:*production*)"
    ]
  }
}
```

**网络隔离（沙箱Bash工具）**

```bash
# 启用沙箱模式，Claude的Bash命令在网络隔离环境中执行
claude --sandbox

# 或在设置中永久启用
# .claude/settings.json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowedPaths": ["src/", "tests/", "docs/"],
      "deniedPaths": [".env*", "secrets/", "*.key"]
    },
    "network": {
      "allowed": ["localhost:*", "127.0.0.1:*"],
      "denied": ["*.production.com", "*.internal.company.com"]
    }
  }
}
```

### 5.3 Docker沙箱方案

对于更严格的隔离需求：

```dockerfile
# claude-sandbox.Dockerfile
FROM node:22-slim

RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*

# 仅挂载需要的代码目录
WORKDIR /workspace

# 安装Claude Code CLI
RUN npm install -g @anthropic-ai/claude-code

# 创建非root用户
RUN useradd -m claude-user
USER claude-user

ENTRYPOINT ["claude"]
```

```bash
# 使用Docker运行Claude Code
docker build -t claude-sandbox -f claude-sandbox.Dockerfile .

docker run -it --rm \
  -v $(pwd)/packages/frontend:/workspace/frontend:ro \
  -v $(pwd)/packages/shared:/workspace/shared:ro \
  -v claude-output:/workspace/output \
  --network none \
  claude-sandbox
```

### 5.4 沙箱环境对比

| 方案 | 隔离级别 | 易用性 | 适用场景 |
|------|---------|--------|---------|
| 内置沙箱Bash | 文件+网络 | ⭐⭐⭐⭐⭐ | 日常开发 |
| Dev Container | 文件+网络+进程 | ⭐⭐⭐⭐ | 团队标准化 |
| Docker | 完全隔离 | ⭐⭐⭐ | CI/CD、审查外部代码 |
| VM | 硬件级隔离 | ⭐⭐ | 最高安全要求 |

```mermaid
flowchart TD
    A["大型代码库安全需求"] --> B{"威胁模型评估"}
    B -->|"日常开发"| C["内置沙箱Bash<br/>轻量文件+网络隔离"]
    B -->|"团队协作"| D["Dev Container<br/>标准化开发环境"]
    B -->|"CI/CD集成"| E["Docker容器<br/>完全隔离+无网络"]
    B -->|"最高安全"| F["虚拟机<br/>硬件级隔离"]
    C --> G["配置:.claude/settings.json"]
    D --> H["配置:.devcontainer/devcontainer.json"]
    E --> I["配置:Dockerfile + docker-compose"]
    F --> J["配置:Vagrant/VirtualBox"]
    style A fill:#fff3e0,stroke:#e65100
    style C fill:#e8f5e9,stroke:#1b5e20
    style D fill:#e8f5e9,stroke:#1b5e20
    style E fill:#e8f5e9,stroke:#1b5e20
    style F fill:#ffebee,stroke:#b71c1c
```

---

## 实战案例：在Monorepo中完成跨包功能开发

### 场景描述

在一个电商Monorepo中，需要添加"用户收藏"功能。涉及三个包的修改：
- `packages/shared/`：添加收藏相关的Zod schema
- `packages/backend/`：添加收藏API端点
- `packages/frontend/`：添加收藏按钮和收藏页面

### 完整操作流程

```bash
# 步骤1: 使用sparse-checkout聚焦到相关包
cd ~/my-monorepo
git sparse-checkout set packages/shared packages/backend packages/frontend

# 步骤2: 创建功能分支
git checkout -b feat/user-favorites

# 步骤3: 在shared包中定义schema
claude -p "在packages/shared/src/schemas/下创建favorite.schema.ts，
定义UserFavorite的Zod schema，包含userId(string)、productId(string)、
createdAt(Date)字段。导出推断的TypeScript类型。"

# 步骤4: 在backend包中实现API
claude -p "在packages/backend/src/api/favorites/下创建路由。
使用packages/shared/src/schemas/favorite.schema.ts中的schema验证。
实现三个端点：
POST /api/favorites - 添加收藏
DELETE /api/favorites/:productId - 取消收藏
GET /api/favorites - 获取用户收藏列表
使用Prisma操作数据库，遵循packages/backend/CLAUDE.md中的架构规范。"

# 步骤5: 在frontend包中实现UI
claude -p "在packages/frontend/src/下实现收藏功能：
1. src/services/favorites.ts - API调用封装
2. src/components/FavoriteButton/ - 收藏按钮组件
3. src/pages/FavoritesPage/ - 收藏列表页面
遵循packages/frontend/CLAUDE.md中的组件规范。"

# 步骤6: 运行全量测试验证
claude -p "运行所有相关包的测试，确保没有破坏现有功能：
pnpm --filter shared test
pnpm --filter backend test
pnpm --filter frontend test"
```

### 关键技巧

**技巧一：让Claude读取相关CLAUDE.md**

在对话中显式引用：
```
请先阅读 @packages/backend/CLAUDE.md 了解后端架构规范，然后实现收藏API
```

**技巧二：跨包修改时指定上下文**

```
我需要修改三个包。请按以下顺序工作：
1. 先在shared包定义schema（这是基础）
2. 然后在backend包实现API（依赖shared）
3. 最后在frontend包实现UI（依赖shared和backend API）

每完成一个包，运行该包的测试确认无误后再继续。
```

**技巧三：使用plan mode规划大功能**

```
# 进入plan mode，让Claude先规划再动手
claude
> 请为"用户收藏"功能制定详细的实现计划，
> 涉及shared、backend、frontend三个包。
> 使用EnterPlanMode进入规划模式。
```

---

## 第六步：并行会话与任务分配

### 6.1 多会话并行工作

在大型项目中，可以开启多个Claude Code会话，每个聚焦不同任务：

```bash
# 终端1: 处理前端任务
cd ~/my-monorepo/packages/frontend
claude
# 这个会话的上下文仅包含前端相关代码

# 终端2: 处理后端任务
cd ~/my-monorepo/packages/backend
claude
# 这个会话的上下文仅包含后端相关代码

# 终端3: 处理CI/CD
cd ~/my-monorepo
claude -p "检查.github/workflows/中的CI配置，确保新增的favorites测试已包含"
```

### 6.2 会话间协调注意事项

| 注意点 | 说明 |
|--------|------|
| 文件冲突 | 不同会话不要修改同一文件 |
| 依赖顺序 | shared包修改后，等其完成再让其他会话使用 |
| Git分支 | 每个会话使用独立分支，避免冲突 |
| 测试隔离 | 每个会话运行自己包的测试 |

---

## 高级技巧：代码智能与索引优化

### 使用.claudeignore排除无关文件

```
# .claudeignore
# 排除大型生成文件，减少上下文噪声
node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.min.css
*.map
vendor/
# 排除二进制文件
*.png
*.jpg
*.woff
*.woff2
# 排除数据文件
*.csv
*.sql
```

### Per-Package Skills

在大型Monorepo中，可以为不同包配置专属Skills：

```json
// packages/frontend/.claude/settings.json
{
  "skills": {
    "frontend-lint": {
      "description": "前端代码质量检查",
      "command": "pnpm --filter frontend lint"
    }
  }
}
```

### 使用/grep和/glob替代全文件读取

```
# ❌ 让Claude读取整个目录
"请看一下src/components/目录下的所有文件"

# ✅ 引导Claude使用精准搜索
"在src/components/中搜索所有使用了useState的文件，
告诉我哪些组件有状态管理"
```

---

## 完整工作流Mermaid图

```mermaid
flowchart TB
    Start["开始大型项目工作"] --> Assess{"项目类型？"}
    Assess -->|"Monorepo"| Mono["配置嵌套CLAUDE.md<br/>Sparse Checkout"]
    Assess -->|"多仓库"| Multi["创建Workspace目录<br/>Bootstrap仓库"]
    Assess -->|"单仓大型"| Single["优化CLAUDE.md<br/>配置.claudeignore"]

    Mono --> Sandbox["选择沙箱级别"]
    Multi --> Sandbox
    Single --> Sandbox

    Sandbox --> Dev["开始开发"]
    Dev --> Task{"任务复杂度？"}

    Task -->|"简单<br/><5个文件"| Direct["直接对话模式<br/>/effort low"]
    Task -->|"中等<br/>跨包修改"| Plan["Plan Mode规划<br/>分步执行"]
    Task -->|"复杂<br/>架构级"| MultiSession["多会话并行<br/>按包分配"]

    Direct --> Review["代码审查"]
    Plan --> Review
    MultiSession --> Merge["合并分支<br/>解决冲突"]
    Merge --> Review

    Review --> Test{"测试通过？"}
    Test -->|"是"| Compact["/compact压缩<br/>准备下一步"]
    Test -->|"否"| Fix["修复问题"]
    Fix --> Review

    Compact --> Done["提交代码"]

    style Start fill:#e3f2fd,stroke:#0d47a1
    style Done fill:#e8f5e9,stroke:#1b5e20
    style Assess fill:#fff3e0,stroke:#e65100
    style Task fill:#fff3e0,stroke:#e65100
    style Test fill:#fff3e0,stroke:#e65100
```

---

## 常见问题排查

### 问题一：Claude Code在大型项目中响应缓慢

**诊断**：上下文过载导致。

```bash
# 检查当前CLAUDE.md总大小
find . -name "CLAUDE.md" -exec wc -c {} + | sort -n

# 如果总计超过10KB，精简内容
# 理想范围：所有CLAUDE.md总计3-8KB
```

**解决**：
1. 精简CLAUDE.md，移除示例代码和冗长解释
2. 使用.claudeignore排除大文件目录
3. 启用sparse-checkout减少可见文件

### 问题二：Claude修改了不该动的文件

**诊断**：CLAUDE.md约束不足或权限配置缺失。

**解决**：
1. 在CLAUDE.md中明确标注"不要修改"的区域
2. 在.claude/settings.json的deny列表中添加敏感路径
3. 启用沙箱模式限制文件系统访问

### 问题三：跨包修改后测试失败

**诊断**：会话间缺乏协调。

**解决**：
1. 始终先修改shared包并确认测试通过
2. 使用显式的步骤指令："先完成shared包，运行测试通过后再改backend"
3. 在CLAUDE.md中标注包间依赖关系

---

## 延伸阅读

- [Claude Code官方文档 - Monorepo配置](https://code.claude.com/docs/en/large-codebases) — Anthropic官方大型代码库最佳实践
- [Claude Code沙箱工程博客](https://www.anthropic.com/engineering/claude-code-sandboxing) — Anthropic工程团队详解沙箱设计
- [Claude Code最佳实践（社区）](https://github.com/shanraisshan/claude-code-best-practice) — 从vibe coding到工程化的实践总结
- [Context Engineering完整指南](https://unmarkdown.com/blog/context-engineering-complete-guide) — 2026年上下文工程方法论
- [Claude Code Token优化系统指南](https://buildtolaunch.substack.com/p/claude-code-token-optimization) — 19个Token优化实操建议
- [Multi-Repo Workspace方案](https://karun.me/blog/2026/03/26/structuring-claude-code-for-multi-repo-workspaces/) — 多仓库workspace架构设计
- [Patricio0312rev/workspaces工具](https://github.com/patricio0312rev/workspaces) — 多仓库workspace管理CLI

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | 企业内训、高级开发者训练营、团队Onboarding |
| **预计教学时长** | 4-5小时（含实操） |
| **难度等级** | ⭐⭐⭐⭐（中高级） |
| **实操占比** | 70%（大量动手配置） |
| **前置课程** | Claude Code基础使用、Git进阶 |
| **学员收益** | 掌握企业级大型项目的Claude Code工程化能力，日节省30-60%Token成本 |

## 参考来源

1. [Set up Claude Code in a monorepo or large codebase](https://code.claude.com/docs/en/large-codebases) — Anthropic官方大型代码库配置文档，涵盖嵌套CLAUDE.md、Sparse Worktree、代码智能
2. [Making Claude Code more secure and autonomous with sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) — Anthropic工程博客，详解沙箱架构与文件系统/网络双层隔离
3. [Claude Code Token-Saving Guide](https://knightli.com/en/2026/05/18/claude-code-prompt-cache-token-optimization/) — Prompt Cache机制深度解析，上下文链模型与缓存失效规则
4. [Structuring Claude Code for Multi-Repo Workspaces](https://karun.me/blog/2026/03/26/structuring-claude-code-for-multi-repo-workspaces/) — 多仓库Workspace方案设计，Bootstrap仓库模式
5. [Claude Code Best Practices](https://github.com/shanraisshan/claude-code-best-practice) — 社区维护的最佳实践合集，从vibe coding到工程化

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)