rigorous-review

/rigorous-review

在代码库中调查 安全性、性能、正确性和重构方面的改进，同时遵守一项硬性约束：不得对任何面向外部的页面或 API 造成可观察到的变化。 修复后，对于合法调用者，公共路由渲染出的 HTML、URL 结构、JSON 响应格式、身份验证流程和管理界面行为都必须逐字节保持一致。

交付内容是报告。只有用户提出要求时才应用修复，且只应用被归类为 safe 的修复。

核心原则

1. 先验证，再报告。 每项发现都要从头到尾阅读相关代码（路由 → 辅助函数 → 查询；对于安全问题，从数据入口追踪到危险的汇点），并引用 file:line 和代码片段。证据开头要说明可观察到的后果——用户、攻击者或运维人员会遇到什么，而不是代码结构。不得根据名称或假设提出发现。
2. 两个评分维度，再进行门槛筛选。 每项发现都要标注严重性（P0–P3，表示影响程度）和置信度（0/25/50/75/100，表示确定程度）。二者相互独立——某个漏洞确实存在，但只能证明一半，应记为 P0 × 50，而不是 P2。由门槛规则（见下文）决定哪些发现会显示出来。这是该技能中影响信噪比最大的因素。
3. 抑制可预见的误报。 噪声太多的审计会被忽视。输出任何发现前，都要先根据禁止标记清单和既定先例表进行检查（references/scoring-gating-validation.md）。最常见的遗漏是“中间件 / 框架 / 并行处理器已经处理”——标记之前要检查调用方。
4. safe 与 gated 的区分至关重要。 这能保障“不得对外部造成变化”的承诺。
   • safe — 对合法调用者保持行为不变；不修改架构，不涉及基础设施。 授权修复属于 safe：拒绝未授权调用者是预期行为，不是回归。合法调用者本来就满足的防护条件也一样。
   • gated — 存在任何可观察到变化的风险、架构 / 迁移变更、数据语义变更或新增基础设施。仅报告，绝不静默应用。
5. 生产环境只读。 不得迁移、不得运行 drizzle-kit push、不得对生产环境运行脚本、不得执行破坏性命令。架构 / 索引建议只能写入报告。
6. 精准修改。 除修复所需内容外，不要“改进”相邻代码、注释或格式。

门槛规则（严重性 × 置信度如何决定哪些发现会显示出来）

在综合分析之后、生成报告之前应用：

• 抑制所有置信度低于 75 的发现——但置信度 ≥50 的 P0 除外，此类发现必须保留（关键但不确定的问题不得被静默丢弃；应交由验证器轮次处理）。
• 按领域区别对待——不同领域的漏报成本不同，因此门槛也不同：
  • 安全性：门槛较低。 置信度为 50 的安全问题通常标记为 P0，以通过门槛。漏掉真实漏洞的代价高于误报。
  • 性能：门槛较高。 应抑制推测性的 / 过早优化类发现，而不是将其按 50 置信度提交。性能误报会浪费工程时间。
  • 正确性和重构采用标准门槛。
• 投入程度（--effort，默认值为 medium）：low / medium 只报告高置信度发现（≥75）——数量较少，但把握更大。high / max 扩大召回范围（展示置信度为 50、尚待筛选的发现，并对更多发现执行验证器轮次）。根据请求调整分析深度。

完整的置信度锚点定义、去重指纹、共识提升规则、验证器轮次流程和先例表：references/scoring-gating-validation.md。

流程

阶段 0：了解情况（分派前，成本低）

1. 确定技术栈和授权模型。关键问题：是否有 middleware.ts／中央授权层，还是每个路由／操作各自进行防护？请先明确回答——这会改变安全审查对每个端点的分析方式。 （在应用根目录运行 grep -r "middleware"；检查框架的授权入口。）
2. 清点攻击面：公开路由、管理路由、API 路由、服务端操作／RPC，以及会触及数据库的脚本。只读的 Explore Agent 很适合做这项工作。对任何没有对应防护的攻击面元素都要提交一条发现（attack-surface-inventory 规则）。
3. 记录 CLAUDE.md／AGENTS.md 中的项目不变量（租户范围限定、PII 规则、金额／单位约定）。将这些内容原样传给审查者，并注明“违反此项属于 P0”。
4. 选择投入级别（默认 medium）并分配模型层级：安全和正确性审查者沿用当前会话模型（风险高，漏报代价高）；性能和重构审查者可使用中档模型（成本约低 3–4 倍，在风险较低的审查领域不会损失质量）。请明确说明分配方案。

阶段 1：并行分派四名审查者

在一条消息中分派四个 Agent（run_in_background: true），每个都必须只读，并要求每个审查者：沿完整代码路径核实每条发现，按两个维度评分，分类为 safe／gated，并且在输出前应用其负责领域的“不要标记”清单。每个审查者都应返回发现（id、严重性、置信度、标题、file:line、证据引文 + 可观察到的后果、修复概要、类别、领域），以及一份对每项给出一个词结论的简短清单。

四个审查领域的完整清单见 references/reviewer-lanes.md：

• 安全（会话模型；较低门槛）——检查每个变更操作和管理读取是否有授权（会话检查和针对目标资源的租户／所有权检查）；将服务端操作／RPC 作为真实端点审计；必须扫描 Git 跟踪文件中的机密；追踪不可信输入到危险接收点的数据流；检查 SSRF、不安全反序列化、CSRF、危险接收点（dangerouslySetInnerHTML、exec 插值、eval／new Function）；将每条发现映射到 OWASP Top 10:2025 + CWE。
• 性能（中档模型；较高门槛）——每次渲染的查询次数（N+1、顺序 await → Promise.all／联接——先确认循环确实存在）；缺少索引（gated）；过度获取数据；Core Web Vitals（LCP／INP／CLS、图像／字体、barrel 导入、RSC 序列化）；无服务器陷阱（跨调用失效的进程内缓存、临时文件系统写入、未经身份验证的 cron）。估算数据量达到 10×／100×／1000× 时的项目影响。
• 正确性（会话模型；标准门槛）——差一错误和边界／分页问题（恰好是每页大小整数倍时）；null／undefined 传播为 "undefined"／NaN；掩盖错误的回退逻辑（查询失败时返回空数组，而非传播错误）；TOCTOU 和状态仅部分更新；竞态条件。
• 重构（中档模型；标准门槛）——使用真实工具证明死代码（knip／ts-prune／ruff F401／ast-grep，并考虑 barrel 文件、动态 import()、框架导出——不能只用裸 grep）；易产生偏差的重复代码（若副本已经不一致，则为 P1）；Fowler 五类代码异味分类法；删除测试和双适配器接缝规则（不要建议创建仅使用一次的抽象）；TS 类型安全（noUncheckedIndexedAccess、Result 与 throw 的取舍、判别联合）。删除建议标为 gated。

另加一项 API 契约检查，直接守护核心不变量（增量式与变更式的区别、静默语义变更，例如“count 以前包含已删除行，现在却不包含”）：references/behavior-preservation.md。

阶段 2：综合（去重 + 提升 + 筛选）

不要只是将四项输出串接起来。按以下顺序执行：

1. 根据指纹 normalize(file) + line_bucket(line, ±3) + normalize(title) 去重——两个通道标记的同一处缺陷只算一项发现，而不是两项。
2. 一致性提升——当 2 个或更多通道标记了相同指纹时，将其置信度提高一级（50→75、75→100）。独立佐证属于证据。
3. 应用筛选条件（见上文）：剔除低于 75 的项，P0（50 分）除外；遵循各通道的不对称性和工作量档位。较弱的 P2/P3 留存项应列入报告中的 residual risks / advisory 层级，而非主表。

阶段 3：独立验证器轮次（取代自我复查）

不要重新验证自己的综合结果——合并发现的编排器并非独立的第二意见（它能发现错误事实，却无法发现自身偏见）。应针对每项留存的 P0 和 P1，启动一个全新的验证器 Agent，且不预设该发现成立（“误报很常见，不要有确认它的压力”）。每项发现对应一个验证器（单个批处理验证器会重现这种偏见）。验证器应从头阅读代码路径，并基于自己的证据返回确认 / 降级 / 驳回。

• 故障时保留降级项：如果验证器未能返回（而非驳回），则剔除 P2/P3（采取保守做法），但保留 P0/P1，并标记为“degraded — unvalidated”——临时故障绝不能悄然移除关键发现。
• 在 low / medium 工作量档位，验证 P0/P1；在 high / max 档位，还要验证 P2。

阶段 4：撰写报告

写入 docs/audits/YYYY-MM-DD-rigorous-review.md：

• 一段 TL;DR，概述少数真正重要的事项，并给出建议的处理顺序。
• 四张发现表（安全 / 性能 / 正确性 / 重构），每行包含： id、严重性、置信度、标题、文件:行号、类别、OWASP/CWE（仅限安全问题）。
• 为软分类的 P2/P3 留存项设置 advisory / residual-risks 层级。
• 设置 “verified clean” 部分，说明检查过且确认安全的内容，避免他人重复审计。
• 给出建议执行顺序：先轮换密钥/凭据并关闭未授权写入，然后处理安全的性能优化，再处理需审批的筛选项，最后处理可维护性问题。
• 明确注明未触及生产数据，也未应用任何修复。

阶段 5：应用安全修复——仅在收到要求时

如果用户传入 apply-safe（或之后提出要求）：

• 仅应用 safe 发现，按置信度从高到低处理。每个问题单独提交一次，并使用规范的提交信息。绝不推送。
• 每次修复后，运行行为保持验证器：推断变更代码所服务的用户故事，并逐边界检查（请求 → 处理程序 → 数据 → 响应），确认合法调用者看到的结果保持不变。 **在第一个出现问题的边界处停止。**测试通过是必要条件，但还不够——验证器必须证明流程符合预期。协议：references/behavior-preservation.md。
• 每次修复后运行项目的测试命令和构建；两者都必须通过才能继续处理下一项。
• 绝不应用 gated 项。如果某项 safe 修复在实际修改代码后可能导致可观察到的变化，停止并将其重新归类为 gated。
• 建议将安全修复单独放在专门的分支中。

已融入的注意事项／经验教训

• 没有置信度的发现只能算半个发现。 严重性说明问题一旦属实会有多严重； 置信度说明有多确定问题确实存在。把推测性的 P0 当作已验证的问题报告，会让审计失去 信任；而忽略不确定的 P0，则可能导致漏掉安全事件。门槛评估两者都需要。
• 密钥扫描不可省略，而且很容易漏掉。 测试中，专门的安全审查漏掉了一项已提交的 数据库凭据，而另一位审查者碰巧发现了它。已提交的密钥属于 P0，需要轮换，而不只是 删除——它仍存在于 git 历史中。
• 自我复查不等于验证。 编排器负责综合发现结果，因此重新阅读它们只会印证自身偏见。 独立验证轮（阶段 3）才是解决办法；不要为了节省 Agent 而跳过它，改成自我复查。
• 标记问题前先检查调用方。 最常见的误报是，对已有中间件、框架默认行为或并行处理器 保护的代码，声称“缺少防护／验证”。审查者经常提出这类问题，因此才有禁止标记列表。
• 在阶段 0 说明身份验证模型。 否则，审查者会浪费精力重新发现没有统一中间件、 每个端点都自行实施防护这一事实。
• 不要让“重构”改变数据。 如果重复的转换逻辑本来就不一致，选择其中一种语义 本身就是一项数据决策，应标记为 gated，而不是悄悄清理。同样适用于任何 API 契约变更。
• 通过 grep 判断死代码并不可靠。 汇总文件、动态导入和框架路由导出会让某个符号看起来 未被使用，实际却并非如此。应使用真实工具证明可以删除；删除操作应标记为 gated。
• 范围： 可选的路径参数会缩小审计范围；默认审计整个应用。审查深度应与范围以及 --effort 相匹配。

更新日志

V1（2026-06-10）

rigorous-review 的首次发布。内容提炼自一个可运行的原型（internal-hardening-audit）。该原型曾在两个生产环境的 Web 代码库上实际运行（Fable/Opus，效果良好；它发现了一个专门的安全审查遗漏的已提交 DB 凭据），随后又通过 3 个 Agent 对 CE 审查 Agent、内置的 code-review/security-review、Vercel 技能、Anthropic security-review、Matt Pocock 的架构技能、OWASP Top 10:2025、Fowler 代码异味和 Core Web Vitals 进行研究综合，进一步加固。设计中的每个部分都有明确来源：

• 两个评分维度 + 一道门槛（CE ce-code-review 的 5 档置信度；Anthropic 的 ≥0.8 报告阈值）——仅靠严重程度无法表达“严重但未经验证”；门槛是提高精确率的主要手段（低于 75 分的结果予以抑制，P0 在 50 分时例外）。
• 禁止标记列表 + 已确定先例表（Anthropic 的 18 项排除规则；CE 的误报目录）——这是提升信噪比收益最高的单项改进。
• 独立验证轮次，而非自我复查（CE：综合者不能作为自己的公正检查者）——每个 P0/P1 配备新的 Agent，崩溃时降级保留。
• 跨审查者去重（指纹）+ 一致性提升（CE 合并流程）——并行审查者相互佐证，而不是重复列出相同问题。
• 按审查领域设置不对称阈值（CE：安全阈值较低 / 性能阈值较高）——采用统一阈值会低报安全问题，也会高报过早优化。
• 四个审查领域——安全、性能、重构和正确性（差一错误、空值传播、错误屏蔽、TOCTOU、竞态）；内置的 code-review 和 Anthropic 都以正确性为核心。
• API 契约 / 行为保持检查——直接保护核心不变量（增量式与变更式、静默语义变化）。
• 覆盖范围——安全：SSRF（OWASP A01）、不安全反序列化、CSRF、危险接收点监控列表、OWASP-2025/CWE 标签。性能：Core Web Vitals、图像 / 字体、barrel 导入、RSC 序列化、无服务器缓存 / FS / cron。重构：真实的死代码工具（knip/ts-prune/ast-grep）、Fowler 五类分类法、Pocock 删除测试 + 双适配器接缝规则、TS 类型安全。
• 流程层——工作量调节（精确率↔召回率）、模型分级（安全 + 正确性 = 会话模型，性能 + 重构 = 中档模型）、第 5 阶段行为保持验证器。
• 为保持 SKILL.md 简洁，复杂的检查清单放在 references/ 中。

实证的精确率 / 召回率验证仍需等待下一次实际审计。

参考资料

• references/reviewer-lanes.md — 各审查领域的完整检查清单（安全 / 性能 / 正确性 / 重构）+ 各领域的禁止标记列表。
• references/scoring-gating-validation.md — 置信度锚点、门槛、各领域的不对称阈值、去重指纹、一致性提升、验证轮次协议、降级保留、已确定先例表、工作量调节、模型分级。
• references/behavior-preservation.md — API 契约的增量式与变更式 + 静默语义变化检查，以及第 5 阶段边界遍历验证器。

测试

tests/eval.sh 以结构化方式验证设计契约（两个维度 + 门槛、P0 在 50 分时的例外、抑制列表、独立验证轮次、去重 + 提升、包含正确性在内的四个审查领域、API 契约检查、OWASP/CWE + SSRF/反序列化、Core Web Vitals、真实的死代码工具、工作量调节、模型分级、行为保持验证器、生产环境只读、安全与需门控）。行为验证将在下一次实际审计中进行（重新审计同一批代码库，并将问题发现的精确率 / 召回率与原型基线进行比较）。