debate-workflow

ディベートワークフロースキル

目的

複数の有効なアプローチが存在する重要なアーキテクチャ上の決定、設計上のトレードオフ、複雑な問題に対して、構造化された多角的なディベートを実施します。

このスキルを使用するタイミング

次の場合に使用してください：

• 主要なアーキテクチャ上の決定（フレームワークの選定、システム設計）
• 明確な優劣がない複雑なトレードオフ
• 複数のチームに影響する、意見の分かれる変更
• 合意形成が必要な影響の大きい決定
• 視点が実際に対立している場合

次の場合は使用しないでください：

• 単純な実装上の選択
• 明らかに正解がある決定
• 時間に追われる緊急修正
• 軽微なリファクタリング
• 定常的な機能追加

設定

コアパラメーター

視点の数：

• 3 - デフォルト（セキュリティ、パフォーマンス、シンプルさ）
• 5 - 拡張版（追加：保守性、ユーザー体験）
• 7 - 包括版（追加：スケーラビリティ、コスト）

ディベートのラウンド数：

• 2 - クイック（立場＋反論）
• 3 - 標準（立場＋反論＋統合）
• 4-5 - 詳細（複数回の反論と応答）

収束基準：

• 100% - 強い合意（すべての視点が一致）
• 2/3 - 多数決（3分の2が合意）
• synthesis - 進行役が最適なハイブリッド案を統合
• evidence - 最も強い証拠や論拠に従う

標準的な視点プロファイル

セキュリティの視点：

• 焦点：脆弱性、攻撃経路、データ保護
• 質問：「何が問題になり得ますか？侵害をどう防ぎますか？」
• エージェント：セキュリティエージェント

パフォーマンスの視点：

• 焦点：速度、スケーラビリティ、リソース効率
• 質問：「これはスケールしますか？ボトルネックは何ですか？」
• エージェント：最適化エージェント

シンプルさの視点：

• 焦点：複雑さを最小限に抑えること、徹底的な簡素化
• 質問：「これが最もシンプルな解決策ですか？抽象化を取り除けますか？」
• エージェント：整理エージェント＋レビューエージェント

保守性の視点：

• 焦点：長期的な進化、技術的負債
• 質問：「将来の開発者が理解できますか？変更はどれほど難しいですか？」
• エージェント：レビューエージェント＋アーキテクトエージェント

ユーザー体験の視点：

• 焦点：API 設計、使いやすさ、開発者体験
• 質問：「直感的に使えますか？ユーザーはどのように操作しますか？」
• エージェント：API 設計エージェント

スケーラビリティの視点：

• 焦点：成長への対応力、分散システム
• 質問：「負荷が10倍になったらどうなりますか？100倍では？」
• エージェント：最適化エージェント＋アーキテクトエージェント

コストの視点：

• 焦点：リソース使用量、インフラコスト、開発時間
• 質問：「投資収益率はどうですか？過剰に設計していませんか？」
• エージェント：分析エージェント

実行プロセス

ステップ1：決定事項を明確にする

• 曖昧さ解消エージェントを使用して、決定すべき事項を明確にします
• プロンプト作成エージェントを使用して、明確な決定プロンプトを作成します
• 決定の範囲と制約を定義します
• ステークホルダーの懸念事項を特定します
• 評価基準を列挙します
• 選択肢を制約する、明示的なユーザー要件を記録します
• 重要：決定事項は、あらかじめ決められた答えではなく、質問として明確にします

決定事項の明確化テンプレート：

# 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ラウンド - 初期の立場

• すべての視点から初期の立場を集めます
• 分析エージェントを使用して、各立場を統合します
• 各視点の推奨事項を記録します
• 合意している点を特定します
• 対立している点を特定します
• 各視点が置いた前提を明らかにします

第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 エージェントを使用して、主張の強さを追跡します
• 精査に耐える主張を特定します
• 譲歩や見直しの内容を記録します

異議を唱える形式：

## [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 エージェントを使用して、統合案を設計します
• すべての視点からハイブリッドなアプローチを検証します
• 意見の収束または分岐を記録します

収束分析：

## 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 エージェントを使用します
• analyzer エージェントを使用して、すべての主張を評価します
• すべてのディベートラウンドを体系的に見直します
• 根拠に基づく最も強力な主張を特定します
• 確信度を添えて推奨事項を示します
• 判断の根拠を詳しく記録します
• 反対意見も明示します

統合の構成：

## 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 エージェントを使用します
• 統合で決めた方針に従います
• 成功指標を監視する仕組みを実装します
• 再検討のトリガーに対するアラートを設定します
• コードコメントに決定内容を記載します
• 運用の複雑さが増す場合は、ランブックを作成します

トレードオフ

コスト： 複数回のエージェントサイクル、より長い意思決定時間 メリット： 十分な根拠に基づく決定、隠れたリスクの発見 最適な用途： 変更に大きなコストがかかる決定

例

例 1：API 設計 — REST と GraphQL の比較

設定：

• 視点：5（シンプルさ、パフォーマンス、ユーザーエクスペリエンス、保守性、コスト）
• ラウンド：3
• 収束方法：統合

ディベートの要約：

• シンプルさ：REST はわかりやすく、広く理解されています
• パフォーマンス：GraphQL は過剰なデータ取得を減らし、往復回数を少なくできます
• UX：GraphQL はフロントエンドの柔軟性を高め、開発者体験を向上させます
• 保守性：REST のほうがバージョン管理や進化が容易です
• コスト：GraphQL は学習コストが高く、インフラストラクチャが複雑です

結果： 初期 MVP では REST を採用し、v2 で GraphQL を導入します

• 根拠：チームが REST に慣れており、より早くリリースできます
• 移行経路：6 か月後に GraphQL レイヤーを追加します
• トリガー：フロントエンドからビューごとに 3 つ以上のエンドポイントが求められた場合

例 2：テスト戦略 — ユニットテスト中心か、統合テスト中心か

設定：

• 視点：3（シンプルさ、保守性、パフォーマンス）
• ラウンド：2
• 収束方法：3 分の 2 の多数決

ディベートの要約：

• シンプルさ：すべての依存関係をモックするユニットテスト
• 保守性：実際の連携をテストする統合テスト
• パフォーマンス：フィードバックの速さを優先して最適化する併用方式

結果： ユニットテスト 70％、統合テスト 30％（多数派が合意）

• 根拠：ユニットテストはフィードバックが速く、統合テストは実際の問題を検出できます
• 反対意見：シンプルさの視点はユニットテストを 90％にすることを望みました（保守性への懸念により却下）

例3：デプロイ戦略 - Kubernetes と Serverless

設定：

• 視点：5（コスト、シンプルさ、スケーラビリティ、パフォーマンス、保守性）
• ラウンド：4
• 合意形成：統合（過半数の賛成なし）

議論の要約：

• 明確な勝者が決まらない、長く意見の分かれる議論
• コストとシンプルさでは Serverless が優勢
• スケーラビリティとパフォーマンスでは Kubernetes が優勢
• 保守性については意見が分かれた（Serverless はよりシンプル、k8s はより高い制御性）

結果： Serverless を採用し、k8s の選択肢についても調査

• 理由：まずはシンプルに始め、チームは小規模であり、Serverless のほうが迅速です
• ハイブリッド：規模が10倍になった場合、または複雑なネットワーク要件が生じた場合に k8s を評価します
• 強い異論を記録：パフォーマンスの視点では、近いうちに再検討が必要になると考えています

哲学との整合性

このワークフローでは、次のことを徹底します。

• 視点の多様性： 複数の視点から、隠れたトレードオフを明らかにします
• エビデンスに基づく議論： 主張は単なる意見ではなく、根拠によって裏付ける必要があります
• トレードオフの透明性： 異論を隠さずに記録します
• 構造化された検討： 議論の形式によって、早急な合意を防ぎます
• 意思決定の質： 厳密な分析を通じて、より良い決定を行います
• 学習： 議論の記録を組織の知識として蓄積します

デフォルトワークフローとの統合

複雑な意思決定で多角的な分析が必要な場合、このワークフローは DEFAULT_WORKFLOW のステップ4（調査と設計）を置き換えます。実装（ステップ5）は、合意された決定に基づいて進めます。