Claude Code代码审查五式：从终端Review到多Agent自动化

# 查看当前工作区的变更
git diff | claude "Review this diff for bugs, security issues, and improvements"

# 只审查已暂存的变更
git diff --cached | claude "Review staged changes for correctness bugs only"

# 审查某个分支相对于main的所有差异
git diff main...HEAD | claude "Review all changes vs main. Focus on logic errors and security."

## Code Review Findings

### 🔴 Critical: SQL Injection (src/auth/login.ts:42)
用户输入 `username` 直接拼接进SQL查询字符串，存在注入风险。
当前代码: db.query(`SELECT * FROM users WHERE name = '${username}'`)
建议修复: db.query('SELECT * FROM users WHERE name = $1', [username])

### 🟡 Warning: Missing Error Handling (src/api/handler.ts:88)
fetch() 调用没有 try/catch，网络超时会导致未捕获异常。

### ✅ Good: Proper Null Check (src/utils/parse.ts:15)
新增的 null guard 正确处理了边缘情况。

# 快速审查别名
alias cr='git diff | claude "Review for bugs, security issues. Be concise."'
alias crc='git diff --cached | claude "Review staged changes for critical bugs only."'
alias crm='git diff main...HEAD | claude "Review all branch changes vs main."'

# 启动Claude Code交互会话
claude

# 在会话中执行代码审查
> /code-review

# 指定审查力度（低/中/高）
> /code-review --effort high

# 审查后将结果作为内联评论发到PR（需要GitHub认证）
> /code-review --comment

flowchart LR
    subgraph 管道方式
        A[git diff] -->|stdin| B[单次推理]
        B --> C[文本输出]
    end

    subgraph code-review命令
        D[读取diff] --> E[分析周围代码]
        E --> F[多轮验证]
        F --> G{发现问题?}
        G -->|是| H[打开相关文件确认]
        H --> I[结构化报告]
        G -->|否| J[确认无问题]
        I --> K[可选: --comment 发到PR]
        J --> K
    end

    style 管道方式 fill:#e8f4f8
    style code-review命令 fill:#fff3e0

# 切换到feature分支
git checkout feature/new-auth-flow

# 启动Claude Code
claude

# 执行深度审查
> /code-review --effort high

flowchart TB
    PR[Pull Request 创建/更新] --> Trigger[触发审查]

    Trigger --> Fleet[Agent集群]

    Fleet --> A1[Agent 1: Bug Detector]
    Fleet --> A2[Agent 2: Security Scanner]
    Fleet --> A3[Agent 3: Regression Analyzer]
    Fleet --> A4[Agent 4: Convention Checker]
    Fleet --> A5[Agent 5: Edge Case Hunter]

    A1 --> Merge[发现合并与去重]
    A2 --> Merge
    A3 --> Merge
    A4 --> Merge
    A5 --> Merge

    Merge --> Verify[验证步骤: 对照代码行为确认]
    Verify --> Score[置信度评分 0-100]
    Score --> Filter{≥ 80分?}
    Filter -->|是| Post[发布为内联评论]
    Filter -->|否| Log[仅记录在日志]

    Post --> Comment[GitHub PR评论 + 严重等级标记]

    style Fleet fill:#ffcdd2
    style Verify fill:#c8e6c9
    style Post fill:#bbdefb

# 在Claude Code中运行安装向导
claude
> /install-github-app

# Review Criteria

## 重点关注
- 授权回归：管理员和普通用户的权限检查是否一致
- 幂等性：Webhook处理器是否保证重复调用安全
- 事务边界：涉及支付的写操作是否有事务保护
- 异步任务：是否存在重复发送邮件/退款/通知的风险
- 输入验证：所有外部输入是否经过校验和清洗

## 不关注（已有工具覆盖）
- 代码格式和import顺序
- 命名风格（已由ESLint处理）
- TypeScript类型声明的完整性

# CLAUDE.md

## 架构说明
- packages/auth 负责所有角色和权限检查
- apps/api 是唯一允许修改计费状态的服务
- apps/worker 重放Webhook事件，必须保持幂等
- 不要在 BillingService 之外直接写 Subscription 表

## 关键约束
- 所有数据库写操作必须通过 Repository 层
- 禁止在 controller 中直接操作 ORM
- 环境变量通过 config 模块统一读取

# 方式1：自动触发（配置为opened/every push时）
git push origin feature/new-auth

# 方式2：手动触发
# 在PR页面评论：
@claude review

# 方式3：一次性审查（不改变仓库设置）
# 在PR页面评论：
@claude review once

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

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

    steps:
      # 必须checkout，Agent需要读取完整文件来验证发现
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            REPO: ${{ github.repository }}
            PR NUMBER: ${{ github.event.pull_request.number }}
            Review the diff for correctness, security, and obvious bugs.
            Focus on logic errors, unhandled error paths, missing input
            validation, and tests that do not actually exercise the new
            behavior. Skip style nits.
            Post inline comments on the lines you have something concrete
            to say about, then a one-paragraph summary as a top-level
            PR comment.
          claude_args: |
            --model claude-sonnet-4-6
            --max-turns 8
            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

flowchart TB
    subgraph YAML配置
        A[prompt] --> B[审查指令文本]
        C[claude_args] --> D[--model 模型选择]
        C --> E[--max-turns 对话轮数]
        C --> F[--allowedTools 工具白名单]
    end

    subgraph 工具白名单
        F --> G[create_inline_comment<br/>在diff行上发评论]
        F --> H[gh pr comment<br/>发PR总结评论]
        F --> I[gh pr diff<br/>读取diff内容]
        F --> J[gh pr view<br/>查看PR元数据]
    end

    subgraph 执行流程
        K[PR事件触发] --> L[checkout代码]
        L --> M[读取diff]
        M --> N[Agent分析]
        N --> O[打开文件验证]
        O --> P[发布内联评论]
        P --> Q[发布总结评论]
    end

    style 工具白名单 fill:#e1f5fe

jobs:
  review:
    runs-on: ubuntu-latest
    if: |
      github.event_name == 'pull_request' &&
      !github.event.pull_request.draft
    steps:
      - uses: actions/checkout@v6
      - name: Check if important paths changed
        id: filter
        run: |
          CHANGED=$(gh pr diff ${{ github.event.pull_request.number }} \
            --name-only | grep -E '^(src/|lib/|pkg/)' | head -1)
          if [ -n "$CHANGED" ]; then
            echo "should_review=true" >> $GITHUB_OUTPUT
          else
            echo "should_review=false" >> $GITHUB_OUTPUT
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - uses: anthropics/claude-code-action@v1
        if: steps.filter.outputs.should_review == 'true'
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Only review files under src/, lib/, and pkg/.
            Skip documentation, config, and generated files.
          claude_args: |
            --model claude-sonnet-4-6
            --max-turns 8
            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

flowchart LR
    PR[PR提交] --> Review[Code Review<br/>四种模式任选]
    Review --> Check[Check Run输出]
    Check --> Parse[解析severity JSON]
    Parse --> Gate{有Important发现?}
    Gate -->|是| Block[⚠️ 标记需要关注]
    Gate -->|否| Pass[✅ 审查通过]
    Block --> Fix[开发者修复]
    Fix --> Push[推送修复]
    Push --> Review
    Pass --> Merge[人工Review后合并]

    style Gate fill:#fff9c4
    style Block fill:#ffcdd2
    style Pass fill:#c8e6c9
    style Merge fill:#bbdefb

# 提取severity数据
gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

# 输出示例：
# {"normal": 2, "nit": 1, "pre_existing": 0}

# .github/workflows/review-gate.yml
name: Review Quality Gate

on:
  check_run:
    types: [completed]

jobs:
  gate:
    runs-on: ubuntu-latest
    if: github.event.check_run.name == 'Claude Code Review'
    steps:
      - name: Parse review severity
        id: severity
        run: |
          SEVERITY=$(gh api repos/${{ github.repository }}/check-runs/${{ github.event.check_run.id }} \
            --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson')
          echo "data=$SEVERITY" >> $GITHUB_OUTPUT
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Check for critical findings
        run: |
          IMPORTANT=$(echo '${{ steps.severity.outputs.data }}' | jq '.normal')
          if [ "$IMPORTANT" -gt 0 ]; then
            echo "::warning::⚠️ Found $IMPORTANT important issue(s). Review before merging."
            echo "has_critical=true" >> $GITHUB_ENV
          else
            echo "✅ No critical findings. Safe to merge."
            echo "has_critical=false" >> $GITHUB_ENV
          fi

      - name: Post gate status comment
        if: always()
        run: |
          if [ "$has_critical" = "true" ]; then
            gh pr comment $PR_NUMBER --body "## ⚠️ Code Review Gate
            Found important issues that should be addressed before merging.
            Review the inline comments above and push fixes."
          else
            gh pr comment $PR_NUMBER --body "## ✅ Code Review Gate Passed
            No critical issues found. Ready for human review."
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.check_run.pull_requests[0].number }}

payment-service/
├── src/
│   ├── handlers/
│   │   ├── charge.ts      # 扣款处理
│   │   └── refund.ts      # 退款处理
│   ├── services/
│   │   ├── payment.ts     # 支付核心逻辑
│   │   └── webhook.ts     # Webhook处理
│   └── middleware/
│       └── auth.ts        # 认证中间件
├── CLAUDE.md              # 项目上下文
├── REVIEW.md              # 审查标准
└── .github/workflows/
    ├── claude-review.yml  # AI审查workflow
    └── review-gate.yml    # 质量门禁workflow

# CLAUDE.md

## 架构
- 这是一个Express.js支付微服务，处理信用卡和Webhook
- payment.ts 是核心，所有金额变更必须通过 PaymentService
- webhook.ts 处理Stripe回调，必须保证幂等性
- auth.ts 校验Bearer Token + API Key双重认证

## 关键约束
- 金额使用整数（分），禁止浮点运算
- 所有外部API调用必须有超时和重试
- 退款必须校验原交易存在且未退款
- 禁止在handler层直接访问数据库

# REVIEW.md

## 必须审查
- 金额计算的精度（是否使用了浮点数）
- 并发退款是否可能导致重复退款
- Webhook处理的幂等性
- API Key和Secret是否硬编码
- 错误响应是否泄露内部信息

## 忽略
- TypeScript类型声明的完整性
- import语句排序
- 注释风格

# 提交前快速自查
git diff | claude "Review for payment-specific bugs: float math, idempotency, race conditions."

# 深度审查整个支付模块
claude
> /code-review --effort high --focus security

# .github/workflows/claude-review.yml
name: Payment Service Review

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'src/**'
      - 'package.json'

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            This is a payment microservice. Critical review areas:
            1. Float math in monetary calculations (MUST use integer cents)
            2. Idempotency of webhook handlers
            3. Race conditions in concurrent refunds
            4. Hardcoded secrets or API keys
            5. Error responses leaking internal info

            Post inline comments ONLY for real bugs and security issues.
            Skip style nits entirely.
          claude_args: |
            --model claude-sonnet-4-6
            --max-turns 10
            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

- name: Payment-specific checks
  run: |
    # 检查是否有金额相关的发现
    FINDINGS=$(gh api repos/${{ github.repository }}/check-runs/${{ github.event.check_run.id }} \
      --jq '.output.text')
    if echo "$FINDINGS" | grep -qi "float\|decimal\|0.01\|precision"; then
      echo "::error::⚠️ Float arithmetic detected in payment code!"
      exit 1
    fi

flowchart TB
    subgraph 开发阶段
        Dev[编写代码] --> Local[git diff管道<br/>闪电自查]
        Local --> Fix1[修复明显问题]
        Fix1 --> Commit[提交代码]
    end

    subgraph PR阶段
        Commit --> PR[创建Pull Request]
        PR --> Action[GitHub Actions触发]
        Action --> Agent[5个Agent并行审查]
        Agent --> Inline[内联评论]
        Agent --> Summary[PR总结评论]
    end

    subgraph 门禁阶段
        Inline --> Parse[解析severity JSON]
        Summary --> Parse
        Parse --> Gate{有Important?}
        Gate -->|是| Review1[人工Review<br/>重点看AI发现]
        Gate -->|否| Review2[人工Review<br/>关注架构设计]
    end

    subgraph 反馈闭环
        Review1 --> Feedback[👍👎反馈]
        Review2 --> Feedback
        Feedback --> Calibrate[校准审查质量]
        Calibrate -.->|优化| REVIEW[REVIEW.md调整]
    end

    style 开发阶段 fill:#e3f2fd
    style PR阶段 fill:#fff3e0
    style 门禁阶段 fill:#fce4ec
    style 反馈闭环 fill:#e8f5e9

# ❌ 泛泛的REVIEW.md
Review for bugs and security issues.

# ✅ 精准的REVIEW.md
## 必须发现
- 缺少事务包裹的数据库写操作
- Redis缓存未设置TTL
- JWT token未校验过期时间
- HTTP响应包含stack trace

## 不要报告
- 变量命名（已有lint规则覆盖）
- import顺序（已有prettier覆盖）
- 函数缺少JSDoc