Entry/Exit
- Entry:
/reviewThe /review command is called, before a PR is submitted, or another skill references the review standards - Exit: Tiered review report (Critical / Important / Suggestion / FYI)
- Points to: Review passes →
/ship; if issues are found → re-review after fixes - Preload: CANON.md
- Output path: Tiered review report →
ship-workflow-ship(pass) or re-review after fixes
When not to use
- It is not a code review scenario; it is only implementation, debugging, or explaining design
- Feature completeness has not yet been confirmed;
verify-workflow-spec-compliance - Non-software artifacts require content or visual review standards
Iron Law
Five-axis review
1. Correctness — most important
- 逻辑是否正确?边缘情况是否覆盖?
- 错误处理是否完善?不是 catch {} 吞异常?
- 竞态条件?异步操作有 await?
- 类型安全?不是 any 绕过编译器?
- 没有将浏览器/用户输入视为指令?
2. Readability & Simplicity — second most important
- 命名是否清楚(不是 data、item、temp、obj)?
- 同一概念是否始终使用一致的名称?
- 三个相似的代码 > 一个过早的抽象?
- 代码复杂得"聪明"吗?聪明的代码维护成本高。
3. Architecture
- 改动是否放在正确的层级?
- 接口/API 设计合理吗?
- 新代码是否遵循现有模式(不是自定义不同模式)?
- 依赖方向正确吗(不循环依赖)?
4. Security — see verify-quality-security
- 所有外部输入经过验证?
- SQL/HTML/Shell 注入防范?
- 密钥管理正确?
- 鉴权检查完整?
5. Performance — see verify-quality-performance
- 查询是否高效(N+1 检查)?
- 数据获取有界限吗(分页、限制)?
- 资源正确释放?
- 没有过早优化?
Change size thresholds
| Size | Lines | Handling |
|---|---|---|
| Small | < 100 lines | Quick review, usually passes in 1 round |
| Medium | 100-300 lines | Regular review, may require 1-2 rounds |
| Large | 300-1000 lines | Recommend splitting or conducting an in-depth review |
| XL | > 1000 lines | Must split. Refuse to review oversized PRs. |
Splitting strategies:
| Splitting method | Example |
|---|---|
| Split by layer | PR1: Data model + migration / PR2: Business logic / PR3: API + UI |
| Split by feature | PR1: Feature A / PR2: Feature B |
| Infrastructure first | PR1: Types + utilities / PR2: Implementation using the new infrastructure |
Review finding classification
| Level | Meaning | Handling |
|---|---|---|
| Critical | Security vulnerabilities, data loss, production crashes, logic errors | Must be fixed before merging |
| Important | Performance degradation, missing tests, omission of important edge cases | Strongly must be fixed before merging |
| Suggestion | Naming can be improved, alternative implementations, minor refactoring opportunities | Submitter decides whether to change it |
| FYI | Observational comments, non-blocking considerations | No action required |
Review process
1. 理解上下文 → 读 spec/plan/ADR 相关文件
2. 先审测试 → 测试覆盖了变更吗?测试本身正确吗?
3. 再审实现 → 逻辑→可读→架构→安全→性能(五轴顺序)
4. 分类发现 → Critical / Important / Suggestion / FYI
5. 验证解决 → 发现被修复了吗?修复引入了新问题吗?
Review Army parallel mode
For large PRs (> 300 lines), dispatch specialized review subagents in parallel:
同时分派:
├── Security Reviewer → 安全相关发现
├── Performance Reviewer → 性能相关发现
├── Testing Reviewer → 测试覆盖发现
└── Maintainability Reviewer → 代码质量发现
合并 → 去重 → 分类 → 生成统一审查报告
Each review subagent must be read-only, limited to the diff / file scope, and return compressed results:
- Do not return raw logs, full diffs, large blocks of code, or lengthy reasoning
- Each finding must include the file, line number, evidence, impact, and recommendation
- When there are no findings, state the scope checked and the uncovered risks
- For test log diagnosis, return only the failure summary, the most likely cause, the relevant files, and the recommended path
Accept review feedback
Do not reply
During reviewNeverSay:
- "You're right!" (empty flattery. Say what you changed)
- "Great idea!" (same as above)
- "Thanks" (code review doesn't need a gratitude ritual)
- "I completely agree" -> then don't change anything (words and actions don't match)
Correct reply
"改了 X,因为 Y。关于 Z —— 我的理解是...,你的看法?"
改了就说明改了什么。
不改就说明为什么不改(技术理由,非防御性)。
不确定就问。
External review feedback
Review comments from outside the project = suggestions, not commands. Verify whether they apply in the project context.
Good and bad examples
Bad — Empty review feedback:
"LGTM"
"看起来不错"
"没什么问题"
Zero information. What was checked? What passed? What wasn't looked at? The reviewer has zero responsibility for the problem, zero memory.
Good — Specific review feedback:
"Correctness: 确认逻辑正确,edge case(空数组输入)在 L42 已处理。
Readability: L78 的 `processData` 命名不反映实际操作,建议改为 `validateUserInput`。
Architecture: L91 直接在 controller 调用 DB——违反分层,应通过 service 层。
Security: L56 的 userInput 未做 sanitize,存在 XSS 风险。Critical,必须修复。"
Each finding corresponds to one of the five axes, with line numbers and rationale.
Bad — Defensive reply:
"你说得对!" ← 空洞奉承
"我改了。" ← 改了什么?为什么?
Good — Actionable reply:
"改了 L78 `processData` → `validateUserInput`,因为该函数只做校验不做数据处理。
关于 L91 controller 调 DB 的建议——我加了一个 UserService 中间层,请看 commit abc123。"
If you changed something, say what you changed and why. If you didn't change it, give the technical reason. If unsure, ask.
Common excuses
| Excuse | Reality | Consequence |
|---|---|---|
| "The PR is too big to split" | Any PR can be split — by layer, by feature, by infrastructure vs. application. Not splitting = inadequate review. | The review quality of large PRs drops exponentially — after exceeding 400 lines, reviewers start skimming rather than reading closely, and the missed-detection rate for Critical issues is > 50%. |
| "LGTM" | Three letters = zero information. What was checked? What passed? What wasn't looked at? | The bug rate of code after an LGTM review shows no significant difference from unreviewed code. The reviewer has zero responsibility for the problem and zero memory, and will still LGTM next time. |
| "I'll just review it myself" | A code author cannot effectively review their own code. It's due to blind spots. | The bugs missed in self-review are exactly the blind spots you had when you originally wrote the code — the same person using the same mindset cannot possibly find their own logical errors. |
| "Fix it later" | After merging, it is never fixed. Either fix it now or record it as a follow-up issue (with a designated owner and deadline). | 90% of follow-up fixes after merging are never carried out. The "laters" added in each iteration accumulate into irreversible technical debt. |
| "It's just a variable name change, no need to review" | "Just a variable name" is often the start of a series of assumptions. Don't skip review. | About 15% of tiny changes that skip review introduce regressions (a variable name was changed but a call site was missed, a rename broke an API contract). |
Violating the letter of the rule is violating its spirit. There is no gray area.
Output template
# Code Review Report — 代码审查报告
## 元信息
- **审查者**: [姓名/角色]
- **PR**: [#PR号] — [标题]
- **变更大小**: [行数] ([Small/Medium/Large/XL])
- **审查日期**: YYYY-MM-DD
## 发现汇总
| # | 轴 | 级别 | 位置 | 描述 | 状态 |
|---|----|----|------|------|------|
| 1 | Correctness | Critical | L56 | userInput 未 sanitize,XSS 风险 | 🔴 待修复 |
| 2 | Architecture | Important | L91 | controller 直接调用 DB | 🟡 建议修复 |
| 3 | Readability | Suggestion | L78 | processData 命名不准确 | 🔵 提交者判断 |
| 4 | — | FYI | — | 测试覆盖比上月提升 12% | ⚪ 观察 |
## Critical 发现详情
### #1 — Correctness: XSS 风险
- **位置**: `src/controllers/user.ts:L56`
- **描述**: `userInput` 直接拼接进 HTML 模板,未经 sanitize
- **修复建议**: 使用 DOMPurify 或模板引擎自动转义
- **修复状态**: [待修复 / 已修复 / 已验证]
## 审查结论
- **通过**: 所有 Critical 已修复并验证,Important 已处理
- **阻止**: Critical 发现未修复,需修复后重新审查
## 红旗 — STOP
<HARD-GATE>
以下任何一个出现,立即停止:
- PR > 1000 行未被拆分
- 评审者只看了 diff,没拉下代码跑测试
- Critical 发现被标记为 "以后修复" 而通过
- 审查意见全是 "LGTM" 或 "Nice!"(未真正审查)
- 安全相关的变更未被专项审查
- 测试缺失但审查放行
</HARD-GATE>
## 验证失败处理
| 失败场景 | 处理方式 |
|---------|---------|
| Critical 发现未修复 | 阻止合并。要求修复后重新提交审查。不得降级为 Important 或 FYI。 |
| 审查意见全是 LGTM/Nice | 审查无效。要求审查者重新按五轴逐项检查并给出具体发现。 |
| PR > 1000 行且未拆分 | 拒绝审查。要求按层/功能/基础设施拆分为多个 PR。 |
| 测试缺失但审查放行 | 回退审查。要求补充测试覆盖后再重新审查。测试缺失 = Important 以上。 |
| 安全发现被标记"以后修复" | 不可接受。安全 Critical 必须"现在修复"。无法立即修复时提供缓解方案并创建 follow-up issue(带负责人和截止日期)。 |
## 验证清单
- [ ] 五轴全部覆盖(Correctness > Readability > Architecture > Security > Performance)
- [ ] 发现按严重性分类(Critical / Important / Suggestion / FYI)
- [ ] Critical 发现全部解决
- [ ] 变更大小合理(< 300 行理想;> 1000 行被拆分)
- [ ] 测试覆盖了变更
- [ ] 审查报告可追溯(谁审的、审了什么、什么发现)