L6-17：审查清单体系 —— 让代码审查像飞行员起飞前检查一样可靠

清单 = 审查质量的底线

没有清单的审查： → 取决于审查者当时的状态（累不累、熟不熟悉代码） → 每次审查覆盖的维度不一样 → 容易漏掉不熟悉的类别（比如 shell 注入） → 无法衡量审查的完整性 → 经验不可累积和传承

有清单的审查： → 每个维度都经过系统检查 → 不依赖审查者的"感觉" → 遗漏率大幅下降 → 清单本身可以持续改进（添加新发现模式） → 新人也能做到 80% 的审查覆盖率

gstack 的清单哲学： → 你是专家——清单帮你记住所有要查的东西 → 不是逐项打勾的机械操作，而是系统性的提醒系统 → DO NOT flag 部分和 DO flag 部分同等重要

为什么是两次 pass？

一次 pass 的问题： → 人的注意力是有限的——你会对"差不多"的东西疲劳 → 到第 20 个检查项时，你的标准已经漂移了 → 关键问题淹没在信息性问题中

双 pass 解决这个问题： → Pass 1（CRITICAL）：只关注最高严重度的问题 - 精力充沛时做最重要的判断 - 只检查 5 个类别 → Pass 2（INFORMATIONAL）：剩余的信息性类别 - 在关键 pass 做完后，用较低的认知负载扫描其余问题

类别划分的逻辑

CRITICAL = 会导致数据损坏、安全漏洞、服务中断的问题 SQL & Data Safety、Race Conditions、LLM Trust Boundary、 Shell Injection、Enum Completeness

INFORMATIONAL = 影响质量但不立即威胁系统的问题 Async/Sync Mixing、Column Name Safety、LLM Prompt Issues、 Completeness Gaps、Time Window Safety、Type Coercion、 View/Frontend、Distribution & CI/CD

SPECIALIST（子 Agent 处理） = 需要专门领域知识的深度检查 Testing、Maintainability、Security、Performance、 Data Migration、API Contract、Red Team

SQL & Data Safety

核心原则：永远不要让用户输入成为 SQL 语法的一部分。

常见错误模式： → "WHERE id = #{params[:id]}" （即使是 .to_i 也不行） → Model.where("status = '#{input}'") （字符串插值） → Model.connection.execute("SELECT ... #{interpolated}") → Model.update_column(:status, value) （跳过验证）

正确做法： → 参数化查询（Rails: sanitize_sql_array / Arel） → WHERE 子句使用数组形式（Rails: Model.where("status = ?", value)） → 使用 ORM 的内置方法，不用 raw SQL

Race Conditions & Concurrency

核心原则：任何"读取 → 判断 → 写入"的模式在并发下都会出问题。

关键发现模式： → hash = compute_hash(...); Model.where(hash: hash).first || Model.create!(hash: hash) → 缺失：唯一索引 + 重复键错误处理 → if record.status == 'draft'; record.update!(status: 'published') → 缺失：原子 WHERE 更新（record.update! 不如 Model.where(id: id, status: 'draft').update_all） → find-or-create 无 DB 唯一约束

LLM Output Trust Boundary

核心原则：LLM 的输出是不可信的——必须像对待用户输入一样对待 LLM 输出。

跨越边界时验证： → LLM → 数据库写入（格式验证、类型检查） → LLM → 邮件/通知（format 验证、长度限制） → LLM → URL fetch（白名单 hostname、SSRF 防护） → LLM → 知识库/向量 DB（消毒、注入防护）

Shell Injection (Python)

核心原则：永远不要用 shell=True + 用户/LLM 数据拼接命令字符串。

检查模式： → subprocess.run(f"cmd {user_input}", shell=True) → os.system(f"cmd {var}") → 正确做法：subprocess.run(["cmd", arg1, arg2])

Enum & Value Completeness

核心原则：新增一个枚举值 = 必须追踪所有消费这个枚举的地方。

操作步骤：

1. 用 Grep 找到所有引用兄弟值的地方
2. Read 每个匹配的文件
3. 检查 switch/case、if/elsif 链、白名单数组
4. 新值是否在任何消费者中被遗漏？
5. 这是唯一需要读取 diff 之外的代码的审查类别

不是"报告问题"，是"修复问题"

审查清单的目的不是生成报告——是改善代码。

分类决策树

AUTO-FIX 条件（满足任一即可）

✓ 死代码 / 未用变量 / 未用导入 ✓ N+1 查询（缺少 eager loading）——将 .includes 加到查询 ✓ 陈旧注释与代码矛盾 ✓ 魔数 → 命名常量 ✓ 缺少 LLM 输出验证——添加格式守卫 ✓ 版本/路径不匹配 ✓ 变量赋值后从未读取 ✓ 内联样式、O(n*m) 视图查找

ASK 条件（满足任一即可）

✗ 安全（auth、XSS、注入） ✗ 竞态条件 ✗ 设计决策 ✗ 大型修复（>20 行代码变更） ✗ 枚举完整性（语义判断） ✗ 删除功能（需要确认意图） ✗ 改变用户可见行为的任何修复

经验法则

如果修正可以写成一条规则"把 X 改成 Y"且永远不会错 → AUTO-FIX 如果修正在不同上下文中可能是不同的做法 → ASK

Critical 发现倾向于 ASK（固有风险更高） Informational 发现倾向于 AUTO-FIX（更机械）

DO NOT flag 的重要性和 DO flag 一样重要

过度标记的问题： → 噪音淹没有信号——审查者疲劳 → 打击开发者信心（"又是这些没用的 flag"） → 增加审查时间却不提高质量 → 标记无意义的问题降低整体信任度

抑制列表

不标记： → "X 与 Y 重复"——当冗余无害且提高可读性时 （如 present? 与 length > 20 冗余但作为文档存在） → "加个注释解释为什么选这个阈值/常量"——阈值在调优中变化， 注释会过时 → "这个断言可以更严格"——当断言已经覆盖行为时 → 建议纯一致性变更（"把这段包在条件里以匹配另一个常量的防护方式"） → "正则不处理边缘情况 X"——当输入受约束且 X 在实践中不会出现时 → "测试一次测了多个守卫"——测试不需要隔离每个守卫 → Eval 阈值变更——这些是经验调优的，经常变化 → 无害的 no-ops（如对数组中不存在的元素 .reject） → 你的审查 diff 中已经处理过的任何事——完整读 diff 再评论

设计清单的特有抑制

→ 第三方/vendor CSS 文件 → CSS reset 或 normalize 样式表 → 测试 fixture 文件 → 生成的/压缩的 CSS → DESIGN.md 中明确声明为有意的模式

设计清单是代码审查的一部分

design-checklist.md 被 review 中的 Design 专家使用：

AI Slop 检测（最高优先级）

六个 AI 生成 UI 的特征信号：

1. 紫色/蓝紫渐变背景
2. 3 列功能网格（彩色圆形图标 + 粗标题 + 2 行描述 × 3）
3. 彩色圆形图标作为区块装饰
4. 居中一切（>60% 的文本容器用 text-align: center）
5. 统一的泡泡圆角（>80% 元素用相同 ≥16px 的 radius）
6. 通用 Hero 文案（"Welcome to X"、"Unlock the power of..."）

其他类别

字体排版、间距与布局、交互状态、DESIGN.md 违反

置信度分层

→ [HIGH]：通过 grep/模式匹配可靠检测。确定性的发现。 → [MEDIUM]：通过模式聚合或启发式检测。标记但要预期噪音。 → [LOW]：需要理解视觉意图。呈现为"可能的——验证或运行 /design-review"

AUTO-FIX vs ASK（设计上下文）

AUTO-FIX（仅机械 CSS 修复——HIGH 置信度且无设计判断）： → outline: none 无替代 → outline: revert 或 focus-visible 环 → 新 CSS 中的 !important → 删除并修复 specificity → body 文本 font-size < 16px → 升至 16px ASK（其余一切——需要设计判断）

清单不是一成不变的

清单应该持续演化：

何时添加新类别

→ 在审查中反复发现某个模式被漏掉 → 新增了一种之前没考虑过的漏洞类型 → 一种新的 AI 生成反模式（slop 模式）出现

何时移除或调整

→ 某类发现总是误报（低信号、高噪音） → 框架/语言更新让某个模式不再适用 → 抑制规则中描述的情况变得普遍

学习的闭环

→ 每次审查都是学习机会 → 如果用户对某类标记说"这不是问题"→ 记录为 learning → 如果漏掉了某个严重问题 → 分析为什么漏掉 → 更新清单 → 审查清单本身是知识积累的容器

审查清单体系型 Skill 模板

核心特征

→ 管理对象 = 代码审查的检查项系统——审查的"底线"和"记忆辅助" → 核心原则 = 双 Pass 分离（CRITICAL vs INFORMATIONAL 注意力分配）+ Fix-First 行动导向 + 抑制优先（降噪比增项更重要） → 关键设计 = 5 类 CRITICAL 检查项、8 类 INFORMATIONAL 检查项、 AUTO-FIX vs ASK 决策树、抑制规则体系、清单演化机制

通用结构

Dual-Pass Architecture（双 Pass 架构）

• Pass 1 CRITICAL（5 类，精力充沛时检查）： SQL & Data Safety / Race Conditions / LLM Trust Boundary / Shell Injection / Enum Completeness
• Pass 2 INFORMATIONAL（8 类，低认知负载扫描）： Async/Sync / Column Safety / LLM Prompt / Completeness Gaps / Time Window / Type Coercion / View / CI/CD
• 设计原理：人的注意力是最稀缺的资源——关键问题不在信息噪音中稀释

Fix-First Decision Tree（Fix-First 决策树）

• 两条判断链：机械的吗？→ 高级工程师会不假思索应用吗？
• AUTO-FIX：死代码、N+1 查询、魔数→常量、缺少 LLM 验证、版本不匹配、内联样式
• ASK：安全、竞态、设计决策、>20 行修复、枚举完整性、改变用户行为
• 经验法则：能写成"把 X 改成 Y"永不错 → AUTO-FIX；上下文相关 → ASK

Suppression Rules（抑制规则体系）

• DO NOT flag 和 DO flag 同等重要
• 抑制：有害冗余（文档性代码）、调优阈值、受约束输入的边缘情况、无害 no-ops
• 设计特有抑制：第三方 CSS、reset/normalize、测试 fixture、生成/压缩 CSS
• 噪声率控制目标：< 10%（误报超过 30% 时工程师学会忽略所有标记）

Checklist Evolution（清单演化机制）

• 添加：反复漏掉的模式、新漏洞类型、新 AI slop 模式
• 移除：低信号高噪音类别、框架更新后不再适用
• 学习闭环：用户说"不是问题"→ learning、漏掉严重问题 → 分析 → 更新