何时做代码审查、如何产出可执行的分级评审报告

在评审 PR、做代码质量审计、找重构机会或排查安全漏洞时，用一套「先理解意图、再审结构/细节/测试、最后分级反馈」的流程产出结构化评审报告。

适用场景

解决思路

1. 先读 PR 描述、理解要解决的问题；进入审查前必须能用一句话总结该 PR 的意图，若总结不出来就先让作者澄清。
2. 审结构与设计：判断改动是否遵循代码库既有模式，新增的抽象是否有必要。
3. 审细节：检查代码质量、安全与性能，具体排查 N+1 查询、硬编码密钥、注入风险。
4. 审测试：验证测试覆盖度与质量，检查边界情况是否覆盖，测试是否断言行为而非实现细节。
5. 产出分类报告（按 Output Template）；若在细节审查阶段就发现严重问题，立即指出，不要等到最后才说。
6. 遇到分歧时：作者已对非显而易见的选择留下说明时，先认可其理由，再提出替代方案。
7. 已配置 linter/formatter 时，不要因风格偏好阻塞合并。
8. 按上下文加载对应参考文档：开始审查或确定分类时加载 references/review-checklist.md；遇到 N+1 查询、魔法数字等模式问题时加载 references/common-issues.md；撰写反馈时加载 references/feedback-examples.md；写最终报告时加载 references/report-template.md；审查实现、做 PR 评审或核对规格时加载 references/spec-compliance-review.md；回应评审意见、处理反馈时加载 references/receiving-feedback.md。
9. N+1 查询的改法：不要在循环里逐条查询（如 for user in users: Order.objects.filter(user=user)），改为批量预取（如 User.objects.prefetch_related('orders').all()）。
10. 魔法数字的改法：不要写 if status == 3，改为定义常量（如 ORDER_STATUS_SHIPPED = 3）后再比较。
11. SQL 注入的改法：不要用字符串插值拼 SQL（cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")），改为参数化查询（cursor.execute("SELECT * FROM users WHERE id = %s", [user_id])）。
12. 必须做到的：审查前先一句话总结 PR 意图；给出具体、可执行的反馈；建议中附代码示例；表扬好的模式；按 严重→次要 排序反馈；审测试要和审代码一样认真；以 OWASP Top 10 为基线检查安全问题。
13. 禁止做的：态度居高临下或粗鲁；在有 linter 时纠结风格；以个人偏好阻塞合并；要求完美；不理解 why 就开始审查；跳过对良好实现的表扬。
14. 报告必须包含 7 部分：Summary（一句话意图回顾 + 总体评价）、Critical issues（合并前必须修：bug、安全、数据丢失）、Major issues（应该修：性能、设计、可维护性）、Minor issues（可选：命名、可读性）、Positive feedback（具体指出做得好的模式）、Questions for author（需要澄清的点）、Verdict（Approve / Request Changes / Comment）。
15. 审查时可参照的知识基线：SOLID、DRY、KISS、YAGNI、设计模式、OWASP Top 10、语言惯用法、测试模式。

适用边界 · 注意事项

• 已配置 linter/formatter 时，不要用它去纠结代码风格问题。
• 没有理解改动意图（why）时不要开始审查。
• 需要深度安全专项或测试专项审查时，应改用 security-reviewer、test-master 等专用技能，本技能只做单轮广覆盖审查。