code-review-quality

代码审查质量

<default_to_action> 审查代码或制定审查规范时：

1. 按优先级提供反馈： 🔴 阻断项（必须修复）→ 🟡 重大问题 → 🟢 次要问题 → 💡 建议
2. 重点关注： Bug、安全性、可测试性、可维护性（而非风格偏好）
3. 多提问，少命令： “是否考虑过……？” > “把它改成……”
4. 提供背景： 说明这样做的重要性，而不只是指出要改什么
5. 控制范围： 每次审查少于 400 行，以提高效率

快速审查清单：

• 逻辑：是否能正确运行？是否处理了边界情况？
• 安全性：是否验证了输入？是否进行了身份验证检查？是否存在注入风险？
• 可测试性：能否进行测试？是否已经测试？
• 可维护性：命名是否清晰？职责是否单一？是否遵循 DRY 原则？
• 性能：是否存在 O(n²) 循环？N+1 查询？内存泄漏？

成功的关键因素：

• 审查代码，而非审查开发者
• 发现 Bug > 挑剔代码风格
• 快速反馈（< 24 小时）> 全面反馈 </default_to_action>

快速参考卡

适用场景

• PR 代码审查
• 结对编程反馈
• 制定团队审查规范
• 指导开发者

反馈优先级

级别	图标	含义	处理方式
阻断项	🔴	Bug/安全问题/崩溃	合并前必须修复
重大问题	🟡	逻辑问题/测试缺失	应在合并前修复
次要问题	🟢	风格/命名	可以修复
建议	💡	替代方案	可在以后考虑

审查范围限制

变更行数	建议
< 200	单次审查
200-400	分块审查
> 400	请求拆分 PR

重点关注内容

✅ 审查	❌ 跳过
逻辑正确性	格式（使用 linter）
安全风险	命名偏好
测试覆盖率	架构争论
性能问题	风格意见
错误处理	细微改动

---

反馈模板

阻断项（必须修复）

🔴 **BLOCKER: SQL Injection Risk**

This query is vulnerable to SQL injection:
```javascript
db.query(`SELECT * FROM users WHERE id = ${userId}`)

修复方法： 使用参数化查询：

db.query('SELECT * FROM users WHERE id = ?', [userId])

原因： 将用户输入直接拼接到 SQL 中，会允许攻击者执行任意查询。

### Major (Should Fix)
```markdown
🟡 **MAJOR: Missing Error Handling**

What happens if `fetchUser()` throws? The error bubbles up unhandled.

**Suggestion:** Add try/catch with appropriate error response:
```javascript
try {
  const user = await fetchUser(id);
  return user;
} catch (error) {
  logger.error('Failed to fetch user', { id, error });
  throw new NotFoundError('User not found');
}

### Minor (Nice to Fix)
```markdown
🟢 **minor:** Variable name could be clearer

`d` doesn't convey meaning. Consider `daysSinceLastLogin`.

建议（可考虑）

💡 **suggestion:** Consider extracting this to a helper

This validation logic appears in 3 places. A `validateEmail()` helper would reduce duplication. Not blocking, but might be worth a follow-up PR.

---

可提出的审查问题

逻辑

• 当 X 为 null/空值/负值时会发生什么？
• 这里是否存在竞态条件？
• 如果 API 调用失败会怎样？

安全性

• 是否验证/清理了用户输入？
• 是否进行了身份验证检查？
• 是否暴露了机密信息或个人身份信息（PII）？

可测试性

• 你会如何测试这段代码？
• 依赖项是否可以注入？
• 是否测试了正常路径和边界情况？

可维护性

• 下一位开发者能理解这段代码吗？
• 这段代码是否承担了过多职责？
• 是否存在可以减少的重复代码？

最低发现项要求

审查的加权发现项得分必须至少达到 3.0（CRITICAL=3、HIGH=2、MEDIUM=1、LOW=0.5、INFORMATIONAL=0.25）。如果初次审查未达到要求，请运行 qe-devils-advocate agent，让其作为元审查者寻找更多发现项。每次审查至少应有 3 条可执行的观察意见。

---

Agent 辅助审查

// Comprehensive code review
await Task("Code Review", {
  prNumber: 123,
  checks: ['security', 'performance', 'testability', 'maintainability'],
  feedbackLevels: ['blocker', 'major', 'minor'],
  autoApprove: { maxBlockers: 0, maxMajor: 2 }
}, "qe-quality-analyzer");

// Security-focused review
await Task("Security Review", {
  prFiles: changedFiles,
  scanTypes: ['injection', 'auth', 'secrets', 'dependencies']
}, "qe-security-scanner");

// Test coverage review
await Task("Coverage Review", {
  prNumber: 123,
  requireNewTests: true,
  minCoverageDelta: 0
}, "qe-coverage-analyzer");

---

Agent 协作提示

记忆命名空间

aqe/code-review/
├── review-history/*     - Past review decisions
├── patterns/*           - Common issues by team/repo
├── feedback-templates/* - Reusable feedback
└── metrics/*            - Review turnaround time

多 Agent 协作

const reviewFleet = await FleetManager.coordinate({
  strategy: 'code-review',
  agents: [
    'qe-quality-analyzer',    // Logic, maintainability
    'qe-security-scanner',    // Security risks
    'qe-performance-tester',  // Performance issues
    'qe-coverage-analyzer'    // Test coverage
  ],
  topology: 'parallel'
});

---

审查礼仪

✅ 应做	❌ 不应做
“是否考虑过……？”	“这不对”
说明为什么重要	只说“修复这个”
肯定优秀代码	只指出负面问题
提出建议，而非强求	居高临下
审查少于 400 行	一次审查 2000 行

---

相关技能

• agentic-quality-engineering - Agent 协作
• security-testing - 安全审查深度
• refactoring-patterns - 可维护性模式

---

记住

优先处理反馈： 🔴 阻塞问题 → 🟡 重大问题 → 🟢 次要问题 → 💡 建议。重点关注 Bug 和安全问题，而非风格。提问，不要下命令。每次审查不超过 400 行。快速反馈（< 24 小时）胜过全面审查。

使用 Agent： Agent 可以自动执行安全、性能和覆盖率检查，让人工审查者专注于逻辑和设计。使用 Agent 进行一致、快速的初步审查。

技能组合

• 安全问题 → 结合 /security-testing 进行安全重点审查
• 覆盖率检查 → 对已更改的文件运行 /qe-coverage-analysis
• 交付决策 → 将审查结果交给 /qe-quality-assessment

注意事项

• Agent 一次审查超过 400 行时容易遗漏问题——每次审查最多分成 200–400 行
• 只挑剔风格却漏掉逻辑 Bug，是 Agent 审查最常见的失败原因——正确性优先于格式
• Agent 可能会批准能编译但存在微妙竞态条件的代码——务必检查共享状态和异步模式
• 没有修复建议的审查评论毫无帮助——务必附上建议的替代方案
• Agent 不会检查 PR 是否真正解决了关联的问题——请确认描述的问题确实已修复