AI 辅助代码审查与团队协作

Code Review 是团队协作的核心环节——它不只是找 Bug，更是知识传递、标准对齐、架构守护的过程。AI 不能替代人类做架构判断，但可以接管 Code Review 中最机械的部分：检查代码规范、发现常见反模式、验证类型安全、评估测试覆盖。本章构建一套 AI 辅助的 Code Review 体系，让人类审查者专注于更高层次的判断。

1. AI Code Review 工作流

1.1 两阶段审查

PR 提交
  ↓
第一阶段：AI 自动审查（3-5 分钟）
  ├── 代码规范检查
  ├── 常见反模式检测
  ├── SSR 安全性扫描
  ├── 类型安全性评估
  ├── 性能风险标记
  └── 测试覆盖率检查
  ↓
第二阶段：人工审查（AI 已过滤低级问题）
  ├── 架构合理性
  ├── 业务逻辑正确性
  ├── 产品需求对齐
  └── 代码可维护性

AI 处理第一阶段后，人工审查时不需要再纠结"这个变量应该用 camelCase"或"这里缺少错误处理"——这些 AI 已经标记了。

1.2 GitHub Actions 集成

# .github/workflows/ai-review.yml
name: AI Code Review
 
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  ai-review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Get PR diff
        id: diff
        run: |
          git diff origin/main...HEAD > pr.diff
          echo "diff_file=pr.diff" >> $GITHUB_OUTPUT
 
      - name: AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx @anthropic-ai/claude-code --print \
            "Review the following PR diff for a Nuxt 4 project.
             
             Check for:
             1. SSR safety (browser API usage without guards)
             2. N+1 database queries
             3. Missing error handling in API routes
             4. Missing Zod validation
             5. TypeScript any usage
             6. Nuxt anti-patterns (manual imports of auto-imports)
             
             Format: markdown with severity (critical/warning/info)
             
             $(cat pr.diff)" > review.md
 
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs')
            const review = fs.readFileSync('review.md', 'utf8')
            await github.rest.pulls.createReview({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number,
              body: review,
              event: 'COMMENT'
            })

2. 审查规则体系

2.1 Nuxt4 专属审查规则

## AI Review Checklist for Nuxt 4
 
### Critical（必须修复）
- [ ] 使用了 `process.client` 而不是 `import.meta.client`
- [ ] 在 `onMounted` 内调用 `useFetch` / `useAsyncData`
- [ ] API 路由缺少认证检查（`requireAuth`）
- [ ] POST/PUT 路由缺少 Zod 输入校验
- [ ] 直接在组件中执行数据库查询
- [ ] `v-html` 渲染用户输入
 
### Warning（建议修复）
- [ ] 手动 import 了 Nuxt 自动导入的函数
- [ ] 使用 `ref()` 而不是 reactive props destructure
- [ ] 缺少 loading / error 状态处理
- [ ] 列表接口缺少分页
- [ ] 缺少 TypeScript 类型（使用了 `any`）
 
### Info（了解即可）
- [ ] 组件超过 300 行（建议拆分）
- [ ] API 路由可以使用 `defineCachedEventHandler` 缓存
- [ ] 可以使用 `useSeoMeta` 优化 SEO

2.2 自定义审查规则

团队可以在 .ai/review-rules.md 中定义项目特定的审查规则：

# Project-Specific Review Rules
 
## API Response Format
All API endpoints must return:
- Success: `{ data: T }` or `{ items: T[], total: number }`
- Error: throw `createError({ statusCode, message })`
- Never return raw database rows (map to response types)
 
## Video Processing
- All video operations must be async (queue-based)
- Never process video synchronously in API handlers
- Always validate file type before starting upload
 
## Auth
- Admin APIs must use `requirePermission('xxx')`
- User-facing APIs must use `requireAuth(event)`
- Public APIs must be explicitly marked (no auth middleware)

3. 质量评估

3.1 代码质量评分

让 AI 对每个 PR 给出结构化的质量评分：

## PR Quality Score
 
| 维度 | 分数 | 说明 |
|------|------|------|
| **类型安全** | 9/10 | 所有函数有类型标注，无 any |
| **错误处理** | 7/10 | API 路由有处理，但 composable 缺少 |
| **SSR 安全** | 10/10 | 所有浏览器 API 有 client guard |
| **性能** | 8/10 | 查询有索引，但缺少缓存 |
| **可读性** | 8/10 | 命名清晰，但缺少关键注释 |
| **测试覆盖** | 6/10 | 有单元测试，缺少边界用例 |
 
**总分：8.0/10**
 
### 建议改进
1. 🔴 composables/useVideoFilter.ts:23 - catch 块只打了 console.error，应该用 toast 通知用户
2. 🟡 server/api/search.get.ts - 热门搜索应使用 defineCachedEventHandler
3. 🟢 可以为 VideoFilter 添加 URL query 同步，提升用户体验

3.2 复杂度分析

对以下文件进行复杂度分析：
@composables/useVideoPlayer.ts

评估：
1. 函数数量和平均行数
2. 依赖数量（import 了多少外部模块）
3. 分支复杂度（if/else/switch 层级）
4. 是否应该拆分

4. 团队规范执行

4.1 新人代码的 AI 辅导

新人的 PR 可以配置更详细的 AI 审查：

# 根据 PR 作者调整审查严格度
ai-review:
  strictness:
    new-members: detailed    # 详细解释每个问题
    team-members: standard   # 只标记问题
    senior: minimal          # 只标记 critical

详细模式的审查输出会包含为什么和怎么修：

### 问题：在 onMounted 中使用 useFetch
 
**文件**: pages/search.vue:15
**严重度**: Critical
 
**代码**:
```vue
onMounted(async () => {
  const { data } = await useFetch('/api/search')
})

问题: useFetch 是 Nuxt 的 composable，必须在 <script setup> 的顶层同步调用，不能在 onMounted 或其他生命周期钩子中调用。 这会导致 SSR 时数据无法正确序列化到客户端。

修复:

&lt;script setup&gt;
const query = ref('')
const &#123; data &#125; = await useFetch('/api/search', &#123;
  query: &#123; q: query &#125;,
&#125;)
&lt;/script&gt;

### 4.2 规范一致性追踪

定期用 AI 扫描整个代码库，检查规范一致性：

```bash
$ claude "扫描整个项目，列出所有不符合以下规范的代码：

1. API 路由缺少 Zod 校验的 POST/PUT 处理器
2. 组件中手动 import 了 ref/computed/watch
3. 使用了 process.client 而不是 import.meta.client
4. API 路由没有使用 requireAuth 但应该有认证

输出格式：
文件路径:行号 - 违规类型 - 建议修复方式"

5. 效率度量

5.1 开发效率指标

指标定义目标
PR Review 时间从提交到 Approve 的时间< 4 小时
AI 修复率AI 审查问题中被采纳的比例> 70%
首次通过率PR 首次提交就通过审查的比例> 60%
代码返工率需要修改的 PR 比例< 30%

5.2 AI 工具使用追踪

## 周度 AI 使用报告
 
### 本周使用统计
- Cursor 活跃时间：32 小时
- Claude Code 任务数：8 个
- AI 自动修复 Issue：3 个
- AI 审查发现问题：47 个（采纳 35 个，74%）
 
### 效率提升
- 平均 PR Review 时间：2.1 小时（上周 3.5 小时，↓40%）
- 代码首次通过率：68%（上周 52%，↑16%）
- AI 检出的 Critical 问题：5 个（人工可能遗漏）
 
### 需要改进
- AI 误报率偏高（26%），需要优化审查规则
- composable 测试覆盖仍不足，考虑用 AI 补充

5.3 ROI 评估

AI 工具月度成本：
- Cursor Pro: $20 × 3 人 = $60
- Claude Code API: ~$150
- GitHub Copilot: $10 × 2 人 = $20
总计：$230/月

效率收益估算：
- PR Review 时间节省：15 小时/月 × $50/小时 = $750
- Bug 预防（AI 检出的 Critical）：5 个 × $200/Bug = $1000
- 代码规范统一（减少返工）：8 小时/月 × $50/小时 = $400
总收益：$2150/月

ROI = ($2150 - $230) / $230 = 835%

6. AI 辅助测试

6.1 测试覆盖率门禁

# PR 合并条件
merge_requirements:
  test_coverage:
    statements: 80%
    branches: 70%
    functions: 80%
    lines: 80%
  # 新增代码覆盖率必须 >= 项目整体覆盖率
  new_code_coverage: ">= project_average"

6.2 AI 补充测试

当 PR 的测试覆盖率不足时，可以让 AI 自动补充：

$ claude "检查这个 PR 的测试覆盖率：
- 运行 pnpm test:coverage
- 找到新增代码中未覆盖的分支
- 为未覆盖的代码编写测试
- 确保所有测试通过
 
不要修改现有测试，只添加新测试。"

6.3 测试质量审查

AI 不只检查测试覆盖率，还检查测试质量：

### 测试质量问题
 
1. **快照测试过度使用**
   - tests/VideoCard.test.ts 有 5 个快照测试
   - 快照测试容易 auto-update，失去保护意义
   - 建议：改为针对性的断言
 
2. **缺少边界用例**
   - useChunkUpload 只测试了成功路径
   - 缺少：网络中断、文件过大、无效类型的测试
 
3. **测试命名不清晰**
   - `it('should work')` → `it('should toggle favorite when clicking button')`

本章小结

  • 两阶段审查：AI 自动处理规范/反模式检查，人工专注架构/业务/可维护性
  • GitHub Actions：CI 中集成 AI Review，每个 PR 自动审查，输出结构化报告
  • 审查规则：Nuxt4 专属的 Critical/Warning/Info 三级规则 + 项目自定义规则
  • 质量评分：六维度评分（类型安全/错误处理/SSR/性能/可读性/测试），给出可操作的改进建议
  • 效率度量：追踪 Review 时间、AI 修复率、首次通过率，量化 AI 工具的 ROI
  • 测试辅助：AI 补充缺失测试、检查测试质量、确保覆盖率门禁