Claude Code调试排障与Git Worktree并行开发全实战

# 验证 Claude Code 版本
claude --version

# 验证 Git 版本（需要支持 worktree）
git --version

# 确认当前在 Git 仓库中
git status

❌ 糟糕的调试提示：
"我的应用报错了，帮我修一下"

✅ 高效的调试提示：
"我的Next.js应用在用户登录时报500错误。
具体错误信息：
[粘贴完整错误堆栈]

涉及的关键文件：
- src/app/api/auth/route.ts（API路由）
- src/lib/auth.ts（认证逻辑）
- src/middleware.ts（中间件）

复现步骤：
1. 访问 /login 页面
2. 输入有效邮箱和密码
3. 点击登录按钮
4. 控制台显示500错误

环境信息：Next.js 15.3, Node 20.x, PostgreSQL 16

请分析根因并给出修复方案。"

# Project: E-Commerce Platform

## Architecture
- Frontend: Next.js 15 App Router + Tailwind CSS
- Backend: Next.js API Routes + Prisma ORM
- Database: PostgreSQL 16
- Auth: NextAuth.js v5

## Key Paths
- API routes: src/app/api/
- Database schema: prisma/schema.prisma
- Auth config: src/lib/auth.config.ts
- Environment: .env.local (never commit!)

## Known Issues
- Session token expires after 1h (by design)
- Rate limiter may block legit traffic at high concurrency
- Image upload fails for files > 5MB

## Debugging Tips
- Run `npm run db:studio` for database inspection
- Check `logs/` directory for server-side logs
- Use `/compact` when context gets heavy during long debug sessions

# 在项目根目录运行
claude
> /init

flowchart TD
    A[收集错误信息] --> B[精准描述给Claude Code]
    B --> C[Claude分析根因]
    C --> D{修复方案是否明确?}
    D -->|是| E[应用修复]
    D -->|否| F[补充上下文<br/>添加日志/断点]
    F --> C
    E --> G[运行测试验证]
    G --> H{测试通过?}
    H -->|是| I[完成修复<br/>提交代码]
    H -->|否| J[反馈失败信息<br/>进入下一轮迭代]
    J --> C

    style A fill:#e1f5fe
    style C fill:#fff3e0
    style E fill:#e8f5e9
    style I fill:#c8e6c9

# 方法1：直接捕获运行时错误
npm run dev 2>&1 | tee debug-output.log

# 方法2：查看构建错误
npm run build 2>&1 | tail -50

# 方法3：查看测试失败详情
npm test -- --reporter=verbose 2>&1 | head -100

我在 [场景] 中遇到了 [错误类型] 错误。

错误信息：
[完整堆栈]

相关代码文件：
- [文件路径1]: [该文件的作用]
- [文件路径2]: [该文件的作用]

我已经尝试过的排查：
1. [操作1] → [结果1]
2. [操作2] → [结果2]

期望的正确行为：[描述]

# 引导深入分析
"请分析这个错误的根因，不要只看表面报错，追踪完整调用链"

# 引导查看特定文件
"请读取 src/lib/auth.ts 和 src/middleware.ts，分析它们之间的数据流"

# 引导对比分析
"项目中其他API路由是如何处理认证的？和这个报错的路由有什么区别？"

# 第一轮修复
"请给出修复方案，只修改必要的代码，不要重构不相关的部分"

# 如果修复引入新问题
"你的修复解决了原始报错，但引入了新问题：[描述新问题]。
请在保持修复的前提下，解决这个新问题。"

# 如果需要更多上下文
"请先在 src/lib/auth.ts 的第42行和第58行添加 console.log，
分别打印 token 值和 user 对象，我需要看到运行时的实际数据。"

# 运行测试
"请运行 npm test 验证修复是否正确，如果测试失败，分析失败原因"

# 检查副作用
"请检查这个修复是否可能影响其他模块，特别是 [相关模块名]"

# 代码审查
"/review"

# 启动Claude Code调试会话
claude

# 输入调试描述
> 我的订单创建API在高并发时返回504 Gateway Timeout。
> 
> 错误日志（从生产环境收集）：
> ```
> Error: 504 Gateway Timeout
>   at OrderService.createOrder (src/services/order.service.ts:87)
>   at async OrderController.store (src/controllers/order.controller.ts:45)
> PrismaClientInitializationError: Connection pool exhausted
>   at PrismaClient._execute (node_modules/.prisma/client/index.js:1234)
> ```
> 
> 涉及文件：
> - src/services/order.service.ts — 订单业务逻辑
> - src/controllers/order.controller.ts — API控制器
> - prisma/schema.prisma — 数据库模型
> - src/lib/prisma.ts — Prisma客户端实例
> 
> 并发量：约500 QPS
> 数据库：PostgreSQL 16 (RDS db.r6g.large)
> 连接池配置：默认Prisma配置

// 修复1：src/lib/prisma.ts — 调整连接池参数
import { PrismaClient } from '@prisma/client'

export const prisma = new PrismaClient({
  datasources: {
    db: {
      url: process.env.DATABASE_URL,
    },
  },
  // 关键修复：增大连接池
  // 公式：pool_size = num_connections = (CPU_cores * 2) + effective_spindle_count
  // db.r6g.large = 2 vCPU → 5 connections per instance
  // 4 instances → 20 connections minimum, set to 25 with buffer
})

// 修复2：在 prisma/schema.prisma 添加连接池配置
// datasource db {
//   provider  = "postgresql"
//   url       = env("DATABASE_URL")
//   relationMode = "prisma"
//   + connection_limit = 25
//   + pool_timeout = 10
// }

// 修复3：src/services/order.service.ts — 添加超时和重试
async createOrder(data: CreateOrderDto) {
  const maxRetries = 3
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await this.prisma.$transaction(
        async (tx) => {
          // ... 订单创建逻辑
        },
        {
          maxWait: 5000,   // 最大等待时间 5s
          timeout: 10000,  // 事务超时 10s
        }
      )
    } catch (error) {
      if (attempt === maxRetries) throw error
      await new Promise(r => setTimeout(r, 100 * attempt))
    }
  }
}

# 在压缩前，让Claude Code记住关键发现
> 在压缩上下文之前，请总结以下信息到你的记忆中：
> 1. 已确认的根因：Prisma连接池耗尽
> 2. 已应用的修复：连接池增大到25，添加事务超时
> 3. 待验证：负载测试下连接池表现
> 4. 关键文件：src/lib/prisma.ts, src/services/order.service.ts

> /compact

# 带自定义指令的压缩（推荐）
> /compact 请保留所有已确认的Bug信息和已应用的修复记录，可以丢弃探索过程中的中间代码片段

graph LR
    subgraph "传统串行开发"
        A1[任务1] --> A2[任务2] --> A3[任务3]
    end

    subgraph "Worktree并行开发"
        B1[Agent 1<br/>fix/auth-bug]
        B2[Agent 2<br/>feature/payment]
        B3[Agent 3<br/>refactor/api]
        B1 ~~~ B2 ~~~ B3
    end

    style B1 fill:#bbdefb
    style B2 fill:#c8e6c9
    style B3 fill:#fff9c4

my-project/                  ← 主工作目录 (main branch)
├── .git/                    ← Git仓库核心
├── .claude/                 ← Claude Code配置
│   └── worktrees/           ← Claude Code管理的Worktree
│       ├── fix-auth-bug/    ← Agent 1的工作目录
│       ├── feature-payment/ ← Agent 2的工作目录
│       └── refactor-api/    ← Agent 3的工作目录
├── src/
├── package.json
└── ...

# 方式A：启动Claude Code时指定worktree
claude --worktree fix-auth-bug

# 方式B：在会话中使用EnterWorktree工具
claude
> 请创建一个worktree来修复认证Bug
# Claude Code会调用内置的EnterWorktree工具自动处理

# 创建一个新的worktree
> 请在一个新的worktree中工作，名称为 fix-auth-bug

# Claude Code会自动：
# 1. 创建 .claude/worktrees/fix-auth-bug/ 目录
# 2. 创建对应的 git 分支 claude/fix-auth-bug
# 3. 切换工作目录到新的worktree
# 4. 加载项目配置（CLAUDE.md等）

# 完成工作后退出worktree
> 请退出worktree，保留修改

# 或者丢弃修改
> 请退出worktree并丢弃所有更改

# .worktreeinclude
src/lib/auth*
src/middleware*
src/app/api/auth/**
prisma/schema.prisma
package.json
tsconfig.json

# 步骤1：创建Worktree
git worktree add ../fix-auth-bug fix-auth-bug
# 输出: Preparing worktree (new branch 'fix-auth-bug')
# HEAD is now at abc1234 feat: initial commit

# 步骤2：在另一个终端中启动Claude Code
cd ../fix-auth-bug
claude

# 步骤3：同时在主目录启动另一个Claude Code
cd my-project
claude
# 两个Agent互不干扰地工作

# 步骤4：完成后合并
cd my-project
git merge fix-auth-bug

# 步骤5：清理Worktree
git worktree remove ../fix-auth-bug

# 终端1：主仓库，修复支付超时Bug
cd ~/projects/my-app
claude --worktree fix-payment-timeout

# 终端2：并行修复认证Bug
claude --worktree fix-auth-bug

# 终端3：在主分支上开发新功能
claude

> 我需要修复支付API超时的问题。
> 
> 错误日志：
> TimeoutError: Payment gateway request timed out after 30000ms
>   at PaymentService.processPayment (src/services/payment.service.ts:156)
> 
> 请分析根因并修复。修复范围限制在 src/services/payment.service.ts 和 src/config/payment.ts。

> 我需要修复JWT Token刷新失败的问题。
> 
> 错误日志：
> JsonWebTokenError: jwt expired
>   at AuthService.refreshToken (src/services/auth.service.ts:89)
> 
> 请分析根因并修复。修复范围限制在 src/services/auth.service.ts 和 src/middleware.ts。

# 查看所有Worktree状态
git worktree list

# 尝试合并第一个分支
git merge fix-payment-timeout

# 如果有冲突，让Claude Code帮助解决
claude
> 合并 fix-payment-timeout 分支时出现冲突，请帮我解决：
> 
> 冲突文件：src/config/constants.ts
> 
> 请读取冲突文件，分析两个分支的修改意图，生成保留两方修改的合并结果。

# 查看所有活跃的Worktree
git worktree list

# 清理已合并的Worktree
git worktree prune

# 删除特定Worktree
git worktree remove .claude/worktrees/fix-auth-bug

# 强制删除（有未提交更改时）
git worktree remove --force .claude/worktrees/fix-auth-bug

> /review

# Claude Code会分析当前diff，检查：
# 1. 是否引入新的Bug
# 2. 是否有性能问题
# 3. 是否符合项目编码规范
# 4. 是否有安全隐患

# TypeScript编译错误 — 收集完整类型链
npx tsc --noEmit 2>&1 | head -50

# 运行时错误 — 带source map的堆栈
NODE_OPTIONS='--enable-source-maps' npm start

# 测试失败 — 详细输出
npm test -- --verbose 2>&1 | tee test-failure.log

# 数据库错误 — 启用Prisma查询日志
# 在 src/lib/prisma.ts 中设置 log: ['query', 'error', 'warn']

# 网络请求错误 — 抓取请求/响应
# Claude Code可以帮你添加请求拦截器日志

# 第一步：让Claude Code创建最小复现
> 请根据这个错误，创建一个最小复现脚本 test-bug.ts，
> 只包含触发错误所需的最少代码

# 第二步：运行最小复现
> 请运行 npx tsx test-bug.ts 并分析输出

# 第三步：逐步添加复杂度
> 现在请把中间件逻辑加回去，看是否还报错

# 第四步：确认修复有效
> 请运行完整测试套件确认修复没有引入回归

# 让Claude Code追踪完整调用链
> 这个错误的完整调用链是什么？请从入口点开始，列出每一层调用，
> 标注每层的文件路径和行号，直到到达出错位置

# Claude Code输出示例：
# 调用链分析：
# 1. src/app/api/orders/route.ts:23     → POST handler 接收请求
# 2. src/controllers/order.controller.ts:45 → OrderController.store()
# 3. src/services/order.service.ts:67   → OrderService.createOrder()
# 4. src/lib/prisma.ts:15               → prisma.$transaction() ← 连接池耗尽
# 5. node_modules/.prisma/client:1234   → PrismaClient初始化错误

> 请记住以下调试经验：
> - 项目使用Prisma ORM，默认连接池不够支撑高并发
> - 修复方案：在schema.prisma中设置connection_limit=25和pool_timeout=10
> - 相关文件：src/lib/prisma.ts, prisma/schema.prisma
> - 参考文档：https://www.prisma.io/docs/guides/performance-and-optimization/connection-management

sequenceDiagram
    participant Dev as 开发者
    participant W1 as Worktree 1<br/>BUG-101
    participant W2 as Worktree 2<br/>BUG-102
    participant W3 as Worktree 3<br/>BUG-103
    participant Main as 主分支

    Dev->>W1: 启动 claude --worktree fix-email
    Dev->>W2: 启动 claude --worktree fix-pagination
    Dev->>W3: 启动 claude --worktree fix-dashboard

    Note over W1: 分析邮件服务配置<br/>发现SMTP端口错误
    Note over W2: 分析分页逻辑<br/>发现offset计算错误
    Note over W3: 分析查询性能<br/>发现N+1查询问题

    W1->>W1: 修复SMTP配置 + 添加重试
    W2->>W2: 修复offset = (page-1)*limit
    W3->>W3: 添加eager loading + 缓存

    W1->>W1: 运行邮件服务测试 ✅
    W2->>W2: 运行分页测试 ✅
    W3->>W3: 运行性能测试 ✅

    W1->>Main: git merge fix-email
    W2->>Main: git merge fix-pagination
    W3->>Main: git merge fix-dashboard

    Main->>Main: 运行完整测试套件 ✅
    Note over Main: 三个Bug全部修复<br/>并行节省 60% 时间

# 窗口1：修复邮件服务
cd ~/projects/my-fullstack-app
claude --worktree fix-email-verification

# 在Claude Code中输入：
> Bug描述：用户注册后收不到验证邮件。
> 
> 环境信息：
> - 邮件服务：Nodemailer + SMTP (Gmail)
> - 配置文件：src/config/email.config.ts
> - 服务文件：src/services/email.service.ts
> - 调用方：src/services/auth.service.ts 的 registerUser 方法
> 
> 测试账号已配置，.env.local中包含：
> SMTP_HOST=smtp.gmail.com
> SMTP_PORT=465
> SMTP_USER=[email protected]
> SMTP_PASS=[app-specific-password]
> 
> 请分析为什么邮件发不出去。

# 窗口2：修复分页
cd ~/projects/my-fullstack-app
claude --worktree fix-pagination

# 在Claude Code中输入：
> Bug描述：商品列表API的第二页返回空数据。
> 
> API端点：GET /api/products?page=2&limit=20
> 实际返回：{ data: [], total: 150, page: 2 }
> 
> 期望返回：第21-40条商品数据
> 
> 相关文件：
> - src/services/product.service.ts — listProducts 方法
> - src/controllers/product.controller.ts — 处理分页参数
> 
> 数据库有150条商品数据，数据库是PostgreSQL。
> 请分析分页逻辑的错误。

# 窗口3：修复Dashboard性能
cd ~/projects/my-fullstack-app
claude --worktree fix-dashboard-perf

# 在Claude Code中输入：
> Bug描述：管理后台Dashboard页面加载时间超过10秒。
> 
> 页面路径：src/app/admin/dashboard/page.tsx
> 数据获取：页面使用多个并行的Prisma查询
> 数据量：约5000条订单、2000条用户、500条商品
> 
> 请分析性能瓶颈，特别是检查是否存在N+1查询问题，
> 并给出优化方案。优化目标：页面加载时间降到2秒以内。

// src/services/email.service.ts — 问题代码
const transporter = nodemailer.createTransport({
  host: config.smtp.host,
  port: config.smtp.port,  // ← 这里读的是 587 (STARTTLS)
  secure: false,           // ← 但Gmail SMTP 465需要 secure: true
  auth: {
    user: config.smtp.user,
    pass: config.smtp.pass,
  },
})

// 修复方案
const transporter = nodemailer.createTransport({
  host: config.smtp.host,
  port: 465,
  secure: true,  // ← 修复：465端口必须用SSL
  auth: {
    user: config.smtp.user,
    pass: config.smtp.pass,
  },
  // 增强可靠性：添加连接超时和重试
  connectionTimeout: 10000,
  greetingTimeout: 10000,
  socketTimeout: 15000,
})

// src/services/product.service.ts — 问题代码
async listProducts(page: number, limit: number) {
  const skip = page * limit  // ← BUG: page=2时 skip=40，跳过了第21-40条
  const products = await this.prisma.product.findMany({
    skip,
    take: limit,
  })
  return products
}

// 修复方案
async listProducts(page: number, limit: number) {
  const skip = (page - 1) * limit  // ← 修复：page=2时 skip=20，正确跳过第一页
  const products = await this.prisma.product.findMany({
    skip,
    take: limit,
    orderBy: { createdAt: 'desc' },
  })
  return products
}

// src/app/admin/dashboard/page.tsx — 问题代码
// N+1查询：先获取所有订单，然后循环查询每条订单的用户信息
const orders = await prisma.order.findMany({ take: 100 })
for (const order of orders) {
  order.user = await prisma.user.findUnique({
    where: { id: order.userId }  // ← 100次额外查询！
  })
  order.items = await prisma.orderItem.findMany({
    where: { orderId: order.id }  // ← 又100次！
  })
}

// 修复方案：使用 include 一次性获取关联数据
const orders = await prisma.order.findMany({
  take: 100,
  orderBy: { createdAt: 'desc' },
  include: {
    user: {
      select: { id: true, name: true, email: true }  // 只选需要的字段
    },
    items: {
      include: {
        product: {
          select: { id: true, name: true, price: true }
        }
      }
    }
  }
})
// 从 201 次查询 → 1 次查询，性能提升约 200 倍

# 回到主分支
cd ~/projects/my-fullstack-app
git checkout main

# 按优先级合并（P1先合并）
git merge fix-email-verification
git merge fix-pagination
git merge fix-dashboard-perf

# 最终验证：让Claude Code运行完整测试
claude
> 请运行完整的测试套件，确认所有修复没有引入回归。
> 特别验证：
> 1. 邮件发送测试是否通过
> 2. 分页查询第二页是否有数据
> 3. Dashboard页面查询性能是否改善

# 清理已合并的Worktree
git worktree remove .claude/worktrees/fix-email-verification
git worktree remove .claude/worktrees/fix-pagination
git worktree remove .claude/worktrees/fix-dashboard-perf

# 删除已合并的分支
git branch -d fix-email-verification fix-pagination fix-dashboard-perf

# 或者一键清理所有已合并的Worktree
git worktree prune

# 会话管理
/compact          # 压缩上下文，释放token空间
/compact [指令]   # 带保留指令的压缩
/clear            # 清空会话，从头开始
/context          # 查看当前上下文状态
/model            # 切换模型（Opus/Sonnet/Haiku）

# 调试相关
/review           # 审查当前代码变更
/init             # 初始化项目配置
/vim              # 切换Vim编辑模式

# Worktree操作
# 通过 --worktree 标志或在会话中请求创建
claude --worktree <name>     # 启动Worktree会话
git worktree list            # 查看所有Worktree
git worktree prune           # 清理无效Worktree

# 错误：fatal: 'fix-auth-bug' already exists
# 解决：先清理旧的Worktree
git worktree list
git worktree remove .claude/worktrees/fix-auth-bug
# 或者强制删除
git worktree remove --force .claude/worktrees/fix-auth-bug

# 解决：利用记忆系统持久化关键发现
> 请将以下调试发现保存到记忆中：
> - 根因分析：[描述]
> - 修复方案：[描述]
> - 已修改文件：[列表]

# 然后安全地压缩
> /compact

# 压缩后记忆中的信息仍然可用

# 每个Worktree需要独立的node_modules
cd .claude/worktrees/fix-auth-bug
npm install

# 如果磁盘空间紧张，使用符号链接共享依赖
ln -s ../../node_modules node_modules  # 仅在确认无冲突时使用

# 预防：明确限制修改范围
> 请只修改以下文件来修复这个Bug：
> - src/services/auth.service.ts
> - src/config/auth.config.ts
> 不要修改任何其他文件。

# 恢复：如果已经误改
> 请撤销对 src/lib/utils.ts 的修改，使用 git checkout 恢复它

# 方式1：共享文件（在主分支上）
echo "Agent1: 已确认auth Bug根因是JWT过期" > .claude/debug-notes.md

# 方式2：使用Git commit信息
git commit -m "WIP: auth bug - found root cause in token refresh logic"

# 方式3：利用CLAUDE.md传递信息（主分支修改会反映到所有Worktree）

flowchart TB
    subgraph "调试准备"
        A[收集错误信息] --> B[编写CLAUDE.md]
        B --> C[准备精准提示词]
    end

    subgraph "并行调试（Worktree模式）"
        C --> D{Bug数量?}
        D -->|单个| E[直接在主分支调试]
        D -->|多个且独立| F[创建多个Worktree]
        F --> F1[Worktree 1: Bug A]
        F --> F2[Worktree 2: Bug B]
        F --> F3[Worktree 3: Bug C]
    end

    subgraph "调试循环"
        E --> G[结构化描述Bug]
        F1 --> G
        F2 --> G
        F3 --> G
        G --> H[Claude分析根因]
        H --> I[应用修复]
        I --> J[运行测试]
        J --> K{通过?}
        K -->|否| L[反馈失败 → 返回H]
        K -->|是| M[/review 审查]
    end

    subgraph "合并与收尾"
        M --> N[合并到主分支]
        N --> O[运行完整测试]
        O --> P[保存调试记忆]
        P --> Q[清理Worktree]
    end

    style F fill:#e3f2fd
    style G fill:#fff3e0
    style M fill:#e8f5e9