SuperAPI AI 工具集

specs-kit-adversarial-review

测试与质量

查看项目

更新于 10-27 10:54

技能介绍

对抗式审查(多模型面板)是一个在编码开始前对规格说明、技术计划和生成的任务集进行压力测试的技能。它把工作提交给一组相互独立的模型,每个模型都被要求尝试打破工作,而不是批准它。各个模型的评审意见随后交叉比对:多个模型独立发现的收敛性发现几乎可以确定是真实缺陷;存在分歧的发现则标记为真正有争议的决策,这类决策若由单一审查者来回答,往往会被一个自信的答案掩盖。

用途与定位

该技能位于工作流的以下位置:brainstorm → spec-check → technical-plan → spec-to-tasks → adversarial-review(本技能)→ task-implementation,是写代码前的最后一道关卡。审查范围仅限文档:规格文件、技术计划、tasks/ 下的任务文件,以及存在时的 data-model.md、contracts/、项目级 architecture.md 和 ontology.md。面板不读取代码库,不查看源码、代码图或测试,它回答的是“这份规格是否自洽”,而不是“代码是否符合规格”。

主要能力

一是隔离审查。每位审查者在第一轮中看不到其他人的结论,比较在事后统一进行。二是敌意授权。返回“看起来不错”的审查者被视为没有完成工作,每个角色都必须按章节说明自己尝试的攻击为何没有奏效。三是可证伪的发现。每条发现都必须附带具体失败场景,无法表述为“给定 X,实现会做 Y,这与 Z 矛盾”的发现会在合并时被丢弃。四是共识作为证据而非权威:多个模型一致会提高严重级别,但不会覆盖用户的决定。五是所有产物都存放在规格文件夹旁,便于与规格一起阅读。六是尽力而为的面板:某位审查者启动失败或输出无法解析时,会被记录为缺失,只要至少两位审查者给出结果,面板就继续。

使用方式

基本用法是 /skill:specs-kit-adversarial-review docs/specs/001-user-auth/。可以用 --spec 指定规格文件夹(默认从当前工作目录自动推断);用 --models 传入逗号分隔的面板,覆盖声明列表;用 --force 在存在 BLOCKER 发现时继续并记录覆盖;用 --rounds 选择 1(默认)或 2 轮,第 2 轮为反驳。如果推断不出规格文件夹,技能会停止并告知用户。

面板装配遵循严格规则:面板只从显式允许列表读取,优先级为命令行 --models、项目 specs-kit.yaml 中的 adversarial_review.panel。若未声明则停止,不会回退到猜测的面板。模型目录只用于校验拼写(pi --list-models),不会自动选择模型,因为目录中混合了免费与按量计费模型,自动选择可能让技能在操作者未选择的模型上花钱。声明的模型在目录中缺失时硬性停止,绝不替换。面板从不扩大:审查者数量恰好是声明的数量,上限为 4。3 位审查者是目标,2 位可接受但需注明共识较弱,只声明 1 位则停止并建议改用 /skill:specs-kit-task-review。

审查者按列表顺序分配角色:1 号“对抗者”攻击不可证伪的需求、轻易通过的验收标准、隐含假设、范围悄然变化;2 号“操作者”关注失败时会发生什么:部分写入、并发、重试、依赖不可用、迁移与回滚、失败可观测性;3 号“执行者”检验任务集是否真的可执行:顺序、缺失的前置任务、伪独立任务间的隐藏耦合、无法检查的完成定义、无任务覆盖的工作;4 号“历史学家”检验工作是否与项目既有决定矛盾,仅在项目维护架构与本体文档时值得占一个席位。

执行时,run-panel.sh 脚本为每位审查者携带固定系统提示并填入角色,用户提示按“目标、审查范围、规则、输出契约”分节写成独立文件,避免内联引号与换行带来的转义问题。审查者默认并行运行,各自是独立进程、无共享会话;当两位审查者共用同一提供方、限流使并行更不稳定时,可加 --sequential 串行执行;--timeout 设置单个审查者的超时秒数。脚本逐行打印每位审查者的状态。

输出结构

输出目录为 docs/specs/[id]/adversarial-review/,包含每位审查者的原始评审、合并报告和结论。每份评审必须是一个 JSON 对象,字段包括 findings(每条含 severity、target、claim、scenario、suggested_fix;severity 为 BLOCKER、MAJOR、MINOR)、attacks_that_did_not_land(记录尝试过但未奏效的攻击及原因)以及 confidence(high、medium、low)。

适用场景与限制

适合已有规格和任务集、准备进入实现之前的项目,尤其适合需要多角度审查、担心单一审查者存在稳定盲区的团队。限制包括:不审查代码,代码与规格的一致性属于另一个技能;要求规格中存在未解决的 [NEEDS CLARIFICATION] 标记时会先警告并建议先运行 spec-check;需要至少两个维护者;面板模型需操作者自行声明并承担费用;具体定价、提供方细节和效果数据暂未提供。