ガイド：バグ修正
デバッグワークフローを使うべきとき
/debug（または自然言語で「バグ修正」「エラー修正」「デバッグ」）は、特定のバグを診断して修正する場合に使用します。症状ではなく根本原因を修正する構造化された再現可能なアプローチを提供します。
全ベンダー対応（Gemini、Claude、Codex、Qwen）。Step 1〜5はインライン実行。Step 6（類似パターンスキャン）は広範なスコープでdebug-investigatorサブエージェントに委任可能。
バグレポートテンプレート
必須フィールド
| フィールド | 説明 | 例 |
|---|---|---|
| エラーメッセージ | 正確なエラーテキストまたはスタックトレース | TypeError: Cannot read properties of undefined (reading 'id') |
| 再現手順 | バグをトリガーする順序付きアクション | 1. 管理者でログイン。2. /usersに移動。3. 任意のユーザーで「削除」をクリック。 |
| 期待される動作 | 本来あるべき動作 | ユーザーが削除されリストから消える。 |
| 実際の動作 | 実際に起きること | ページが白い画面でクラッシュする。 |
推奨フィールド
環境（ブラウザ、OS、Node版）、頻度、最近の変更、関連コード、ログ、スクリーンショット。
重要度トリアージ（P0-P3）
P0 — 致命的（即時対応）
本番ダウン、データ損失・破損、セキュリティ侵害。すべてを中断して対応。
P1 — 高（当セッション内）
コア機能が多数ユーザーに影響。回避策はあるが長期的に不可。当セッション内で修正。
P2 — 中（今スプリント）
機能は動作するが品質が劣化。今スプリントで修正。
P3 — 低（バックログ）
見た目の問題、エッジケース、軽微な不便。バックログに追加。
5ステップデバッグループ
Step 1：エラー情報収集
エラーメッセージ、スタックトレース、再現手順、期待vs実際の動作、環境情報。プロンプトにエラーが含まれていればStep 2へ即進行。
Step 2：バグの再現
ツール： search_for_pattern（エラーメッセージ検索）、find_symbol（関数の特定）。
ユーザー報告の症状をコードレベルの位置に変換。
Step 3：根本原因の診断
ツール： find_referencing_symbols（実行パスの逆トレース）。
一般的な根本原因パターン：
- Null/undefinedアクセス — nullチェック欠如、オプショナルチェーニング必要
- レースコンディション — 非同期操作の順序問題、await欠如
- エラーハンドリング欠如 — try/catchなし、Promiseリジェクション未処理
- 型の不一致 — 文字列で数値を期待、スキーマ不正
- 古い状態 — React状態未更新、キャッシュ無効化漏れ
- バリデーション欠如 — 入力未サニタイズ、境界条件未チェック
根本原因を特定することが重要 — 症状ではない。
Step 4：最小修正の提案
根本原因、修正提案、なぜこれが根本原因を修正するかの説明を提示。ユーザー確認までブロック。
最小修正の原則：最少行の変更。リファクタリング、コードスタイル改善、無関係な機能追加をしない。
Step 5：修正適用と回帰テスト作成
- 承認された修正を適用
- 回帰テストを作成：修正なしで失敗、修正ありでパス、将来の再発を防止
Step 6：類似パターンスキャン
search_for_patternで根本原因パターン全体をスキャン。
サブエージェント委任基準： 複数ドメインエラー、スキャンスコープ10ファイル超、深い依存関係トレースが必要。
Step 7：バグのドキュメント化
症状、根本原因、修正、変更ファイル、回帰テスト位置、類似パターンをメモリに記録。
/debugのプロンプトテンプレート
デバッグワークフローをトリガーする際に、構造化されたプロンプトを提供できます：
/debug
Error: TypeError: Cannot read properties of undefined (reading 'id')
Stack trace:
at deleteUser (src/api/users.ts:47:23)
at handleDelete (src/routes/users.ts:112:5)
Steps to reproduce:
1. Log in as admin
2. Navigate to /users
3. Click "Delete" on a user whose organization was deleted
Expected: User is deleted
Actual: 500 Internal Server Error
Environment: Node 22.1, PostgreSQL 16
この構造が効果的な理由：
- エラー + スタックトレースがあれば、Step 2で即座にコード内の位置を特定できます（
search_for_patternで"deleteUser"を検索して関数を発見、find_symbolで正確な位置を特定）。 - 特定のトリガー条件（「組織が削除されたユーザー」）を含む再現手順が、根本原因（null外部キー）を示唆します。
- 環境情報がバージョン固有の的外れな調査を排除します。
より簡単なバグには、短いプロンプトでも動作します：
/debug ログインページで正しいパスワードでも「認証情報が無効です」と表示される
ワークフローが必要に応じて追加の詳細を尋ねます。
エスカレーションシグナル
シグナル1：同じ修正を2回試行
Exploration Loopを起動：2〜3の代替仮説生成、各ワークスペースでテスト、スコアリング、最良採用。
シグナル2：マルチドメインの根本原因
フロントエンドエラー ← バックエンド変更 ← データベースマイグレーション。/workまたは/orchestrateにエスカレート。
シグナル3：再現環境の欠如
本番環境でのみ発生し、ローカルで再現できないバグ。以下のようなシグナルがあります：
- 環境固有の設定差異
- 本番負荷下でのみ発現するレースコンディション
- ステージングと本番でのサードパーティサービスの動作差異
対応： 本番ログを収集し、本番モニタリングへのアクセスを依頼し、修正を試みる前にインストルメンテーション/ロギングの追加を検討してください。
シグナル4：テストインフラ障害
テストインフラを先に修正（oma installで設定）、その後デバッグワークフローに復帰。
修正後検証チェックリスト
- 回帰テストが修正なしで失敗する
- 回帰テストが修正ありでパスする
- 既存テストが引き続きパスする
- ビルドが成功する
- 類似パターンがスキャン済み
- 修正が最小限
- 根本原因がドキュメント化済み
完了条件
- 根本原因が特定・ドキュメント化済み
- ユーザー承認済みの最小修正が適用済み
- 回帰テストが存在
- コードベース全体で類似パターンがスキャン済み
- バグレポートがメモリに記録済み
- 全既存テストが修正後もパス