第 07 期 | /caveman-review — 一行式代码审查

🎯 学习目标

学完本期你将掌握：

1. /caveman-review 的输出格式和严重级别体系
2. 如何在不同平台上触发代码审查
3. 实战：审查一段 Express 中间件代码
4. 与 GitHub Actions 集成实现 PR 自动审查

📖 核心内容

7.1 为什么代码审查需要 Caveman？

传统 AI 代码审查的问题：

❌ 正常 Claude 的代码审查 (每个问题写一大段):

"I noticed that on line 42, you're accessing `user.name` without 
first checking if the `user` object is null or undefined. This could 
lead to a TypeError at runtime if the database query returns no results. 
I'd suggest adding a null check before accessing the property, perhaps 
using optional chaining (`user?.name`) or an explicit guard clause..."

(120 tokens 说了一个空指针问题)

Caveman 的回答：

✅ L42: 🔴 bug: user null. Add guard.

(10 tokens。同一个问题。)

7.2 输出格式规范

L<行号>: <严重级别> <类型>: <一句诊断>. <修复建议>.

严重级别体系

graph LR
    subgraph Levels["严重级别"]
        A["🔴 bug
必须修复
会导致运行时错误"]
        B["🟡 warn
建议修复
潜在问题或性能陷阱"]
        C["🔵 nit
可选优化
代码风格或命名"]
        D["✅ ok
代码良好
无需修改"]
    end
    
    A --> B --> C --> D

7.3 实战：审查一段 Express 中间件

待审查代码：

// auth.middleware.js
const jwt = require('jsonwebtoken');
const db = require('./database');

module.exports = async (req, res, next) => {
  const token = req.headers.authorization;          // L6
  
  try {
    const decoded = jwt.verify(token, SECRET);       // L9
    const user = await db.findUser(decoded.id);      // L10
    req.user = user;                                 // L11
    req.userRole = user.role;                        // L12
    next();                                          // L13
  } catch (err) {
    res.status(401).json({ error: err.message });    // L15
  }
};

🪨 Caveman Review 输出：

L6:  🔴 bug: no Bearer prefix strip. `authorization` includes "Bearer ".
     Split: `token.split(' ')[1]`
L9:  🔴 bug: SECRET undefined. Should be `process.env.JWT_SECRET`.
L10: 🟡 warn: no user found check. `findUser` may return null → L12 crash.
L12: 🔴 bug: `user.role` throws if user null. Guard after L10.
L15: 🟡 warn: leaking jwt error details to client. Use generic message.
     `{ error: "Authentication failed" }`

Summary: 3 🔴 3 🟡. Auth middleware has critical null-safety gaps.

对比正常 Claude 的输出大约需要 500+ tokens，Caveman 只用了约 80 tokens 就完成了同样深度的审查。

7.4 各平台使用方式

Claude Code

# 审查当前的 staged changes
> /caveman-review

# 审查指定文件
> /caveman-review src/middleware/auth.js

# 审查一个 PR 的 diff
> 审查这个 PR 的改动，用 caveman-review 格式

Antigravity

# 自然语言触发
> 用 caveman-review 格式审查 src/middleware/auth.js

# 或者更简短
> review auth.js, caveman style, one line per issue

Gemini CLI

> /caveman-review
# 或
> /caveman-review src/middleware/auth.js

Codex

> $caveman-review
# 或审查指定文件
> $caveman-review src/middleware/auth.js

OpenCode

# 自然语言触发 (无斜杠命令)
> 审查当前改动，格式: L行号 + 级别(🔴🟡🔵) + 一句诊断

7.5 与 GitHub Actions 集成

将 caveman-review 集成到 CI/CD 中，让每个 PR 自动获得一行式审查：

# .github/workflows/caveman-review.yml
name: Caveman 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 files
        id: diff
        run: |
          echo "files=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | tr '\n' ' ')" >> $GITHUB_OUTPUT
      
      - name: Caveman Review
        uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Review these changed files using caveman-review format.
            Rules:
            - One line per issue: L<line>: <🔴|🟡|🔵> <type>: <diagnosis>
            - No throat-clearing, no pleasantries
            - End with summary: N 🔴 N 🟡 N 🔵
            
            Files: ${{ steps.diff.outputs.files }}
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

graph TD
    A["开发者提交 PR"] --> B["GitHub Actions 触发"]
    B --> C["获取 changed files"]
    C --> D["调用 Claude Code Action
+ caveman-review 规则"]
    D --> E["生成一行式审查意见"]
    E --> F["自动评论到 PR"]
    F --> G["开发者收到精炼反馈"]
    
    G -->|"修复后推送"| A

📊 五大平台 Review 工作流对比

💡 进阶技巧

只关注 Bug

> /caveman-review —— 只报告 🔴 级别的问题

按文件类型审查

> /caveman-review *.tsx  # 只审查 React 组件
> /caveman-review *.sql  # 只审查 SQL 文件

自定义审查维度

> /caveman-review 重点关注：安全漏洞、SQL 注入、XSS

📝 本期要点回顾

1. /caveman-review 输出格式：L行号: 🔴/🟡/🔵 类型: 一句诊断
2. 三个严重级别：🔴 bug(必修) / 🟡 warn(建议) / 🔵 nit(可选)
3. 同样深度的审查，Token 消耗降低 80%+
4. 可与 GitHub Actions 集成，实现 PR 自动审查
5. Codex 用 $caveman-review，Antigravity 和 OpenCode 用自然语言触发

🔗 参考资料

• Caveman Review Skill
• Claude Code Action (GitHub)
• Conventional Comments