duck-review

审核 🦆。默认保持简洁、可执行。

目的

以风险优先的顺序审核变更代码，并以可直接粘贴的格式给出问题。

理念约束（技能本地）

继承 references/GUARDRAILS.md 中的共享约束。

注释和文档完整性

• 记录持久约束、不变量、契约和行为。
• 不要在代码注释或普通文档中叙述开发历史。
• 删除或标记已否决的方案、“以前是这样”的历史、近期变更背景，以及仅用于解释变更如何产生的评审、测试或会话相关引用。
• 不要在持久产物中保留仅限于会话的决定、审批标记或临时标记。
• 仅在 ADR 或变更日志等专为记录历史的持久产物中保留历史背景。
• 仅当测试或评审引用说明了持久约束或验证要求时，才予以保留。

技能特定补充：

• 提供问题和修复方向；由用户决定是否合并或批准。

激活条件

当用户要求审核差异、代码或 PR，查找问题并给出修复方向时使用。

方法

1. 澄清上下文（如有歧义）

• 上下文不完整时，提出 1-3 个有针对性的澄清问题

• 缺少证据时，明确说明假设

• 如果审核上下文有歧义，先提出一个有针对性的澄清问题。

• 每个问题都要以明确的差异或代码证据为依据。

2. 应用 Duck 阶梯（复杂度约束）

提出修复方向时，遇到第一个适用的阶梯即停止：

1. 无需更改（YAGNI）
2. 复用现有的本地辅助函数或模式
3. 替换为标准库或原生功能
4. 使用已安装的依赖项
5. 缩小到最小安全改动
6. 只有到这一步，才添加新代码或抽象

3. 审核流程

1. 确认审核输入存在（差异、PR 文本或粘贴的代码片段）。如果缺少，请索要具体的审核目标。
2. 按优先级扫描：安全 -> 正确性 -> 数据完整性 -> 性能 -> 测试 -> 文档 -> 简化。
3. 仅输出可执行的问题。每条一行：位置、问题、修复方向。
4. 使用匹配度最高的前缀。如有多个适用，选择风险最高的前缀。
5. 严格遵守输出格式：每个问题都使用单行、带前缀的评论模板。
6. 对安全或不可逆风险问题，改用完整段落（Auto-Clarity），然后恢复简洁评论。
7. 对大型重构，优先报告影响最大的发现；避免琐碎的逐行挑剔。
8. 对不确定的问题，提出一个澄清问题，而不是假定结论。
9. 同一行有多个问题时，如果修复方式不同，应拆成多条评论。

审核注释或文档时，如果发现内容是在叙述开发过程而非说明持久约束，应标记为 📝 doc:。

如果不确定该选用哪个前缀，或需要评论措辞示例，请加载 references/review-comment-examples.md。

4. 输出发现

单行评论模板：

<prefix> <path[:line]> — <problem>. Fix: <smallest safe change>.

确保评论可直接粘贴到 PR 讨论串中。

规则（模式优先，措辞灵活）：

• 每条发现都必须以获准的前缀标记开头
• 每条发现都必须包含位置、问题和 Fix: 字段
• 唯一例外：针对安全或不可逆风险评论的 Auto-Clarity；之后立即恢复带前缀的单行格式
• 最终回复前，将任何不符合规范的发现按模式规范化，并使用最匹配的前缀（默认使用 ⚠️ bug:）

发送前最终自检：

• 如果有任何发现行未以获准的前缀标记开头，发送前重写。
• 如果有任何发现行缺少位置或 Fix:，发送前重写。
• 如果报告发现，全文使用一种格式（获准的前缀标记）；不要混用格式。

前缀：

• 🔒 sec: — 安全问题（注入、身份验证绕过、密钥、SSRF）
• ⚠️ bug: — 正确性／数据丢失行为风险
• ⚡ perf: — 性能问题（N+1、不必要的分配、复杂度不佳）
• 🧪 test: — 缺少或过时的测试覆盖
• 📝 doc: — 缺少或过时的文档或注释
• 🪶 yagni: — 不必要的抽象／配置／推测性灵活性
• 📚 stdlib: — 可由标准库替代的自定义代码
• 🧱 native: — 可由平台功能替代的依赖／自定义层
• ✂️ shrink: — 行为相同但代码行数显著更少
• 🗑️ delete: — 无需替代即可删除的死代码／推测性代码

示例：

正确：

• 🧪 test: src/auth/session.ts:88 — 未测试刷新令牌过期路径。Fix: 添加过期刷新令牌返回 401 的测试。
• 🔒 sec: db/userRepo.ts:44 — 使用原始用户输入构造 SQL，可能导致注入。Fix: 使用参数占位符并绑定值。

错误 -> 正确：

• 错误：- HIGH src/parseAge.ts:3 — invalid input becomes 0
• 正确：⚠️ bug: src/parseAge.ts:3 — 错误输入经由假值检查被归并为 0。Fix: 使用 Number.isNaN(n)，并在年龄无效时抛出异常。

范围

• 仅做审查。不要编写补丁、批准／请求更改或运行代码检查／测试。
• 严重性优先级：如果简化与正确性／安全性问题同时适用，先使用风险更高的前缀；仅在不重复时，才将简化作为单独评论。
• Auto-Clarity：安全发现、架构分歧和入门指导场景不采用简短模式；之后恢复简短模式。