对抗性规格说明书

一个 Claude 代码插件，通过多模型辩论迭代优化产品规格说明书，直到达成共识。

核心洞察： 单一的 LLM 审查规格说明书时会遗漏一些内容。而多个 LLM 对规格说明书进行辩论，则能够发现漏洞、挑战假设，并揭示任何单一模型都可能忽视的边缘情况。最终生成的文档经过了严格的对抗性审查。

Claude 是积极参与者，而不仅仅是协调者。Claude 会提供独立的批评意见，挑战对手模型，并与外部模型一起提出实质性的改进建议。

快速入门

# 1. 添加市场并安装插件
claude plugin marketplace add zscole/adversarial-spec
claude plugin install adversarial-spec

# 2. 设置至少一个 API 密钥
export OPENAI_API_KEY="sk-..."
# 或使用 OpenRouter，只需一个密钥即可访问多家供应商
export OPENROUTER_API_KEY="sk-or-..."

# 3. 运行它
/adversarial-spec "构建一个基于 Redis 后端的限流服务"

工作原理

您描述产品 --> Claude 起草规格说明书 --> 多个 LLM 并行评审
        |                                              |
        |                                              v
        |                              Claude 综合各方意见并加入自己的评论
        |                                              |
        |                                              v
        |                              修改并重复，直到所有模型一致同意
        |                                              |
        +--------------------------------------------->|
                                                       v
                                            用户审阅期
                                                       |
                                                       v
                                            最终文档输出

1. 描述您的产品概念或提供现有文档。
2. （可选）从深入访谈开始，以捕捉需求。
3. Claude 起草初始文档（PRD 或技术规格说明书）。
4. 文档被发送给对手模型（GPT、Gemini、Grok 等）进行并行评审。
5. Claude 在对手反馈的基础上提供独立的评论。
6. Claude 综合所有反馈并进行修订。
7. 循环持续，直到所有模型和 Claude 都达成一致。
8. 用户审阅期：请求修改或再运行几轮。
9. 最终收敛的文档会被输出。

系统要求

• Python 3.10+
• litellm 包：pip install litellm
• 至少一家 LLM 提供商的 API 密钥。

支持的模型

供应商	环境变量	示例模型
OpenAI	OPENAI_API_KEY	gpt-4o, gpt-4-turbo, o1
Anthropic	ANTHROPIC_API_KEY	claude-sonnet-4-20250514, claude-opus-4-20250514
Google	GEMINI_API_KEY	gemini/gemini-2.0-flash, gemini/gemini-pro
xAI	XAI_API_KEY	xai/grok-3, xai/grok-beta
Mistral	MISTRAL_API_KEY	mistral/mistral-large, mistral/codestral
Groq	GROQ_API_KEY	groq/llama-3.3-70b-versatile
OpenRouter	OPENROUTER_API_KEY	openrouter/openai/gpt-4o, openrouter/anthropic/claude-3.5-sonnet
Codex CLI	ChatGPT 订阅	codex/gpt-5.2-codex, codex/gpt-5.1-codex-max
Gemini CLI	Google 账户	gemini-cli/gemini-3-pro-preview, gemini-cli/gemini-3-flash-preview
Deepseek	DEEPSEEK_API_KEY	deepseek/deepseek-chat
Zhipu	ZHIPUAI_API_KEY	zhipu/glm-4, zhipu/glm-4-plus

检查已配置的密钥：

python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers

AWS Bedrock 支持

对于需要将所有模型调用路由到 AWS Bedrock 的企业用户（例如出于安全合规或推理网关的要求）：

# 启用 Bedrock 模式
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock enable --region us-east-1

# 添加您在 Bedrock 账户中启用的模型
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock add-model claude-3-sonnet
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock add-model claude-3-haiku

# 检查配置
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock status

# 禁用 Bedrock 模式
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" bedrock disable

当 Bedrock 启用时，所有模型调用都会通过 Bedrock 路由——不会直接进行 API 调用。您可以使用友好的名称，如 claude-3-sonnet，这些名称会自动映射到 Bedrock 的模型 ID。

配置存储在 ~/.claude/adversarial-spec/config.json 中。

OpenRouter 支持

OpenRouter 提供了一个统一的 API，可以访问多家 LLM 提供商的服务。这对于以下情况非常有用：

• 使用一个 API 密钥即可访问多家提供商的模型。
• 比较不同提供商的模型。
• 自动回退和负载均衡。
• 在不同提供商之间优化成本。

设置：

# 从 https://openrouter.ai/keys 获取您的 API 密钥
export OPENROUTER_API_KEY="sk-or-..."

# 使用 OpenRouter 模型（前缀为 openrouter/）
python3 debate.py critique --models openrouter/openai/gpt-4o,openrouter/anthropic/claude-3.5-sonnet < spec.md

流行的 OpenRouter 模型：

• openrouter/openai/gpt-4o —— 通过 OpenRouter 使用 GPT-4o。
• openrouter/anthropic/claude-3.5-sonnet —— Claude 3.5 Sonnet。
• openrouter/google/gemini-2.0-flash —— Gemini 2.0 Flash。
• openrouter/meta-llama/llama-3.3-70b-instruct —— Llama 3.3 70B。
• openrouter/qwen/qwen-2.5-72b-instruct —— Qwen 2.5 72B。

完整的模型列表请参见 openrouter.ai/models。

Codex CLI 支持

Codex CLI 允许 ChatGPT Pro 订阅者无需单独的 API 积分即可使用 OpenAI 的模型。前缀为 codex/ 的模型会通过 Codex CLI 路由。

设置：

# 安装 Codex CLI（需要 ChatGPT Pro 订阅）
npm install -g @openai/codex

# 使用 Codex 模型（前缀为 codex/）
python3 debate.py critique --models codex/gpt-5.2-codex,gemini/gemini-2.0-flash < spec.md

推理时间控制：

通过 --codex-reasoning 参数来控制模型使用的思考时间：

python3 debate.py critique --models codex/gpt-5.2-codex,gemini/gemini-2.0-flash --codex-reasoning=high < spec.md

可用级别：低、中、高、超高（默认：超高）

python3 debate.py critique --models codex/gpt-5.2-codex --codex-reasoning high < spec.md

更高的推理力度会产生更全面的分析，但会消耗更多的 token。

**可用的 Codex 模型：**
- `codex/gpt-5.2-codex` - 通过 Codex CLI 的 GPT-5.2
- `codex/gpt-5.1-codex-max` - 通过 Codex CLI 的 GPT-5.1 Max

检查 Codex CLI 的安装状态：

```bash
python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers

Gemini CLI 支持

Gemini CLI 允许 Google 账户持有人在无需单独 API 额度的情况下使用 Gemini 模型。前缀为 gemini-cli/ 的模型将通过 Gemini CLI 路由。

设置：

# 安装 Gemini CLI
npm install -g @google/gemini-cli && gemini auth

# 使用 Gemini CLI 模型（需加 gemini-cli/ 前缀）
python3 debate.py critique --models gemini-cli/gemini-3-pro-preview < spec.md

可用的 Gemini CLI 模型：

• gemini-cli/gemini-3-pro-preview - 通过 CLI 的 Gemini 3 Pro
• gemini-cli/gemini-3-flash-preview - 通过 CLI 的 Gemini 3 Flash

检查 Gemini CLI 的安装状态：

python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers

OpenAI 兼容端点

对于暴露 OpenAI 兼容 API 的模型（本地 LLM、自托管模型、替代提供商），请设置 OPENAI_API_BASE：

# 指向自定义端点
export OPENAI_API_KEY="your-key"
export OPENAI_API_BASE="https://your-endpoint.com/v1"

# 与任何模型名称一起使用
python3 debate.py critique --models gpt-4o < spec.md

这适用于：

• 本地 LLM 服务器（Ollama、vLLM、text-generation-webui）
• OpenAI 兼容提供商
• 自托管推理端点

使用方法

从头开始：

/adversarial-spec "构建一个基于 Redis 后端的限流服务"

完善现有文档：

/adversarial-spec ./docs/my-spec.md

系统将提示您提供以下信息：

1. 文档类型：PRD（面向业务/产品）或技术规格书（面向工程）
2. 访谈模式：可选的深入需求收集环节
3. 对手模型：逗号分隔的列表（例如：gpt-4o,gemini/gemini-2.0-flash,xai/grok-3）

模型越多，视角越丰富，收敛标准也越严格。

文档类型

PRD（产品需求文档）

适用于利益相关者、产品经理和设计师。

章节： 执行摘要、问题陈述、目标用户/角色、用户故事、功能需求、非功能需求、成功指标、范围（包含/排除）、依赖关系、风险

批评重点： 清晰的问题定义、明确的角色定位、可衡量的成功标准、清晰的范围界定、不包含技术实现细节

技术规格书

适用于开发人员和架构师。

章节： 概述、目标/非目标、系统架构、组件设计、API 设计（完整模式）、数据模型、基础设施、安全、错误处理、性能/SLA、可观性、测试策略、部署策略

批评重点： 完整的 API 合同、数据模型覆盖、安全威胁缓解、错误处理机制、具体性能目标、避免对工程师造成歧义

核心功能

访谈模式

在辩论开始前，可以选择进入深度访谈环节，以提前捕捉需求。

内容： 问题背景、用户/利益相关者、功能需求、技术限制、UI/UX、权衡取舍、风险、成功标准

访谈会通过深入追问来挑战假设。完成后，Claude 会将回答综合成一份完整的规格书，再开始对抗式辩论。

Claude 的积极参与

每一轮，Claude 都会：

1. 检查对手的批评是否有效
2. 提供独立的批评（对手遗漏了什么？）
3. 表明对特定观点的同意或不同意
4. 将所有反馈综合为修订内容

显示格式如下：

--- 第 N 轮 ---
对手模型：
- [GPT-4o]：批评——缺少限流配置
- [Gemini]：同意

Claude 的批评：
安全部分缺乏输入验证策略。建议加入 OWASP 十大漏洞防护。

综合意见：
- 接受来自 GPT-4o 的建议：限流配置
- Claude 添加：输入验证、OWASP 防护
- 拒绝：无

早期一致性验证

如果某个模型在前两轮内就表示同意，Claude 会持怀疑态度。该模型会被要求：

• 确认已阅读全文
• 列出具体审查过的章节
• 解释为何同意
• 指出仍存在的顾虑

这样可以防止那些未经仔细审查就盲目认可的模型产生虚假的一致性。

用户审核期

当所有模型达成一致后，您将进入审核期，有三种选择：

1. 按原样接受：文档已完成
2. 请求修改：Claude 更新规格书，您无需进行完整辩论周期即可迭代
3. 再运行一轮：将更新后的规格书再次送入对抗式辩论

多轮审核

您可以采用不同策略运行多轮辩论：

• 第一轮使用快速模型（gpt-4o），第二轮使用更强的模型（o1）
• 第一轮关注结构完整性，第二轮聚焦安全性
• 在用户提出修改后，获取新的视角

PRD 到技术规格书的流程

当 PRD 达到共识时，您将被提供直接基于 PRD 继续撰写技术规格书的选项。这样可以在一次会话中完成一整套文档。

进阶功能

批评焦点模式

引导模型优先关注特定问题：

--focus security      # 认证、输入验证、加密、漏洞
--focus scalability   # 水平扩展、分片、缓存、容量
--focus performance   # 延迟目标、吞吐量、查询优化
--focus ux            # 用户旅程、错误状态、无障碍访问
--focus reliability   # 故障模式、断路器、灾难恢复
--focus cost          # 基础设施成本、资源效率

模型角色

让模型从特定职业角度进行批评：

--persona security-engineer      # 以攻击者的思维思考
--persona oncall-engineer        # 关注凌晨三点的调试
--persona junior-developer       # 指出模糊性和经验性知识
--persona qa-engineer            # 测试场景缺失
--persona site-reliability       # 部署、监控、突发事件
--persona product-manager        # 用户价值、成功指标
--persona data-engineer          # 数据模型、ETL 影响
--persona mobile-developer       # 针对移动端的 API 设计
--persona accessibility-specialist  # WCAG、屏幕阅读器
--persona legal-compliance       # GDPR、CCPA、监管要求

自定义角色同样适用：--persona "金融科技合规官"

上下文注入

包含现有文档供模型参考：

--context ./existing-api.md --context ./schema.sql

使用场景：

• 新规范必须集成的现有 API 文档
• 规范必须兼容的数据库模式
• 用于保持一致性的设计文档或先前规范
• 合规性要求文档

会话持久化与恢复

长时间的讨论可能会崩溃或需要暂停。会话会自动保存状态：

# 启动一个命名会话
echo "spec" | python3 debate.py critique --models gpt-4o --session my-feature-spec

# 从上次中断处恢复
python3 debate.py critique --resume my-feature-spec

# 列出所有会话
python3 debate.py sessions

会话保存的内容包括：

• 当前规范的状态
• 轮次编号
• 所有配置（模型、焦点、角色等）
• 历史轮次的记录

会话存储在 ~/.config/adversarial-spec/sessions/ 目录中。

自动检查点

使用会话时，每一轮的规范都会保存到 .adversarial-spec-checkpoints/ 目录中：

.adversarial-spec-checkpoints/
├── my-feature-spec-round-1.md
├── my-feature-spec-round-2.md
└── my-feature-spec-round-3.md

如果某次修订使情况变得更糟，可以使用这些检查点进行回滚。

保留意图模式

当模型将“不寻常”解释为“错误”时，收敛可能会抹去新颖的想法。--preserve-intent 标志会使移除操作变得代价高昂：

--preserve-intent

启用后，模型必须：

1. 精确引用他们想要移除或大幅更改的内容
2. 说明其危害——不仅仅是“不必要的”，还要指出它会造成哪些具体问题
3. 区分错误与偏好——只移除那些事实错误、自相矛盾或存在风险的内容
4. 在移除之前询问那些不寻常但功能正常的选项：“这是有意为之吗？”

这会将默认行为从“抹去任何不寻常之处”转变为“增加保护性细节，同时保留独特的选择”。

适用场景：

• 您的规范包含有意为之的非常规选择
• 您希望模型挑战您的想法，而不是将其同质化
• 前几轮移除了您原本想保留的内容

成本跟踪

每一轮评论都会显示令牌使用量和预估成本：

=== 成本摘要 ===
总令牌数：输入 12,543 / 输出 3,221
总成本：$0.0847

按模型：
  gpt-4o：$0.0523（输入 8,234 / 输出 2,100）
  gemini/gemini-2.0-flash：$0.0324（输入 4,309 / 输出 1,121）

保存的配置文件

保存常用配置：

# 创建一个配置文件
python3 debate.py save-profile strict-security \
  --models gpt-4o,gemini/gemini-2.0-flash \
  --focus security \
  --doc-type tech

# 使用配置文件
python3 debate.py critique --profile strict-security < spec.md

# 列出配置文件
python3 debate.py profiles

配置文件存储在 ~/.config/adversarial-spec/profiles/ 目录中。

轮次之间的差异比较

查看规范版本之间的确切变化：

python3 debate.py diff --previous round1.md --current round2.md

导出为任务列表

从最终确定的规范中提取可执行的任务：

cat spec-output.md | python3 debate.py export-tasks --models gpt-4o --doc-type prd

输出内容包括标题、类型、优先级、描述以及验收标准。

使用 --json 可以获得适合导入问题跟踪系统的结构化输出。

Telegram 集成（可选）

在手机上接收通知，并在讨论过程中注入反馈。

设置步骤：

1. 在 Telegram 中联系 @BotFather，发送 /newbot 并按照提示操作
2. 复制机器人令牌
3. 运行：python3 "$(find ~/.claude -name telegram_bot.py -path '*adversarial-spec*' 2>/dev/null | head -1)" setup
4. 向您的机器人发送消息，再次运行设置流程以获取聊天 ID
5. 设置环境变量：

export TELEGRAM_BOT_TOKEN="..."
export TELEGRAM_CHAT_ID="..."

功能：

• 轮次完成后异步通知（包含成本信息）
• 60 秒内回复反馈的时间窗口（反馈将被纳入下一轮）
• 讨论结束后将最终文档发送至 Telegram

输出

最终文档具备以下特点：

• 完整，遵循相应文档类型的完整结构
• 经所有模型审核直至达成一致意见
• 可直接交付给相关方，无需进一步编辑

输出位置：

• 打印到终端
• 写入 spec-output.md（PRD）或 tech-spec-output.md（技术规范）
• 发送至 Telegram（如已启用）

辩论总结包括已完成的轮次、运行的周期、参与的模型、Claude 的贡献、成本以及所做的关键改进。

CLI 参考

# 核心命令
debate.py critique --models MODEL_LIST --doc-type TYPE [OPTIONS] < spec.md
debate.py critique --resume SESSION_ID
debate.py diff --previous OLD.md --current NEW.md
debate.py export-tasks --models MODEL --doc-type TYPE [--json] < spec.md

# 信息命令
debate.py providers      # 列出提供商及 API 密钥状态
debate.py focus-areas    # 列出重点领域
debate.py personas       # 列出角色
debate.py profiles       # 列出已保存的配置文件
debate.py sessions       # 列出已保存的会话

# 配置文件管理
debate.py save-profile NAME --models ... [--focus ...] [--persona ...]

# Bedrock 管理
debate.py bedrock status                      # 显示 Bedrock 配置
debate.py bedrock enable --region REGION      # 启用 Bedrock 模式
debate.py bedrock disable                     # 关闭 Bedrock 模式
debate.py bedrock add-model MODEL             # 将模型添加到可用列表
debate.py bedrock remove-model MODEL          # 从列表中移除模型
debate.py bedrock list-models                 # 列出内置模型映射

选项：

• --models, -m - 逗号分隔的模型列表（若未指定，则会根据可用的 API 密钥自动检测）
• --doc-type, -d - prd 或 tech
• --codex-reasoning - Codex 模型的推理力度（low、medium、high、xhigh；默认：xhigh）
• --focus, -f - 重点领域（security、scalability、performance、ux、reliability、cost）
• --persona - 专业角色
• --context, -c - 上下文文件（可重复使用）
• --profile - 加载已保存的配置文件
• --preserve-intent - 要求对移除操作提供理由
• --session, -s - 会话 ID，用于持久化和检查点
• --resume - 恢复之前的会话
• --press, -p - 防止拖延检查
• --telegram, -t - 启用 Telegram
• --json, -j - JSON 输出

文件结构

adversarial-spec/
├── .claude-plugin/
│   └── plugin.json           # 插件元数据
├── README.md
├── LICENSE
└── skills/
    └── adversarial-spec/
        ├── SKILL.md          # 技能定义和流程
        └── scripts/
            ├── debate.py     # 多模型辩论编排
            └── telegram_bot.py   # Telegram 通知

许可证

MIT

adversarial-spec 快速上手指南

环境准备

系统要求

• Python 3.10+
• 支持类 Unix 系统（Linux/macOS）

前置依赖

1. 安装 Python 3.10+（建议使用 pyenv 管理版本）
2. 安装 litellm 包（支持多模型调用）

   pip install litellm
   

   推荐使用国内镜像加速

   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple litellm
   

API 密钥准备
需配置至少一个 LLM 提供商的 API 密钥（如 OpenAI、OpenRouter 等）

export OPENAI_API_KEY="sk-..."
# 或使用 OpenRouter 统一接入
export OPENROUTER_API_KEY="sk-or-..."

---

安装步骤

1. 添加插件市场源

   claude plugin marketplace add zscole/adversarial-spec
   

2. 安装 adversarial-spec 插件

   claude plugin install adversarial-spec
   

3. 验证安装（可选）

   python3 "$(find ~/.claude -name debate.py -path '*adversarial-spec*' 2>/dev/null | head -1)" providers
   

---

基本使用

场景 1：从零构建需求文档

/adversarial-spec "Build a rate limiter service with Redis backend"

场景 2：迭代优化现有文档

/adversarial-spec ./docs/my-spec.md

运行后需回答

1. 文档类型：PRD（产品需求文档）或 tech spec（技术规格书）
2. 是否启用深度访谈（可选）
3. 指定对抗模型列表（如 gpt-4o,gemini/gemini-2.0-flash）

输出结果
经过多模型辩论收敛后的最终文档，支持后续迭代优化。