debate-workflow

辩论工作流技能

用途

针对重要的架构决策、设计权衡和存在多种合理方案的复杂问题，开展结构化的多视角辩论。

何时使用此技能

适用于：

• 重大架构决策（框架选择、系统设计）
• 没有明确赢家的复杂权衡
• 影响多个团队的争议性变更
• 需要获得各方支持的高影响力决策
• 各方观点确实相互冲突时

避免用于：

• 简单的实现选择
• 有明显正确答案的决策
• 时间紧迫的热修复
• 小型重构
• 常规功能新增

配置

核心参数

视角数量：

• 3 - 默认（安全性、性能、简洁性）
• 5 - 扩展（增加：可维护性、用户体验）
• 7 - 全面（增加：可扩展性、成本）

辩论轮数：

• 2 - 快速（立场 + 质疑）
• 3 - 标准（立场 + 质疑 + 综合）
• 4-5 - 深入（多轮质疑/回应）

达成共识的标准：

• 100% - 强共识（所有视角均同意）
• 2/3 - 多数规则（三分之二同意）
• synthesis - 由主持人综合出最佳混合方案
• evidence - 遵循最有力的证据/论据

标准视角配置

安全性视角：

• 关注点：漏洞、攻击向量、数据保护
• 问题：“可能出现什么问题？我们如何防止安全漏洞？”
• Agent：安全 Agent

性能视角：

• 关注点：速度、可扩展性、资源效率
• 问题：“这能扩展吗？瓶颈在哪里？”
• Agent：优化 Agent

简洁性视角：

• 关注点：尽量降低复杂度、彻底简化
• 问题：“这是最简单的解决方案吗？能否去掉抽象层？”
• Agent：清理 Agent + 审查 Agent

可维护性视角：

• 关注点：长期演进、技术债务
• 问题：“未来的开发者能看懂吗？修改起来有多难？”
• Agent：审查 Agent + 架构师 Agent

用户体验视角：

• 关注点：API 设计、易用性、开发者体验
• 问题：“这是否直观？用户会如何与之交互？”
• Agent：API 设计师 Agent

可扩展性视角：

• 关注点：增长能力、分布式系统
• 问题：“负载达到 10 倍时会怎样？100 倍呢？”
• Agent：优化 Agent + 架构师 Agent

成本视角：

• 关注点：资源使用、基础设施成本、开发时间
• 问题：“投资回报率是多少？我们是否过度设计了？”
• Agent：分析师 Agent

执行流程

步骤 1：明确决策框架

• 使用歧义 Agent，明确需要做出的决策
• 使用提示词编写 Agent，创建清晰的决策提示词
• 定义决策范围和约束条件
• 确定利益相关方的关切
• 列出评估标准
• 记录限制选项的明确用户需求
• 关键：将决策表述为问题，而非预设答案

决策框架模板：

# Decision: [Brief Title]

## Question

[One-sentence question to be debated]

## Context

[Why this decision matters, background information]

## Constraints

[Non-negotiable requirements, technical limitations]

## Evaluation Criteria

[How we'll judge proposed solutions]

## Perspectives to Include

[Which viewpoints are most relevant]

示例：

# Decision: Data Storage Strategy for User Analytics

## Question

Should we use PostgreSQL with JSONB, MongoDB, or ClickHouse
for storing and querying user analytics events?

## Context

- 10M events/day expected at launch
- 100M events/day within 2 years
- Complex queries for dashboard analytics
- Real-time and historical reporting needed

## Constraints

- Must handle 10M events/day minimum
- Query latency < 200ms for dashboards
- Budget: $5K/month infrastructure
- Team familiar with PostgreSQL, not ClickHouse

## Evaluation Criteria

1. Performance at scale
2. Query flexibility
3. Operational complexity
4. Cost at scale
5. Team learning curve

## Perspectives to Include

Performance, Cost, Maintainability, Scalability

步骤 2：初始化各个视角

• 选择与决策相关的 N 个视角
• 为每个视角启动一个 Claude 子进程
• 每个子进程接收决策框架文档
• 为每个子进程分配一个视角配置
• 此时各视角之间不共享上下文
• 每个视角独立形成初步立场

初步立场要求：

• 说明推荐方案
• 提供 3-5 条支持论据
• 识别其他方案的风险
• 尽可能量化论点

步骤 3：辩论第 1 轮——初步立场

• 收集所有视角的初步立场
• 使用分析师 Agent 综合各方立场
• 记录每个视角的建议
• 找出共识点
• 找出冲突点
• 揭示每个视角所作的假设

第 1 轮输出结构：

## Security Perspective: [Recommendation]

Arguments For:

1. [Argument with evidence]
2. [Argument with evidence]
3. [Argument with evidence]

Concerns About Alternatives:

- [Alternative A]: [Specific concern]
- [Alternative B]: [Specific concern]

Assumptions:

- [Assumption 1]
- [Assumption 2]

第 4 步：辩论第 2 轮——质疑与回应

• 与所有视角分享第 1 轮的所有立场
• 每个视角质疑其他视角的论点
• 每个视角针对质疑为自己的立场辩护
• 使用 analyzer agent 跟踪论据强度
• 确定哪些论据经得起审视
• 记录让步和完善之处

质疑格式：

## [Perspective A] challenges [Perspective B]

Challenge: [Question or counter-argument]
Evidence: [Supporting data or examples]
Request: [What would change your position?]

回应格式：

## [Perspective B] responds to [Perspective A]

Response: [Address the challenge]
Concession: [Points where you agree or adjust]
Counter: [Additional evidence or reasoning]

第 5 步：辩论第 3 轮——寻求共同点

• 确定各视角之间的共识
• 明确指出仍然存在的分歧
• 探索结合不同见解的混合方案
• 使用 architect agent 设计综合方案
• 根据所有视角验证混合方案
• 记录趋同或分歧情况

趋同分析：

## Areas of Agreement

1. [Consensus point 1]
2. [Consensus point 2]

## Remaining Disagreements

1. [Disagreement 1]
   - Security says: [position]
   - Performance says: [position]
   - Potential resolution: [hybrid approach]

## Hybrid Approaches Identified

1. [Hybrid Option 1]
   - Combines: [which perspectives]
   - Trade-offs: [explicit costs/benefits]

第 6 步：主持人综合

• 使用 architect agent 担任中立主持人
• 使用 analyzer agent 评估所有论据
• 系统地回顾所有辩论轮次
• 找出最有力、以证据为基础的论据
• 提出建议并给出置信度
• 详尽记录决策依据
• 明确列出不同意见

综合结构：

## Facilitator Synthesis

### Recommendation

[Clear statement of recommended approach]

### Confidence Level

[High/Medium/Low] confidence based on:

- Consensus level: [X% of perspectives agree]
- Evidence quality: [Strong/Moderate/Weak]
- Risk level: [Low/Medium/High if wrong]

### Rationale

[Explanation of why this recommendation]

### Key Arguments That Won

1. [Argument that swayed decision]
2. [Argument that swayed decision]
3. [Argument that swayed decision]

### Key Arguments Against (Dissenting Views)

1. [Strongest counter-argument]
2. [Remaining concern]

### Implementation Guidance

[How to execute this decision]

### Success Metrics

[How we'll know if this was the right choice]

### Revisit Triggers

[Conditions that would require reconsidering this decision]

第 7 步：记录决策

• 创建决策记录：decisions/YYYY-MM-DD-decision-name.md
• 记录完整的辩论记录
• 包含所有视角的论据
• 记录综合结果和最终决策
• 使用 amplihack.memory.discoveries 中的 store_discovery() 存储到记忆中
• 更新相关架构文档

决策记录模板：

# Decision Record: [Title]

Date: [YYYY-MM-DD]
Status: Accepted
Decision Makers: [List perspectives included]

## Context

[What decision was needed and why]

## Decision

[What was decided]

## Consequences

[What happens because of this decision]

## Alternatives Considered

[What other options were debated]

## Debate Summary

[Key arguments from each perspective]

## Dissenting Opinions

[Perspectives that disagreed and why]

## Review Date

[When to revisit this decision]

---

## Full Debate Transcript

### Round 1: Initial Positions

[Complete positions from all perspectives]

### Round 2: Challenges and Responses

[All challenge/response exchanges]

### Round 3: Convergence Analysis

[Common ground and hybrid approaches]

### Facilitator Synthesis

[Complete synthesis document]

第 8 步：实施决策

• 使用 builder agent 实施选定方案
• 按照综合结果中确定的路径执行
• 实施成功指标的监控
• 设置触发重新审视的告警
• 在代码注释中记录决策
• 如果增加了运维复杂性，则创建运行手册

权衡

成本： 多个 Agent 周期，决策时间更长
收益： 做出有充分依据的决策，发现隐藏风险
适用场景： 难以撤销的决策

示例

示例 1：API 设计——REST 与 GraphQL

配置：

• 视角：5 个（简洁性、性能、用户体验、可维护性、成本）
• 轮次：3
• 收敛方式：综合

辩论摘要：

• 简洁性：REST 简单明了，易于理解
• 性能：GraphQL 可减少过度获取，减少往返次数
• 用户体验：GraphQL 为前端提供灵活性，开发体验更好
• 可维护性：REST 更易于进行版本管理和演进
• 成本：GraphQL 学习曲线更陡，基础设施更复杂

结果： 初始 MVP 使用 REST，v2 使用 GraphQL

• 理由：团队熟悉 REST，能够更快发布
• 迁移路径：6 个月后添加 GraphQL 层
• 触发条件：前端要求每个视图调用 3 个以上端点时

示例 2：测试策略——单元测试与集成测试占主导

配置：

• 视角：3 个（简洁性、可维护性、性能）
• 轮次：2
• 收敛方式：2/3 多数同意

辩论摘要：

• 简洁性：采用单元测试，模拟所有依赖项
• 可维护性：采用集成测试，测试真实交互
• 性能：两者结合，优先优化反馈速度

结果： 70% 单元测试，30% 集成测试（多数同意）

• 理由：单元测试反馈更快，集成测试能发现实际问题
• 异议：简洁性视角希望 90% 使用单元测试（因可维护性方面的顾虑而未采纳）

示例 3：部署策略——Kubernetes 与无服务器

配置：

• 视角：5 个（成本、简洁性、可扩展性、性能、可维护性）
• 轮次：4
• 收敛方式：综合（无多数意见）

辩论摘要：

• 辩论时间长、争议激烈，没有明确的赢家
• 成本和简洁性倾向于无服务器
• 可扩展性和性能倾向于 Kubernetes
• 可维护性意见不一（无服务器更简单，k8s 提供更多控制权）

结果： 采用无服务器方案，并研究 k8s 选项

• 理由：从简单方案起步，团队规模较小，无服务器速度更快
• 混合方案：规模达到 10 倍或出现复杂网络需求时，评估 k8s
• 记录了强烈异议：性能视角认为很快就需要重新评估

理念契合度

此工作流贯彻以下原则：

• 视角多样性： 多种观点揭示隐藏的权衡
• 基于证据： 论点必须有证据支持，而不只是个人观点
• 权衡透明： 记录异议，而不是将其隐藏
• 结构化探索： 辩论形式可防止过早达成一致
• 决策质量： 通过严谨分析做出更好的决策
• 学习： 辩论记录将成为组织知识

与默认工作流的集成

当复杂决策需要多视角分析时，此工作流会替代 DEFAULT_WORKFLOW 的第 4 步（研究和设计）。实施（第 5 步）将根据共识决策进行。