SDDトラブルシューティングスキル

デバッグ・エラー修正・問題分析のための中核スキル。あらゆる問題に対して体系的に分析し、仕様に基づいた修正方針を策定します。

重要な原則

┌─────────────────────────────────────────────────────────────────┐
│ エラー・バグ発生時の鉄則                                          │
├─────────────────────────────────────────────────────────────────┤
│ 1. 修正コードを書く前に、必ず根本原因を特定する                    │
│ 2. 推測に基づく修正は禁止（「たぶんこれが原因」はNG）             │
│ 3. 修正方針は必ずユーザー承認を得てから実装に進む                 │
│ 4. 原因不明のまま「とりあえず動くように」は禁止                   │
└─────────────────────────────────────────────────────────────────┘

ワークフロー概要

エラー/バグ発生
      ↓
1. 問題事象の確認（現象、再現手順、期待動作）
      ↓
2. ★ 並列調査判定 ★（原因候補が3つ以上 → Agent toolで並列調査）
      ↓
   ┌─ YES → Agent toolで並列調査（下記参照）
   └─ NO  → 単一セッションで分析続行
      ↓
3. 根本原因の分析（コードを追跡して原因を特定）
      ↓
4. 仕様との照合（docs/requirements/ の要求、およびPR本文の設計ノート）
      ↓
5. 修正方針の策定（どう直すか、影響範囲は）
      ↓
6. ★ ユーザー承認 ★（必須ゲート - 承認なしで実装禁止）
      ↓
7. タスク分割 → GitHub Issue起票（デフォルト）/ docs/sdd/tasks/（オプション）

詳細な分析手法: references/analysis_guide_ja.md

このスキルを使用する場面

以下のいずれかに該当する場合は、このスキルを使用する。

テスト・ビルドエラー時

• テストが失敗した場合
• ビルドエラー、コンパイルエラー、型エラー
• lint/静的解析エラー
• CI/CDパイプラインの失敗

実行時エラー・例外発生時

• 例外やエラーがスローされた場合
• クラッシュ・異常終了
• タイムアウト・ハング

デバッグ時

• 期待と異なる動作をしている
• データが正しく処理されない
• 機能が動作しない

問題報告時

• ユーザーからの動作不良報告
• バグや不具合の発見

禁止パターン

❌ エラーメッセージを見てなんとなく修正
❌ とりあえずtry-catchで囲む
❌ 似たエラーを以前直したから同じ修正
❌ 検索で見つけた解決策をそのまま適用
❌ 原因はわからないが動くようになった

✅ このスキルで根本原因を特定 → 修正方針を承認 → 実装

各ステップの概要

ステップ1: 問題事象の確認

収集する情報:

項目	内容
現象	何が起きているか
期待動作	本来どう動くべきか
再現手順	どうすれば再現できるか
発生環境	どの環境で起きるか
エラー情報	エラーメッセージ、ログ、スタックトレース

ステップ2: 根本原因の分析

1. 関連コードの特定（エラーメッセージ、スタックトレースから）
2. コードフローの追跡（入力から出力まで）
3. 原因の特定（なぜその問題が発生するか明確化）

分析テクニック: references/analysis_guide_ja.md

ステップ3: 仕様との照合

• 要求との照合: docs/requirements/ を参照
• 要求との照合: docs/requirements/ の要求と verification を参照。設計方針はPR本文の設計ノートを参照
• 乖離の分類:
  • 実装バグ（仕様は正しいが実装が間違っている）
  • 仕様バグ（仕様自体に問題がある）
  • 仕様漏れ（仕様に記載がない）

ステップ4: 修正方針の策定

検討項目:

• 修正アプローチ（複数ある場合は比較）
• 修正対象ファイル
• 影響範囲
• リスク評価
• 仕様更新の要否

ステップ5: ユーザー承認（必須）

修正方針をユーザーに提示し、承認を得てから次に進む。

修正方針について承認をお願いします。

【修正方針サマリー】
- 問題: [問題の概要]
- 原因: [原因の概要]
- 修正内容: [修正の概要]
- 影響範囲: [影響範囲の概要]

上記の修正方針で進めてよろしいでしょうか？

ステップ6: タスク分割

• 適切な粒度（20-40分程度）
• 1タスク1責務
• 依存関係を明確化
• デフォルト: GitHub Issueとして起票（ラベル sdd:task + sdd:bugfix）。mcp__github__issue_write（create）を使用
• オプション: ユーザーがファイル管理を希望した場合のみ docs/sdd/tasks/に追加

タスクテンプレート:

• Issueモード（デフォルト）: ../task-planning/assets/templates/task_issue_template_ja.md（BugFix用は本文冒頭に問題・原因・分析レポートへのリンクを追記）
• ファイルモード: assets/templates/bugfix_task_template_ja.md

成果物の保存

docs/sdd/troubleshooting/
└── [YYYY-MM-DD]-[issue-name]/
    └── analysis.md

分析レポートテンプレート: assets/templates/analysis_report_template_ja.md

SDDワークフローとの統合

sdd-documentation
    ├── requirement-management → docs/requirements/
    ├── 設計                    → PR本文（永続化しない）
    ├── task-planning        → GitHub Issue（デフォルト）/ docs/sdd/tasks/
    ├── task-executing       → 実装コード
    └── sdd-troubleshooting  → 問題分析・修正タスク（このスキル）

連携するドキュメント:

• 参照: docs/requirements/（仕様照合用）
• 参照: docs/requirements/（要求）、PR本文の設計ノート（設計方針）
• 作成: 修正タスク（デフォルト: GitHub Issue sdd:task+sdd:bugfix / オプション: docs/sdd/tasks/）
• 作成: docs/sdd/troubleshooting/（分析レポート）

Agent toolによる並列調査（条件を満たす場合は積極的に使用）

概要

原因が不明な複雑なバグの場合、Agent toolを使用して複数の仮説を並列で調査する。各サブエージェントが異なる仮説を担当し、並列に調査を進めることで、より迅速に根本原因に到達する。

重要: ワークフローのステップ2で以下の条件を評価し、満たす場合は必ずAgent toolで並列調査すること。

適用条件（ステップ2で必ず判定）

1. 原因の候補（並列調査対象）が3つ以上ある
2. 仮説間に依存関係がない（独立して調査可能）

• すべてYES → Agent toolで並列調査
• いずれかNO → 単一セッションで分析続行

Agent tool呼び出しパターン

調査は読み取り専用のためisolation: worktreeは不要。1つのメッセージで複数のAgent toolを同時に呼び出す。

【Agent tool 呼び出し1】
  subagent_type: general-purpose
  prompt: |
    以下の仮説について調査してください。

    問題: [問題の概要]
    仮説1: データフロー・状態管理の問題
    調査対象: src/state/, src/hooks/

    調査手順:
    1. 関連コードを読み取り
    2. データフローを追跡
    3. 問題の有無を判定
    4. 証拠（該当コード箇所）を収集

    結果を以下の形式で報告:
    - 仮説の支持/棄却
    - 根拠（具体的なコード箇所と説明）
    - 追加発見事項

【Agent tool 呼び出し2】
  subagent_type: general-purpose
  prompt: |
    仮説2: API通信・認証の問題
    調査対象: src/api/, src/auth/
    ...（同様の構造）

【Agent tool 呼び出し3】
  subagent_type: general-purpose
  prompt: |
    仮説3: 非同期処理・タイミングの問題
    調査対象: src/services/, src/workers/
    ...（同様の構造）

注意: 相互反証が特に重要な場合は、エージェントチーム（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS）の使用を検討。メンバー間で直接発見を共有・反証できる。

並列処理パターンの詳細: sdd-documentation/references/agent_teams_guide_ja.md

並列調査後のフロー

1. 各サブエージェントの調査結果を統合
2. 最も有力な根本原因を特定
3. 通常のフローに戻る:
   - 仕様との照合
   - 修正方針の策定
   - ★ ユーザー承認 ★
   - タスク分割

TodoWrite連携

修正タスクの同期

sdd-troubleshootingで修正タスクを追加した場合、TodoWriteにも同期します:

1. 修正タスクを作成
   - Issueモード（デフォルト）: mcp__github__issue_write（create）でラベル sdd:task+sdd:bugfix 付きIssueを起票
   - ファイルモード: docs/sdd/tasks/に作成
2. TodoWriteに修正タスクをpendingで追加:
   todos = [
     ...既存のtodo...,
     { content: "[Phase-N/TASK-XXX](#20) [BugFix] 問題の修正", status: "pending", activeForm: "[TASK-XXX] 問題を修正中" }
   ]

タスクIDの命名

修正タスクには[BugFix]プレフィックスを付けてTodoWriteに登録し、通常タスクと区別（Issueモードは末尾に (#Issue番号)）:

[Phase-2/TASK-010](#20) [BugFix] 認証トークンの有効期限チェック修正

リソース

リソース	内容
references/analysis_guide_ja.md	分析テクニック、問題分類、チェックリスト
assets/templates/analysis_report_template_ja.md	分析レポートテンプレート
assets/templates/bugfix_task_template_ja.md	バグ修正タスクテンプレート