Claude Code Monorepo七大治理策略实战

monorepo/
├── CLAUDE.md              ← 第1层：全局规则（~500 token）
├── .claude/
│   └── settings.json      ← 全局工具权限
├── packages/
│   ├── shared-ui/
│   │   └── CLAUDE.md      ← 第2层：包级规则（~300 token）
│   ├── api-server/
│   │   └── CLAUDE.md      ← 第2层
│   └── admin-web/
│       ├── CLAUDE.md      ← 第2层
│       └── src/
│           └── dashboard/
│               └── CLAUDE.md  ← 第3层：模块级（~200 token）

# 项目架构

Monorepo结构，pnpm workspace管理。

## 技术栈
- Runtime: Node.js 20 + TypeScript 5.4
- 前端: React 18 + Vite + TailwindCSS
- 后端: Fastify + Prisma + PostgreSQL
- 共享: @mono/shared-ui (组件库), @mono/types (类型定义)

## 架构规则
1. packages/shared-ui 的组件禁止引入任何后端依赖
2. 所有API路由必须定义在 @mono/types 的 schema 中
3. 数据库变更必须生成 Prisma migration，禁止手动SQL
4. 测试文件与源文件同目录，命名为 *.test.ts

## 禁止事项
- 禁止在 api-server 中直接引用 admin-web 的代码
- 禁止使用 any 类型
- 禁止跳过 ESLint 规则（不允许 eslint-disable）

# packages/api-server/CLAUDE.md

## 本包说明
Fastify HTTP API服务。入口 src/index.ts，路由在 src/routes/。

## 关键约定
- 路由文件按 RESTful 资源命名：users.ts, orders.ts
- 每个 route handler 必须包含 Zod schema 验证
- 错误处理统一使用 src/errors/ 下的自定义错误类
- 数据库操作只在 src/services/ 层，路由层禁止直接调用 PrismaClient

## 常用命令
- `pnpm --filter api-server dev` — 启动开发服务器
- `pnpm --filter api-server test` — 运行测试
- `pnpm --filter api-server prisma:migrate` — 数据库迁移

## 依赖关系
- 依赖 @mono/types（API schema）
- 依赖 @mono/shared-logger（日志工具）
- 被依赖：无（API是终端节点）

# packages/api-server/src/auth/CLAUDE.md

## 认证模块
JWT + Refresh Token双令牌方案。

## 关键文件
- jwt.ts — 签发和验证逻辑
- guards.ts — Fastify认证守卫
- strategies/ — OAuth provider策略

## 规则
- Token过期时间：access 15min, refresh 7d
- Refresh Token必须存入Redis，登出时主动删除
- 密码使用 bcrypt (cost=12) 存储

┌─────────────────────────────────────────┐
│            Git Main Branch              │
│         monorepo (所有代码)              │
└──────────┬──────────┬───────────────────┘
           │          │
    ┌──────▼──┐  ┌───▼────────┐
    │worktree1│  │ worktree2  │
    │api-server│  │ admin-web  │
    │ 修改路由  │  │ 重构组件   │
    └──────┬──┘  └───┬────────┘
           │          │
    ┌──────▼──────────▼────────┐
    │     合并回 Main           │
    │  (主会话处理冲突)          │
    └──────────────────────────┘

# 1. 为api-server创建独立worktree
git worktree add .claude/worktrees/feat-api-v2 -b feat/api-v2

# 2. 启动Claude Code，在worktree中工作
cd .claude/worktrees/feat-api-v2
claude

# 3. 在Claude Code中指定只操作api-server
> 只修改 packages/api-server/ 下的文件。参考 CLAUDE.md 中的路由约定。

> 使用Task工具并行完成以下任务：
> 1. 在 packages/shared-ui 中，给所有组件添加 displayName
> 2. 在 packages/api-server 中，给所有路由添加 OpenAPI注释
> 3. 在 packages/admin-web 中，把所有 className 硬编码替换为 TailwindCSS 变量
>
> 每个任务使用独立的子Agent，避免上下文交叉。

# 查看所有worktree
git worktree list

# 清理已合并的worktree
git worktree prune

总上下文 = 系统提示(~3K) + CLAUDE.md加载(~1K) 
         + 对话历史(递增) + 文件读取(按需) + 工具输出(按需)

# ❌ 错误：让Claude Code扫描整个Monorepo
> 找出所有需要修改的文件

# ✅ 正确：先缩小范围再操作
> 在 packages/api-server/src/routes/ 目录下，找出所有缺少错误处理的路由

# ✅ 先用Glob定位文件列表（Token消耗极低）
> 列出 packages/shared-ui/src/components/ 下所有 .tsx 文件

# 然后只读取需要修改的文件
> 读取 Button.tsx 和 Modal.tsx，给它们添加 aria-label 属性

# 阶段1：规划（不读取文件）
> 列出重构 packages/api-server 的认证模块需要的步骤，只列步骤不执行

# 阶段2：确认后执行
> 按你列出的步骤执行前3步

# 阶段3：验证
> 运行测试验证修改

> /compact

# Step 1: 先修改共享的日志工具
> 在 packages/shared-logger/src/ 中添加 requestLogger 函数。
> 接口：(req: FastifyRequest) => void
> 输出格式：[${timestamp}] ${method} ${url} - ${statusCode}

# Step 2: 提交共享工具
git add packages/shared-logger/
git commit -m "feat(logger): add requestLogger for API routes"

# Step 3: 修改路由文件
> 在 packages/api-server/src/routes/ 的每个路由文件中，
> 引入 requestLogger 并添加 onRequest 钩子。
> 每修改一个路由文件就告诉我，我来确认。

# Step 4: 逐文件提交
git add packages/api-server/src/routes/users.ts
git commit -m "feat(api): add request logging to users route"
# ... 重复每个路由文件

# 限制Agent只做3轮操作，避免一次改太多
claude -p --max-turns 3 "给 packages/api-server/src/routes/users.ts 添加请求日志"

# 查看最近的修改
git diff HEAD~1

# 如果整个提交需要回退
git revert HEAD

# 如果只需要回退某些文件
git checkout HEAD~1 -- packages/api-server/src/routes/users.ts

{
  "permissions": {
    "allow": [],
    "deny": ["Bash(rm -rf*)"]
  }
}

## packages/api-server/CLAUDE.md

## 依赖关系图（必须遵守）

@mono/api-server
  ├── @mono/types（API schema定义）
  ├── @mono/shared-logger（日志）
  ├── @mono/auth-lib（认证工具）
  └── @mono/db-client（数据库客户端）

## 依赖规则
1. 本包是终端节点，不对外暴露
2. 只能依赖 @mono/* 的包，不能直接引用其他包的源码
3. 如果 @mono/types 中的 schema 需要变更，先提 PR 到 types 包

# .claude/commands/verify-deps.md
验证当前修改是否违反了 CLAUDE.md 中声明的依赖规则。

检查步骤：
1. 读取 git diff --name-only 获取修改的文件列表
2. 对每个修改的文件，检查其 import 语句
3. 如果发现跨包直接引用（未通过 workspace 包名引用），报告违规
4. 如果发现依赖了未在 CLAUDE.md 中声明的包，报告违规

> /project:verify-deps

# 安装madge
pnpm add -Dw madge

# 检测循环依赖
npx madge --circular packages/

# 在CI中加入检查
npx madge --circular --warning packages/ || exit 1

flowchart TD
    A[Step 1: 修改共享层] --> B[提交变更]
    B --> C[Step 2: 逐包修复编译错误]
    C --> D{还有编译错误?}
    D -->|是| E[修复下一个包]
    E --> D
    D -->|否| F[Step 3: 运行全量测试]
    F --> G{测试通过?}
    G -->|是| H[合并]
    G -->|否| I[修复测试]
    I --> F

// packages/types/src/user.ts
// 重命名时保留旧名称作为别名

export interface Account {
  id: string;
  email: string;
  name: string;
}

/** @deprecated 使用 Account 替代 */
export type User = Account;

git add packages/types/
git commit -m "feat(types): rename User to Account, keep User alias"

# 使用-p模式逐包处理
for pkg in api-server admin-web worker; do
  claude -p --max-turns 5 \
    "将 packages/$pkg 中所有对 User 类型的引用改为 Account。
     不要修改 packages/types/ 下的文件。
     修改完后运行 pnpm --filter $pkg typecheck 验证。"
done

# 删除废弃别名
claude -p --max-turns 3 \
  "删除 packages/types/src/user.ts 中的 User 别名导出。
   然后运行 pnpm -r typecheck 和 pnpm -r test 验证。"

// packages/api-server/tsconfig.json
{
  "references": [
    { "path": "../types" },
    { "path": "../shared-logger" }
  ]
}

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash .claude/hooks/quality-check.sh \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/quality-check.sh
FILE="$1"

# 1. 检查是否误改了其他包的文件
CURRENT_PKG=$(echo "$FILE" | grep -oP 'packages/[^/]+')
ALLOWED_PKGS=$(cat .claude/current-work-package 2>/dev/null)

if [ -n "$ALLOWED_PKGS" ] && [ "$CURRENT_PKG" != "$ALLOWED_PKGS" ]; then
  echo "⚠️  警告：正在修改 $CURRENT_PKG，但当前工作范围是 $ALLOWED_PKGS"
fi

# 2. 检查是否引入了 console.log
if grep -q "console\.log" "$FILE" 2>/dev/null; then
  echo "⚠️  发现 console.log，请使用 @mono/shared-logger 替代"
fi

# 3. 检查是否有未处理的 TODO
if grep -q "TODO\|FIXME\|HACK" "$FILE" 2>/dev/null; then
  echo "ℹ️  文件包含 TODO/FIXME/HACK 标记"
fi

# .github/workflows/ai-review.yml
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed packages
        id: packages
        run: |
          CHANGED=$(git diff --name-only origin/main...HEAD | \
            grep -oP 'packages/[^/]+' | sort -u)
          echo "list=$CHANGED" >> $GITHUB_OUTPUT

      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          for pkg in ${{ steps.packages.outputs.list }}; do
            # 只审查变更的文件
            FILES=$(git diff --name-only origin/main...HEAD -- "$pkg/")
            claude -p --max-turns 3 \
              --output-format json \
              "审查以下文件的变更，重点关注：
              1. 是否违反了 $pkg/CLAUDE.md 中的规则
              2. 是否有跨包违规引用
              3. 是否缺少错误处理
              文件列表：$FILES
              使用 git diff origin/main...HEAD -- $FILES 查看具体变更。"
          done

## 提交前检查清单

每次修改代码后，自动执行以下检查：
- [ ] `pnpm -r typecheck` — 类型检查通过
- [ ] `pnpm -r lint` — ESLint检查通过
- [ ] `pnpm -r test` — 所有测试通过
- [ ] 无跨包违规引用
- [ ] 新代码有对应的测试
- [ ] 无 console.log 或 debugger 残留

i18n-monorepo/
├── CLAUDE.md
├── pnpm-workspace.yaml
├── packages/
│   ├── shared-ui/       # React组件库
│   ├── api-server/      # Fastify API
│   ├── admin-web/       # 管理后台
│   └── types/           # 共享类型

> 列出为这个Monorepo添加i18n支持需要的步骤。
> 不要执行任何修改，只输出步骤列表。
> 考虑以下方面：翻译文件结构、运行时切换、组件适配、API错误消息。

1. 在 packages/types 中定义 I18nLocale 类型和翻译 key 的 schema
2. 创建 packages/shared-i18n 包（翻译加载器 + React hook）
3. 在 packages/shared-ui 中适配组件，接受 i18n props
4. 在 packages/api-server 中实现错误消息的国际化
5. 在 packages/admin-web 中添加语言切换 UI

# 先修改 types 包
cd packages/types
claude

> 在 src/ 中创建 i18n.ts，定义以下类型：
> - Locale: 'zh' | 'en'
> - TranslationKey: 所有翻译 key 的联合类型
> - TranslationDict: Record<Locale, Record<TranslationKey, string>>
> 参考本包 CLAUDE.md 的类型导出规范。

git add packages/types/src/i18n.ts
git commit -m "feat(types): add i18n type definitions"

# 创建 shared-i18n 包
cd ../..
mkdir -p packages/shared-i18n/src

# packages/shared-i18n/CLAUDE.md

## 本包说明
国际化运行时工具包。提供翻译加载、语言切换、React Hook。

## 关键约定
- 翻译文件放在 src/locales/，按语言命名：zh.ts, en.ts
- 使用 @mono/types 中定义的 TranslationKey 类型确保 key 一致
- 导出 useTranslation React Hook
- 导出 I18nProvider React Context Provider

## 依赖
- @mono/types（类型定义）
- react（peer dependency）

## 被依赖
- @mono/shared-ui
- @mono/admin-web

> 根据 CLAUDE.md 的描述，实现这个 i18n 包的完整代码。
> 包含：翻译加载器、I18nProvider、useTranslation hook、
> zh.ts 和 en.ts 两个语言文件（先放空壳翻译）。

# 终端1：适配 shared-ui 组件
cd packages/shared-ui
claude

> 将 src/ 下的所有组件中的硬编码中文文案替换为 useTranslation() 调用。
> 例如 "确定" → t('common.confirm')
> 不要修改组件的 props 接口，只替换文案。
> 每修改完一个组件就运行 pnpm --filter shared-ui typecheck 验证。

# 终端2：适配 api-server
cd packages/api-server
claude

> 修改错误处理，将硬编码的错误消息改为支持 i18n。
> 在 src/errors/ 下创建 I18nError 类，接受 TranslationKey 而非固定字符串。
> 修改中间件，根据请求头 Accept-Language 决定错误消息语言。

> 执行提交前检查清单：
> 1. 运行 pnpm -r typecheck
> 2. 运行 pnpm -r lint
> 3. 运行 pnpm -r test
> 4. 检查是否有跨包违规引用
> 5. 确认所有新代码都有测试
> 报告每项的结果。

flowchart TB
    subgraph "阶段1: 规划"
        A[读取CLAUDE.md] --> B[输出步骤列表]
        B --> C[用户确认]
    end

    subgraph "阶段2: 共享层"
        C --> D[修改 @mono/types]
        D --> E[创建 @mono/shared-i18n]
        E --> F[提交共享层变更]
    end

    subgraph "阶段3: 并行适配"
        F --> G[子Agent: 适配 shared-ui]
        F --> H[子Agent: 适配 api-server]
        F --> I[子Agent: 适配 admin-web]
    end

    subgraph "阶段4: 集成验证"
        G --> J[类型检查]
        H --> J
        I --> J
        J --> K[全量测试]
        K --> L[代码审查]
        L --> M[合并]
    end

    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style J fill:#fff3e0
    style M fill:#c8e6c9