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

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配置
└── ...

# 项目概览
这是一个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

# 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，不要在页面组件中嵌套路由

# 组件开发规范

## 设计系统
- 颜色变量定义在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. 克隆仓库时直接启用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

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

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

# 创建一个工作脚本: 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

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

# 2. 克隆所有相关仓库
git clone [email protected]:org/frontend-app.git
git clone [email protected]:org/backend-api.git
git clone [email protected]:org/shared-types.git
git clone [email protected]:org/infra-config.git

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

# 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/中的环境变量映射

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

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

{
  "workspace": "my-product",
  "repos": [
    {
      "name": "frontend-app",
      "url": "[email protected]:org/frontend-app.git",
      "branch": "main",
      "path": "frontend-app"
    },
    {
      "name": "backend-api",
      "url": "[email protected]:org/backend-api.git",
      "branch": "develop",
      "path": "backend-api"
    },
    {
      "name": "shared-types",
      "url": "[email protected]: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"}
  ]
}

#!/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初始化完成"

# 安装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 [email protected]:org/frontend-app.git
npx @anthropic/workspaces add backend-api [email protected]:org/backend-api.git

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

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

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

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

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

// 20行示例代码

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

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

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

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

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

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

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

// .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*)"
    ]
  }
}

# 启用沙箱模式，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"]
    }
  }
}

# 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"]

# 使用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

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

# 步骤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"

请先阅读 @packages/backend/CLAUDE.md 了解后端架构规范，然后实现收藏API

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

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

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

# 终端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测试已包含"

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

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

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

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

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.md总大小
find . -name "CLAUDE.md" -exec wc -c {} + | sort -n

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