核心思路​

PR 提交
  → GitHub Actions 触发
    → Claude Code（Headless 模式）分析 diff
      → 输出审查报告
        → 自动发布为 PR 评论

Claude Code 的 -p 参数（Headless 模式）是实现这一流程的关键——它让 Claude Code 脱离交互界面，以命令行工具的形式在 CI 环境中运行。

快速接入：5 分钟配置​

第 1 步：添加 API Key 到 GitHub Secrets​

在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加：

ANTHROPIC_API_KEY = sk-ant-xxxxxxxxxxxxxxxx

第 2 步：创建工作流文件​

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - 'src/**'
      - 'tests/**'

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: 安装 Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: 生成 PR Diff
        id: diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD \
            -- '*.ts' '*.tsx' '*.js' '*.py' \
            > /tmp/pr-diff.txt
          echo "lines=$(wc -l < /tmp/pr-diff.txt)" >> $GITHUB_OUTPUT

      - name: Claude 代码审查
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          REVIEW=$(cat /tmp/pr-diff.txt | claude -p "
          请对以下代码变更进行专业审查，用中文输出，格式如下：

          ## 总体评价
          [简短总结，说明本次变更的质量]

          ## 发现的问题
          [列出 Bug、安全漏洞、性能问题，标注严重程度]

          ## 改进建议
          [具体可操作的优化建议]

          ## 值得肯定的地方
          [优秀的实践值得表扬]
          " --dangerously-skip-permissions 2>/dev/null)

          {
            echo 'REVIEW<<REVIEW_EOF'
            echo "$REVIEW"
            echo 'REVIEW_EOF'
          } >> $GITHUB_ENV

      - name: 发布 PR 评论
        uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const review = process.env.REVIEW;
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Claude Code 自动审查\n\n${review}\n\n---\n*审查范围：${{ steps.diff.outputs.lines }} 行变更 · ${new Date().toISOString()}*`
            });

进阶配置​

安全门禁：检测高危问题自动拦截​

在工作流中添加安全检查步骤，发现高危问题时阻止 PR 合并：

      - name: 安全扫描（高危问题自动拦截）
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          SECURITY_RESULT=$(cat /tmp/pr-diff.txt | claude -p "
          专注于安全角度审查以下代码变更：
          1. SQL 注入
          2. XSS 漏洞
          3. 硬编码密钥或密码
          4. 权限控制缺失
          5. 不安全的反序列化

          如果发现任何高危漏洞，在输出开头加上 [SECURITY_BLOCK]
          " --dangerously-skip-permissions 2>/dev/null)

          if echo "$SECURITY_RESULT" | grep -q "\[SECURITY_BLOCK\]"; then
            echo "❌ 检测到高危安全漏洞，PR 被拦截"
            echo "$SECURITY_RESULT"
            exit 1  # 非零退出码使 CI 失败
          fi
          echo "✅ 安全检查通过"

在 Branch Protection Rules 中将此 Job 设为 Required Status Check，PR 有高危漏洞时无法合并。

结构化 JSON 输出（便于解析）​

对于需要进一步处理审查结果的场景，使用 --output-format stream-json：

      - name: 结构化审查（供其他工具消费）
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          cat /tmp/pr-diff.txt | claude -p "
          审查代码，输出 JSON 格式：
          {
            \"score\": 1-10,
            \"issues\": [{\"severity\": \"high|medium|low\", \"file\": \"...\", \"description\": \"...\"}],
            \"summary\": \"...\"
          }
          只输出 JSON，不要其他内容
          " --dangerously-skip-permissions \
            --output-format stream-json | \
          jq -r 'select(.type=="text") | .content' > /tmp/review.json

          # 可以进一步处理 JSON，例如创建 GitHub Check 注释
          cat /tmp/review.json

增量审查（只审查新变更）​

避免每次审查整个 PR，只审查新增的提交：

      - name: 增量 Diff（只看新提交）
        run: |
          # 获取最新 commit 的变更，而非整个 PR 的 diff
          git diff HEAD~1...HEAD \
            -- '*.ts' '*.py' \
            > /tmp/incremental-diff.txt

GitLab CI 接入​

claude-review:
  stage: test
  image: node:20-alpine
  only:
    - merge_requests
  script:
    - npm install -g @anthropic-ai/claude-code
    - git diff $CI_MERGE_REQUEST_DIFF_BASE_SHA...HEAD > /tmp/diff.txt
    - |
      cat /tmp/diff.txt | claude -p "进行代码审查，用中文输出 Markdown 格式报告" \
        --dangerously-skip-permissions > review.md
    - cat review.md
  artifacts:
    paths:
      - review.md
    expire_in: 1 week
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY  # 在 GitLab CI/CD Variables 中配置

实际效果​

发布到 PR 的审查评论示例：

## 🤖 Claude Code 自动审查

## 总体评价
本次 PR 实现了 JWT 刷新机制，整体逻辑清晰，但存在一个中等风险的安全问题需要处理。

## 发现的问题
**[Medium] 安全** `src/auth/AuthService.ts:89`
JWT 验证时未检查 `exp`（过期时间）字段，过期的 token 可能仍被接受。
建议：在第 89 行添加 `if (payload.exp < Date.now() / 1000) throw new Error('Token expired')`

**[Low] 质量** `src/auth/routes.ts:45`
`refreshToken` 函数返回 `any` 类型，影响类型安全。

## 改进建议
1. 添加 token 过期检查（必须）
2. 将 refreshToken 返回类型改为 `Promise<TokenPair>`
3. 考虑将刷新逻辑提取为 `TokenRefreshService`，降低 AuthService 的职责

## 值得肯定的地方
- 刷新逻辑与认证逻辑分离得很好
- 错误处理覆盖了主要边界情况
- 测试覆盖了 happy path 和异常情况

---
*审查范围：147 行变更 · 2025-02-18T14:30:00Z*

关键参数说明​

执行流程​

第 1 步：扫描需要补测试的文件​

扫描 src/services/ 目录，找出所有没有对应测试文件的源码文件，
列出它们的函数数量和代码行数，按"函数数量多"到"函数数量少"排序

Claude Code 分析后输出：

找到以下文件缺少测试覆盖：

文件                              行数    函数数    优先级
src/services/OrderService.ts      342     18       🔴 高
src/services/PaymentService.ts    289     14       🔴 高
src/services/UserService.ts       156     9        🟡 中
src/services/NotificationService  98      5        🟢 低

建议从 OrderService.ts 开始，它是核心业务逻辑且函数最多。

第 2 步：触发自动测试生成​

使用 test-writer agent 为 src/services/OrderService.ts 生成完整测试，
要求单元测试覆盖率达到 85% 以上，所有测试必须通过才算完成

第 3 步：Agent 自动运行（自修复循环）​

Agent 自动执行以下循环：

[循环 1]
✓ 读取 OrderService.ts（342 行，18 个公共方法）
✓ 检测到使用 Jest 测试框架
✓ 生成初始测试文件：__tests__/OrderService.test.ts（89 个测试用例）
✗ 运行测试：12 个失败

失败原因分析：
- createOrder 测试：Mock 的 database.save 返回值格式不对
- calculateDiscount 测试：边界值计算有误
- cancelOrder 测试：缺少对 status 字段的 Mock

[自动修复中...]
✓ 修正 Mock 返回值格式
✓ 修正边界值计算（0.00 → 0）
✓ 添加 status 字段 Mock

[循环 2]
✗ 运行测试：3 个失败（原有 12 个减少到 3 个）

失败原因分析：
- sendNotification 在 cancelOrder 中被调用，但 Mock 未配置

[自动修复中...]
✓ 在测试前添加 jest.spyOn(NotificationService, 'send').mockResolvedValue(undefined)

[循环 3]
✓ 运行测试：89/89 全部通过 ✅

覆盖率报告：
- 语句覆盖率：92.3%
- 分支覆盖率：87.6%
- 函数覆盖率：100%
- 行覆盖率：91.8%

✅ 目标达成（要求 85%，实际 92.3%）

实际生成的测试示例​

以下是 Agent 为 OrderService.createOrder 生成的测试：

// __tests__/services/OrderService.test.ts（由 Claude Code 自动生成）

import { OrderService } from '../../src/services/OrderService';
import { Database } from '../../src/db/Database';
import { NotificationService } from '../../src/services/NotificationService';
import { OrderStatus, PaymentMethod } from '../../src/types/order';

jest.mock('../../src/db/Database');
jest.mock('../../src/services/NotificationService');

const MockedDatabase = Database as jest.MockedClass<typeof Database>;

describe('OrderService', () => {
  let orderService: OrderService;
  let mockDb: jest.Mocked<Database>;

  beforeEach(() => {
    jest.clearAllMocks();
    mockDb = new MockedDatabase() as jest.Mocked<Database>;
    orderService = new OrderService(mockDb);
  });

  describe('createOrder', () => {
    const validOrderData = {
      userId: 'user-123',
      items: [{ productId: 'prod-1', quantity: 2, price: 50 }],
      paymentMethod: PaymentMethod.CREDIT_CARD
    };

    it('should create order successfully with valid data', async () => {
      const savedOrder = { id: 'order-456', ...validOrderData, status: OrderStatus.PENDING };
      mockDb.save.mockResolvedValue(savedOrder);

      const result = await orderService.createOrder(validOrderData);

      expect(result.id).toBe('order-456');
      expect(result.status).toBe(OrderStatus.PENDING);
      expect(mockDb.save).toHaveBeenCalledWith(
        expect.objectContaining({ userId: 'user-123' })
      );
    });

    it('should throw error when order has no items', async () => {
      const emptyOrder = { ...validOrderData, items: [] };

      await expect(orderService.createOrder(emptyOrder))
        .rejects.toThrow('Order must contain at least one item');
    });

    it('should calculate total price correctly', async () => {
      const multiItemOrder = {
        ...validOrderData,
        items: [
          { productId: 'prod-1', quantity: 2, price: 50 },
          { productId: 'prod-2', quantity: 1, price: 30 }
        ]
      };
      mockDb.save.mockResolvedValue({ id: 'order-789', ...multiItemOrder, total: 130 });

      const result = await orderService.createOrder(multiItemOrder);

      expect(result.total).toBe(130); // 2×50 + 1×30
    });
  });
});

批量自动化处理​

对多个文件批量生成测试：

#!/bin/bash
# 批量为遗留文件生成测试

set -euo pipefail

COVERAGE_TARGET=${1:-80}  # 默认覆盖率目标 80%
OUTPUT_LOG="./test-generation.log"

echo "开始自动测试生成，覆盖率目标：${COVERAGE_TARGET}%" | tee "$OUTPUT_LOG"

# 找出没有测试的文件
MISSING_TESTS=$(find src/services -name "*.ts" ! -name "*.test.ts" | while read file; do
  test_file=$(echo "$file" | sed 's/src\///' | sed 's/\.ts$/.test.ts/')
  if [ ! -f "__tests__/$test_file" ]; then
    echo "$file"
  fi
done)

TOTAL=$(echo "$MISSING_TESTS" | wc -l)
CURRENT=0

echo "$MISSING_TESTS" | while read source_file; do
  CURRENT=$((CURRENT + 1))
  echo ""
  echo "[$CURRENT/$TOTAL] 处理：$source_file" | tee -a "$OUTPUT_LOG"

  result=$(claude --agent test-writer \
    "为 $source_file 生成完整测试，覆盖率目标 ${COVERAGE_TARGET}%，所有测试必须通过" \
    --dangerously-skip-permissions \
    --output-format stream-json 2>/dev/null | \
    jq -r 'select(.type=="text") | .content' | tail -5)

  echo "$result" | tee -a "$OUTPUT_LOG"

  # 防止 API 速率限制
  sleep 3
done

echo ""
echo "========================================" | tee -a "$OUTPUT_LOG"
echo "自动测试生成完成，查看日志：$OUTPUT_LOG"
echo "运行 npm test -- --coverage 查看总覆盖率"

关键技巧​

配置三个专业审查代理​

在项目根目录创建 .claude/agents.json：

{
  "agents": [
    {
      "name": "quality-reviewer",
      "displayName": "代码质量审查",
      "description": "审查代码可读性、设计模式、DRY 原则、命名规范",
      "model": "claude-sonnet-4-6",
      "systemPrompt": "你是一位专注于代码质量的高级工程师。审查时重点关注：\n\n1. **可读性**：命名是否清晰？逻辑是否易懂？注释是否必要？\n2. **DRY 原则**：是否有重复代码？是否可以提取公共函数？\n3. **单一职责**：函数/类是否只做一件事？是否过于庞大？\n4. **设计模式**：是否有更好的设计方式？\n5. **错误处理**：边界情况是否处理完整？\n\n输出格式：\n## 代码质量报告\n### 问题列表（按严重程度）\n[Critical/Major/Minor] 文件名:行号 - 问题描述 - 建议修改方式\n\n### 总体评价\n[1-10分] 和总结",
      "tools": ["Read", "Glob", "Grep"],
      "temperature": 0.3
    },
    {
      "name": "security-reviewer",
      "displayName": "安全漏洞审查",
      "description": "扫描 SQL 注入、XSS、CSRF、权限绕过、敏感信息泄露等安全问题",
      "model": "claude-sonnet-4-6",
      "systemPrompt": "你是一位专注于安全的高级工程师，熟悉 OWASP Top 10。审查时重点检查：\n\n1. **注入攻击**：SQL 注入、命令注入、LDAP 注入\n2. **XSS**：反射型、存储型、DOM 型\n3. **认证与授权**：权限检查是否完整？Token 是否安全？\n4. **敏感信息**：是否有硬编码的密码/API Key？日志是否泄露敏感信息？\n5. **依赖安全**：新增依赖是否有已知漏洞？\n6. **加密**：是否使用了不安全的加密算法？\n\n输出格式：\n## 安全审查报告\n### 漏洞列表\n[Critical/High/Medium/Low] OWASP-类别 - 文件名:行号 - 漏洞描述 - 修复建议\n\n### 总体安全评估",
      "tools": ["Read", "Glob", "Grep", "Bash"],
      "temperature": 0.1
    },
    {
      "name": "performance-reviewer",
      "displayName": "性能问题审查",
      "description": "分析 N+1 查询、不必要重渲染、内存泄露、算法复杂度等性能问题",
      "model": "claude-sonnet-4-6",
      "systemPrompt": "你是一位专注于性能优化的高级工程师。审查时重点关注：\n\n1. **数据库查询**：是否有 N+1 查询？索引是否合理？是否有不必要的全表扫描？\n2. **前端性能**：不必要的重渲染？大列表是否虚拟化？图片是否优化？\n3. **内存管理**：是否有内存泄露风险？大对象是否及时释放？\n4. **算法复杂度**：是否有 O(n²) 或以上复杂度的操作可以优化？\n5. **网络请求**：是否有重复请求？是否可以批量或缓存？\n6. **同步阻塞**：是否有不必要的同步操作阻塞主线程？\n\n输出格式：\n## 性能审查报告\n### 问题列表\n[High/Medium/Low Impact] 文件名:行号 - 问题描述 - 优化方案 - 预期收益\n\n### 总体性能评估",
      "tools": ["Read", "Glob", "Grep", "Bash"],
      "temperature": 0.2
    }
  ]
}

执行并行审查​

方式一：在 Claude Code 交互界面中指令触发​

请用三个子代理并行审查 src/auth/ 目录下最近修改的代码：

1. quality-reviewer：审查代码质量和设计
2. security-reviewer：扫描安全漏洞
3. performance-reviewer：分析性能问题

审查目标：
- 涉及文件：src/auth/AuthService.ts, src/auth/middleware.ts, src/auth/routes.ts
- 背景：这是一次认证模块重构，新增了 JWT 刷新机制和权限分组

三个代理完成后，将结果汇总为一份综合审查报告，按严重程度排序所有问题。

输出示例​

综合报告示例结构：

# 代码审查综合报告

审查时间：2025-02-18 14:30:22
审查目录：src/auth/

---

## 代码质量报告

### 问题列表
[Major] AuthService.ts:45 - `refreshToken` 方法超过 80 行，建议拆分
[Minor] middleware.ts:12 - 变量名 `t` 语义不清，建议改为 `token`

### 总体评价
7/10 - 整体结构清晰，但部分函数职责过重

---

## 安全审查报告

### 漏洞列表
[High] A2-失效认证 - AuthService.ts:89 - JWT 验证时未检查 `iss` 字段，可能被跨系统伪造
[Medium] A3-敏感数据泄露 - routes.ts:34 - 错误日志中输出了完整的 token 字符串

### 总体安全评估
中等风险，存在一个需要立即修复的认证漏洞

---

## 必须修复（Critical/High）

- [安全-High] AuthService.ts:89 - JWT 验证缺少 iss 字段检查

## 建议修复（Medium）

- [安全-Medium] routes.ts:34 - 日志中暴露完整 token
- [质量-Major] AuthService.ts:45 - refreshToken 函数过长需拆分

效率对比​

关键技巧​

前置准备​

安装 Chrome DevTools MCP​

# 添加 Chrome DevTools MCP 服务器
claude mcp add chrome-devtools npx @modelcontextprotocol/server-chrome-devtools

确认安装成功：

# 在 Claude Code 中检查
/mcp
# 应该看到 chrome-devtools: 已连接

安装 Python 依赖​

pip install openpyxl pandas

实现过程​

第 1 步：登录并获取数据​

使用 Chrome DevTools 打开我们的管理后台：
1. 导航到 https://admin.internal.com/login
2. 用账号 admin@company.com 登录（我来输密码）
3. 进入"销售报表"→"区域概览"页面
4. 截图确认页面加载完成

Claude Code 通过 chrome_navigate 打开页面，chrome_fill 填写表单，chrome_screenshot 截图确认：

[截图：已成功登录到管理后台，当前在区域概览页面]

页面上我看到一个表格，包含以下列：
- 区域名称
- 昨日销售额
- 本周累计
- 完成率
- 同比增长

共 12 个区域的数据。需要我抓取这些数据吗？

第 2 步：提取表格数据​

是的，把所有行的数据都抓下来，输出为 JSON 格式

Claude Code 使用 chrome_evaluate 执行 JavaScript 提取数据。

自动化定时执行​

将整个流程封装成脚本，配合 cron 每天自动运行：

#!/bin/bash
# 每日自动抓取销售数据并发送报表
# cron: 0 8 * * 1-5 /path/to/daily-sales-report.sh

claude -p "
使用 Chrome DevTools 登录管理后台，抓取区域销售数据，
生成格式化 Excel 文件保存到 ~/reports/ 目录，
完成后输出文件路径
" --dangerously-skip-permissions \
  --output-format stream-json | \
  jq -r 'select(.type=="text") | .content' | \
  tail -1  # 获取文件路径

# 发送邮件
REPORT_FILE=$(ls ~/reports/销售日报_*.xlsx | tail -1)
python3 -c "
import smtplib
from email.mime.multipart import MIMEMultipart
from email.mime.base import MIMEBase
from email import encoders
import os

msg = MIMEMultipart()
msg['From'] = 'robot@company.com'
msg['To'] = 'team@company.com'
msg['Subject'] = '每日销售报表'

with open('$REPORT_FILE', 'rb') as f:
    attachment = MIMEBase('application', 'octet-stream')
    attachment.set_payload(f.read())
    encoders.encode_base64(attachment)
    attachment.add_header('Content-Disposition', f'attachment; filename=\"{os.path.basename(\"$REPORT_FILE\")}\"')
    msg.attach(attachment)

with smtplib.SMTP('smtp.company.com', 587) as s:
    s.login('robot@company.com', os.environ['EMAIL_PASS'])
    s.send_message(msg)
print('邮件已发送')
"

效率对比​

关键技巧​

解决过程​

第 1 步：将文件夹拖入终端​

将设计资产文件夹从 Finder/Explorer 拖拽到终端，路径会自动填入：

# 路径自动填入后，启动 Claude Code
claude

第 2 步：描述重命名规则​

我的 /Users/me/project/assets/icons/ 目录下有 300 张切图，
文件名像这样：icon_home_v2_final_FINAL.png、btn-submit_copy2.png

请帮我重命名，规则如下：
1. 全部转为小写
2. 下划线统一换成连字符
3. 去掉 _v2、_final、_copy[数字] 这类版本后缀
4. 文件名只保留语义部分，如 icon-home.png、btn-submit.png

执行前先预览变更列表，我确认后再执行。

第 3 步：Claude 生成预览​

Claude Code 会先分析目录，生成变更预览：

分析完成，找到 283 个文件需要重命名：

icon_home_v2_final_FINAL.png    →  icon-home.png
icon_search_v1_copy3.png        →  icon-search.png
btn_submit_v2_FINAL.png         →  btn-submit.png
bg_hero_section_final2.png      →  bg-hero-section.png
... (还有 279 个)

注意事项：
⚠️  发现 3 组重名冲突（重命名后文件名相同）：
   - icon_user.png 和 icon_user_v2.png → 都会变成 icon-user.png
   - 建议：保留最新版，旧版加 -old 后缀？

是否按此规则执行？(确认 / 调整规则 / 处理冲突后再执行)

第 4 步：处理冲突并确认​

重名冲突的处理：icon_user_v2.png 保留为 icon-user.png，
icon_user.png 改名为 icon-user-v1.png

其余的按你说的规则执行，开始吧

第 5 步：执行重命名​

Claude Code 生成并执行重命名脚本：

#!/bin/bash
# 由 Claude Code 生成的重命名脚本

rename_file() {
  local old="$1"
  local new="$2"
  if [ -f "$new" ]; then
    echo "⚠️  跳过（目标已存在）: $old → $new"
    return
  fi
  mv "$old" "$new"
  echo "✓ $old → $new"
}

cd /Users/me/project/assets/icons/

rename_file "icon_home_v2_final_FINAL.png" "icon-home.png"
rename_file "icon_search_v1_copy3.png" "icon-search.png"
# ... 283 行

执行完成后输出统计：

完成！
✓ 成功重命名：280 个
⚠️  跳过（冲突）：3 个
✗ 失败：0 个

常见变体​

按日期前缀重命名​

把 exports/ 目录下所有文件加上今天的日期前缀，格式：2025-02-18_原文件名

序号化重命名​

把 screenshots/ 里的图片按修改时间排序，
重命名为 screenshot-001.png、screenshot-002.png...

跨格式重命名​

把所有 .jpeg 扩展名改成 .jpg，同时把文件名里的空格替换成连字符

基于内容重命名（配合 Vision）​

看一下 banners/ 目录里每张图的内容（可以截图），
按图片中显示的产品名称重命名文件

关键技巧​

从命令行手动管理到 Web 看板自动化调度，构建你自己的 Claude Code Manager。支持任务创建、需求自动拆分、并行执行、实时日志监控和一键合并。

整体架构​

┌─────────────────────────────────────────────────┐
│              浏览器 / 手机 PWA                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │
│  │ 任务看板  │ │ 实时日志  │ │ 项目/Worktree管理 │  │
│  └──────────┘ └──────────┘ └──────────────────┘  │
└───────────────────┬─────────────────────────────┘
                    │ WebSocket + REST API
┌───────────────────▼─────────────────────────────┐
│            Python 后端 (FastAPI)                   │
│  ┌──────────┐ ┌───────────┐ ┌────────────────┐  │
│  │ 任务调度器 │ │ CC进程管理 │ │ Git Worktree管理│  │
│  └──────────┘ └───────────┘ └────────────────┘  │
│  ┌──────────┐ ┌───────────┐ ┌────────────────┐  │
│  │ 日志解析器 │ │ 模板引擎  │ │  SQLite 存储   │  │
│  └──────────┘ └───────────┘ └────────────────┘  │
└───────────────────┬─────────────────────────────┘
                    │ subprocess
┌───────────────────▼─────────────────────────────┐
│          Claude Code 实例 ×N                      │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐            │
│  │ worktree1│ │ worktree2│ │ worktree3│  ...      │
│  │ feat/auth│ │ feat/ui  │ │ feat/api │           │
│  └─────────┘ └─────────┘ └─────────┘            │
└─────────────────────────────────────────────────┘

系统分为三层：

• 前端层：基于原生 HTML/CSS/JS 的单文件看板，通过 WebSocket 接收实时日志，通过 REST API 操作任务。支持 PWA，可添加到手机桌面。
• 后端层：FastAPI 提供异步 API，aiosqlite 管理持久化数据，asyncio 并发调度多个 Claude Code 实例。
• 执行层：每个任务在独立的 Git Worktree 中运行，Claude Code 以 stream-json 格式输出，后端解析后通过 WebSocket 广播。

项目结构​

claude-code-manager/
├── app.py              # FastAPI 后端主入口
├── requirements.txt    # Python 依赖
├── tasks.db            # SQLite 数据库（自动创建）
├── manifest.json       # PWA 清单
├── sw.js               # Service Worker
├── templates/          # 项目模板
│   ├── CLAUDE.md.tpl   # CLAUDE.md 通用模板
│   └── PROGRESS.md.tpl # 进度追踪模板
└── frontend/
    └── index.html      # 看板 UI（单文件）

启动与使用​

# 1. 创建项目目录
mkdir claude-code-manager && cd claude-code-manager
mkdir -p frontend templates

# 2. 安装依赖
pip install fastapi uvicorn websockets aiosqlite

# 3. 将 app.py 和 frontend/index.html 放入对应目录

# 4. 启动服务
uvicorn app:app --host 0.0.0.0 --port 8080

# 5. 浏览器访问
# http://localhost:8080

自动化任务流程​

以下是从需求输入到代码合并的完整端到端流程：

用户输入需求
    │
    ▼  POST /api/tasks/batch
Claude Code 自动拆分 → 5 个独立任务
    │
    ▼  用户看板上审阅生成的任务列表
    │  可以手动编辑/删除不需要的任务
    │
    ▼  点击「全部启动」 POST /api/tasks/run-all
5 个 Git Worktree 并行创建
5 个 Claude Code 实例并行启动
    │
    ▼  WebSocket 实时推送日志
看板显示每个任务的运行状态和实时输出
    │
    ▼  各任务独立完成
状态变为 success / failed
    │
    ▼  对每个 success 任务点击「合并分支」
自动执行 git merge --no-ff，删除 worktree
    │
    ▼
主分支包含所有新功能

并行执行效率对比​

手机端 PWA 配置​

将以下文件添加到 claude-code-manager/ 目录，实现 PWA 支持：

{
  "name": "Claude Code Manager",
  "short_name": "CC Manager",
  "description": "Claude Code 可视化任务管理系统",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#0d1117",
  "theme_color": "#161b22",
  "icons": [
    {
      "src": "data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🤖</text></svg>",
      "sizes": "any",
      "type": "image/svg+xml"
    }
  ]
}

添加到桌面步骤：

1. 在 Chrome（Android）或 Safari（iOS）中打开 http://your-server:8080
2. Chrome：点击右上角菜单 → "添加到主屏幕"
3. Safari：点击分享按钮 → "添加到主屏幕"
4. 安装后图标出现在桌面，以独立 App 模式运行，无浏览器导航栏
5. 支持离线访问界面（API 调用需要网络连接）

进阶增强方向​

安全注意事项​

Docker 部署（推荐）​

FROM python:3.12-slim

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

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

# 只挂载指定的项目目录，而非整个宿主机文件系统
VOLUME ["/projects"]

EXPOSE 8080
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]

# 构建和运行
docker build -t cc-manager .
docker run -d \
  -p 8080:8080 \
  -v /home/user/my-project:/projects/my-project \
  -e ANTHROPIC_API_KEY=your_key \
  cc-manager

基于胡渊鸣的实践经验，本文将其方法论拆解为可直接落地的 6 个阶段。每个阶段独立可用，按需逐步升级。

前置条件​

• Claude Code 已安装 (npm install -g @anthropic-ai/claude-code)
• 项目已用 Git 管理
• 建议在独立的云服务器或容器中操作（如 EC2、本地 Docker）

阶段 1：无打断模式（效率 ×2）​

最低门槛的改进。

claude --dangerously-skip-permissions

# crontab -e 添加，每小时自动备份
0 * * * * cd /your/project && git add -A && git stash push -m "auto-backup-$(date +\%H\%M)"

效果：单个 prompt 下 Claude Code 能连续工作 5+ 分钟，不会被权限弹窗中断。

阶段 2：CLAUDE.md + PROGRESS.md（质量 ×2）​

在项目根目录创建两个文件，这是所有后续步骤的基础。

CLAUDE.md — 项目规范（不频繁改动）​

完整模板示例：

# 项目名称

## 技术栈
- 前端: React + TypeScript
- 后端: Node.js + Express
- 数据库: PostgreSQL

## 项目结构
src/
├── components/    # UI 组件
├── services/      # 业务逻辑
├── utils/         # 工具函数
└── types/         # 类型定义

## 常用命令
npm run dev        # 启动开发服务器
npm test           # 运行测试
npm run build      # 构建生产版本

## 编码规范
- 文件名用 kebab-case
- 组件名用 PascalCase
- 提交信息遵循 Conventional Commits

## 禁止事项
- 不要删除 config/production.json
- 不要直接修改 database schema，先备份
- 不要在代码中硬编码密钥

## 工作模式
每次任务完成后，将踩坑经验总结到 PROGRESS.md 中。同样的错误不要再犯。

PROGRESS.md — 经验教训（AI 的外部记忆）​

# 经验记录

## 2026-02-18
- 问题：修改登录模块时忘记更新路由配置，导致页面 404
- 教训：修改任何模块后必须检查相关路由是否同步更新
- 解决：在测试中加入路由完整性检查

## 2026-02-17
- 问题：数据库迁移脚本缺少回滚逻辑
- 教训：每个 migration 必须包含 up 和 down

在 CLAUDE.md 中加入引用：

每次启动时阅读 PROGRESS.md，避免重复犯错。

自动生成 CLAUDE.md​

如果不想手写，可以让 Claude Code 自动分析生成：

claude -p "分析当前项目结构、package.json、README，生成一份 CLAUDE.md，包含技术栈、项目结构、常用命令、编码规范、禁止事项" --dangerously-skip-permissions

阶段 3：Git Worktree 并行化（效率 ×5）​

这是核心的并行化技术。

Git Worktree 原理​

主仓库 (.git)
    ├── main 工作区 (原始目录)
    ├── worktree-1 (feat/auth 分支) → Claude Code 实例 1
    ├── worktree-2 (feat/ui 分支)   → Claude Code 实例 2
    └── worktree-3 (feat/api 分支)  → Claude Code 实例 3

共享: Git 历史、远程配置、hooks
独立: 工作目录、分支、暂存区

操作步骤​

# 1. 创建并行工作区
cd /your/project
git worktree add ../project-wt1 -b feat/task-1
git worktree add ../project-wt2 -b feat/task-2
git worktree add ../project-wt3 -b feat/task-3

# 2. 每个工作区启动独立的 Claude Code
# 方式一：多个终端标签页
cd ../project-wt1 && claude --dangerously-skip-permissions

# 方式二：tmux 多窗格
tmux new-session -d -s cc1 "cd ../project-wt1 && claude --dangerously-skip-permissions"
tmux new-session -d -s cc2 "cd ../project-wt2 && claude --dangerously-skip-permissions"
tmux new-session -d -s cc3 "cd ../project-wt3 && claude --dangerously-skip-permissions"

# 3. 任务完成后合并
cd /your/project
git merge feat/task-1
git merge feat/task-2
git merge feat/task-3

# 4. 清理工作区
git worktree remove ../project-wt1
git worktree remove ../project-wt2
git worktree remove ../project-wt3

合并冲突处理​

# 如果合并出现冲突
git merge feat/task-2
# CONFLICT detected

# 方式一：让 Claude Code 解决
claude -p "解决当前的 git merge 冲突，保留两边功能" --dangerously-skip-permissions

# 方式二：手动解决后继续
git add .
git merge --continue

实际效果​

阶段 4：Ralph Loop — 连续任务执行（效率 ×8）​

任务文件 TODO.md​

- [ ] 实现用户登录页面，包含表单验证
- [ ] 添加 API 鉴权中间件（JWT）
- [ ] 编写 auth 模块单元测试，覆盖率 >80%
- [ ] 实现用户资料编辑页面
- [ ] 添加文件上传功能

CLAUDE.md 中的工作模式定义​

## Ralph Loop 工作模式
1. 读取 TODO.md，找到第一个未完成的任务（`- [ ]`）
2. 执行该任务
3. 运行测试确认通过
4. 将其标记为 `- [x]`，附上完成时间
5. 将经验记录到 PROGRESS.md
6. 如果还有未完成任务，继续下一个
7. 所有任务完成后，输出总结报告

自动循环脚本​

#!/bin/bash
# run-loop.sh — Ralph Loop 自动调度器
PROJECT_DIR="/your/project"

while true; do
    # 检查是否还有未完成任务
    if ! grep -q '\- \[ \]' "$PROJECT_DIR/TODO.md"; then
        echo "✅ 所有任务已完成"
        break
    fi

    echo "🔄 启动新一轮 Claude Code..."
    claude -p "按照 CLAUDE.md 中的 Ralph Loop 工作模式执行下一个任务。完成后更新 TODO.md 和 PROGRESS.md。" \
        --dangerously-skip-permissions \
        --cwd "$PROJECT_DIR"

    EXIT_CODE=$?
    if [ $EXIT_CODE -ne 0 ]; then
        echo "⚠️ Claude Code 异常退出（退出码: $EXIT_CODE），等待 10 秒后重试..."
        sleep 10
    else
        sleep 2
    fi
done

chmod +x run-loop.sh
./run-loop.sh

阶段 5：程序化调度 -p + stream-json（效率 ×10+）​

核心命令​

# 基础用法：执行一个任务并退出
claude -p "实现用户注册功能" --dangerously-skip-permissions

# 进阶：JSON 流式输出，方便程序解析
claude -p "实现用户注册功能" \
    --dangerously-skip-permissions \
    --output-format stream-json \
    --verbose

这部分包含详细的 Python 调度器示例代码，可查看原文件获取完整实现。

阶段 6：Plan 模式批量预审（成功率 95%+）​

先出计划后执行​

# Step 1: 生成计划
claude -p "请为以下需求生成执行计划，列出步骤和涉及的文件，不要开始编码：
实现 OAuth2.0 第三方登录，支持 Google 和 GitHub" \
    --dangerously-skip-permissions > plan.md

# Step 2: 人工审阅 plan.md（关键！）
cat plan.md

# Step 3: 确认后执行
claude -p "按照 plan.md 中的计划执行" \
    --dangerously-skip-permissions

效率升级路径总结​

应用到新项目的标准流程​

1. git init 或 clone 已有项目
2. 创建 CLAUDE.md（手写或 claude -p 自动生成）
3. 创建 PROGRESS.md（空文件即可）
4. 编写 TODO.md 列出所有任务
5. 评估任务独立性，决定并行数量
6. 用 Git Worktree 创建工作区
7. 启动 Claude Code 实例
8. 监控执行，合并结果

本文整理自 Meshy AI 创始人胡渊鸣（Ethan Hu）的公开分享，记录了他从单机 Cursor Agent 到 10 个 Claude Code 实例并行运行的完整进化路径。这是目前最系统、最具工程深度的 Agentic Coding 实践案例之一。

背景​

关于胡渊鸣​

胡渊鸣（Ethan Hu）的经历堪称技术创业者的理想模板：

• 清华大学姚班（计算机科学实验班）毕业
• MIT 计算机图形学博士
• 太极图形语言（Taichi）创造者——一门面向图形与并行计算的高性能编程语言
• Meshy AI 创始人兼 CEO——全球排名第一的 3D AI 生成平台，ARR 已达 3000 万美元

凭借深厚的技术背景，胡渊鸣对 AI 编程工具有着比普通开发者更敏锐的判断力。他选择用自己的亲身实践，系统性地探索 Claude Code 的吞吐量极限。

目标：给 CEO 造一套量身定制的软件​

作为公司 CEO，胡渊鸣的日常工作高度碎片化。他决定用 Vibe Coding 为自己开发一套"CEO 支持软件"，核心需求包括：

这套软件没有现成产品可以替代——它需要完全匹配个人工作流。定制化软件的开发成本，正在被 AI 编程工具趋近于零。

提高 Agentic Coding 吞吐量的 10 个阶段​

Step 1：从 Cursor Agent 到 Claude Code​

故事从一台 RTX 4090 的 Ubuntu 工作站开始。

胡渊鸣原本使用 Cursor Agent，并取得了令人印象深刻的成果——在工作站上用 3 小时完成了一个 GPU DSL（领域专用语言）的重新设计，而传统方式需要整整 3 周。

但问题随之而来：工作站只能在公司使用，灵感却随时随地都会出现。他需要远程操控（RustDesk），操作体验极差。

切换到 Claude Code 后，通过 SSH 在 iPhone 上直接访问服务器，可以 vibe coding 的时间窗口从每天 8 小时扩展到 24 小时。

Step 2：找个 Container​

在本地工作站上操作仍然有局限。胡渊鸣将工作环境迁移到 AWS EC2，并启用了 Claude Code 的跳权模式：

claude --dangerously-skip-permissions

这个改变带来了质的飞跃：Claude Code 在单个 prompt 下可以持续工作 5 分钟甚至更长，无需频繁的人工确认，大幅提高了利用率。

云端容器的优势：

• 资源弹性伸缩，可同时跑多个实例
• 网络稳定，无需担心本地断线
• 计费按需，成本可控
• 天然隔离，降低权限风险

Step 3：Ralph Loop，让 Claude Code 不停干活​

有了容器之后，下一个瓶颈出现了：每次任务完成后，Claude Code 就停下来等待新指令。

胡渊鸣引入了 Ralph Loop——一种让 Claude Code 持续自驱工作的模式：

1. 从任务列表中取出下一个任务
2. 执行任务
3. 将结果记录到任务列表
4. 回到步骤 1，直到列表为空

更妙的是，他用 Claude Code 开发了 Claude Code 的启动器——让 AI 管理 AI 的工作流。CLAUDE.md 文件定义了"干活"的具体内容和规则，Claude Code 启动后自动读取并开始循环执行。

这是一个典型的 meta-programming 思路：用 AI 编程工具来优化 AI 编程工具自身的使用效率。

Step 4：用 Git Worktree 实现并行化​

Ralph Loop 解决了单个实例的连续性问题，但还不够。胡渊鸣开始思考：能否同时跑多个 Claude Code？

答案是 Git Worktree。

# 为每个并行任务创建独立的工作树
git worktree add ../feature-auth feature/auth
git worktree add ../feature-ui feature/ui
git worktree add ../feature-api feature/api

# 在每个工作树中启动独立的 Claude Code 实例
cd ../feature-auth && claude --dangerously-skip-permissions &
cd ../feature-ui   && claude --dangerously-skip-permissions &
cd ../feature-api  && claude --dangerously-skip-permissions &

Git Worktree 的核心优势是：多个工作区共享同一个 Git 仓库历史，但拥有各自独立的工作目录和分支，互不干扰。

实际效果：5 个 Claude Code 实例并行运行，达到了每分钟 1 个 commit 的速度。

GitHub 成为整个并行开发的调度中心：任务分支、进度追踪、代码合并全部通过 Git 管理。

Step 5：用好 CLAUDE.md 和 PROGRESS.md​

随着并行实例增多，如何保持 AI 行为一致性成为新挑战。胡渊鸣总结了两类关键文件的最佳实践：

CLAUDE.md（项目规范）：

• 定义编码规范、架构约定、禁止行为
• 不宜频繁修改——频繁变动会让 Claude Code 产生混乱的行为
• 写清楚"什么情况下不该做什么"，比"应该做什么"更重要

PROGRESS.md（经验积累）：

• 记录每次踩坑的教训
• 关键原则："同样的错误下次不要再犯"
• 在 CLAUDE.md 中引用 PROGRESS.md，让 AI 在每次启动时复习历史教训

<!-- CLAUDE.md 中的典型写法 -->
## 重要约束
- 修改数据库 schema 前必须先备份，参见 PROGRESS.md#数据库事故-2024-03
- 不要直接修改 config/production.json，所有生产配置通过环境变量注入

Step 6：干掉 SSH，开发界面变手机网页​

SSH 下的 Claude Code 有一个令人抓狂的问题：在 iPhone Safari 中刷新 terminal 时，延迟巨大、体验极差。

胡渊鸣的解决方案：自己写一个 Claude Code Web Manager。

核心架构：

iPhone Safari
    ↓ HTTP 请求
Web Manager（Python Flask）
    ↓ subprocess
Claude Code（-p 非交互模式）
    ↓ JSON 输出
Web Manager 解析展示

关键命令：

# 非交互模式，适合被程序调度
claude -p "执行任务描述" \
  --dangerously-skip-permissions \
  --output-format stream-json \
  --verbose

最终，这个 Web Manager 被包装成 iPhone 的 PWA（Progressive Web App），添加到桌面后与原生 App 无异。走在马路上打开手机，就能查看和调度所有 Claude Code 实例的状态。

Step 7：有效编写管理 Claude Code 的程序​

Web Manager 只是开始。随着管理复杂度上升，胡渊鸣开始系统性地优化管理程序的设计。

关键洞察：Claude Code 的成功率取决于闭环是否完整。

一个完整的闭环包括：

写代码 → 运行代码 → 检查输出 → 发现问题 → 调试修复 → 重新运行

如果任何一个环节断开，Claude Code 就会陷入"以为成功"的假象。

实现方式：

# 使用 stream-json 格式捕获完整执行过程
claude -p "完成任务 X，运行测试，确认全部通过后才算完成" \
  --dangerously-skip-permissions \
  --output-format stream-json \
  --verbose 2>&1 | python manager.py parse-and-monitor

Manager 程序通过解析 JSON 日志：

• 检测测试是否真正运行并通过
• 发现运行时错误并自动重试
• 超时保护，防止无限循环
• 统计成功率，持续优化提示词

效果：任务成功率从 20% 提升到 95%。

这个数字揭示了一个重要事实：Agentic Coding 的成功率很大程度上取决于管理层的设计，而不仅仅是 AI 本身的能力。

Step 8：自然语言编程​

有了 Web Manager，下一步是让输入更自然。

胡渊鸣在输入框中集成了语音识别 API，实现了真正的"语音 vibe coding"：

• 打开手机，对着麦克风说需求
• 语音转文字，自动发送给 Claude Code
• Claude Code 开始执行，结果实时推送到手机

走在马路上都可以 vibe coding。 这不是比喻，是字面意义上的随时随地编程。

Step 9：添加 Plan Mode​

在大量并行任务场景中，"先执行后发现方向错了"的成本极高。胡渊鸣封装了 Claude Code 的 Plan 模式：

用户提交需求
    ↓
Claude Code 生成执行计划（不执行）
    ↓
统一展示所有待处理实例的计划
    ↓
用户批量 review，修改或确认
    ↓
批量 kick off 执行

这个模式的价值在于：用极低的成本（看一眼计划）过滤掉方向性错误，避免浪费几十分钟的执行时间。

当同时有 10 个 Claude Code 在工作时，每个实例节省一次错误方向的执行，累计节省的时间相当可观。

Step 10：坚持不看代码​

这是最反直觉，也最重要的一步。

胡渊鸣制定了一条铁律：坚决不看 Claude Code 生成的具体代码。

这不是懒惰，而是一种刻意的管理哲学：

"Context, not control."（提供上下文，而不是微观管理。）

他真正关注的事情：

杜绝 micromanagement 的本质是：相信系统，而不是相信单次执行的细节。

关键启示​

启示一：标准化软件的终结​

当一个 CEO 可以在手机上用语音随时指挥 10 个 AI 实例并行开发软件，软件开发的成本正在趋近于零。

这意味着：

• 任何人都可以拥有完全匹配自己工作流的定制化工具
• 标准化 SaaS 软件的竞争优势将持续减弱
• 未来的软件可能不再是"产品"，而是"实时生成的工具"

启示二：管理 AI 比管人更能提高领导力​

在传统管理中，给一个下属安排任务后，你需要等待数天才能得到反馈。而管理 Claude Code：

• 反馈周期：5 分钟
• 并发数量：理论上无限
• 成长速度：每天迭代数十次，是人类的 100 倍

这意味着 AI 时代的领导力核心技能发生了根本性转变：从"如何做"转向"做什么"，从执行优化转向方向判断。

启示三：重新审视"学习"的意义​

如果 AI 可以完成大量的执行性工作，人类的学习目标也需要重新定义：

不是学习如何编写更好的代码，而是学习如何提出更好的问题。不是积累技术细节，而是建立跨领域的第一性原理思维。

核心技术栈总结​

可复用的行动清单​

如果你想复刻胡渊鸣的部分实践，可以按以下顺序逐步推进：

• 起点：在本地用 claude --dangerously-skip-permissions 跑一个完整任务，感受无打断的体验
• 容器化：将工作环境迁移到云端 EC2，确保 24 小时可访问
• 任务列表：建立 PROGRESS.md，记录第一个踩坑经验
• 并行化：用 Git Worktree 同时开两个 Claude Code 处理不同功能分支
• 监控闭环：用 stream-json 输出接入简单的监控脚本，检测任务真实成功率
• Plan 先行：对所有超过 30 分钟的任务，强制先用 Plan 模式审查方向
• 不看代码：连续一周只看测试结果和功能演示，训练自己放弃 micromanagement