/afc:debug — バグ診断と修正

バグの根本原因を分析して修正します。 収束ベースの Critic Loop により修正の安全性と正確性を検証します。

引数

• $ARGUMENTS — (必須) バグの説明、エラーメッセージ、または再現手順

プロジェクト設定 (自動読み込み)

!cat .claude/afc.config.md 2>/dev/null || echo "[CONFIG NOT FOUND] .claude/afc.config.md が見つかりません。/afc:init で作成してください。"

実行ステップ

1. 情報収集

1. $ARGUMENTS から抽出します:

   • 症状: 何が間違っているのか?
   • 再現条件: いつ発生するのか?
   • エラーメッセージ: 利用可能な場合は全文
   • 期待される動作: どうなるべきか?

2. 必要に応じてユーザーに追加情報を質問します (最大2問)

2. 根本原因分析 (RCA)

以下の順序で進め、症状タイプに応じて適応的なスキップを適用します:

1. エラートレース: エラーメッセージ/スタックトレースから file:line を抽出 → そのコードを読む
2. データフロー: 問題発生箇所から逆方向にトレース (不正なデータはどこから入ってきたのか?) — エラートレースで既に高い確度で根本原因を特定できた場合はスキップ
3. 状態分析: 関連する状態管理キャッシュ状態を確認 (プロジェクトコンテキストから) — バグが明らかに構文/型/null参照エラーで状態が関係ない場合はスキップ
4. 最近の変更: git log --oneline -10 -- {related files} で最近の変更を確認 — バグが明らかに以前からあるもの (ユーザーが「いつも」失敗すると報告している場合) はスキップ
5. 競合状態: 非同期操作間のタイミング問題をチェック — バグが決定的である場合 (同じ入力は常に失敗し、非同期/並行コンテキストがない場合) はスキップ

ステップをスキップする際は、"Skipped: {理由}" と記述してください。ステップ1のみで根本原因を特定できない限り、ステップ1と2のスキップはしないでください。

3. 仮説の形成

可能な原因を仮説リストとして列挙します:

### 仮説
0. **[バグではない?]** {意図された動作の説明}: {ドキュメント/コード/仕様からの証拠}
1. **[高確度]** {原因1}: {証拠}
2. **[中程度の確度]** {原因2}: {証拠}
3. **[低確度]** {原因3}: {証拠}

仮説0を常に最初に評価してください。 以下をチェック:

• この動作はドキュメント化されているか、仕様で指定されているか? (README、コメント、仕様、CLAUDE.md)
• コードはこのケースを明示的に処理しているか? (意図的なロジック、失われたロジックではなく)
• ユーザーの期待は設計の誤解に基づいていないか?

仮説0が確認された場合 (バグではない):

• 報告: 「これは意図された動作のようです: {証拠付きの説明}」
• コードを変更しないでください。動作が明らかでない場合はドキュメント改善を提案してください。
• ステップ4-6をスキップします。最終出力に直進し、判定は: "バグではない — 意図された動作。" としてください。

仮説0が棄却された場合: 最も高い確度から残りの仮説を検証します。

4. 修正の実装

前提条件: ステップ3で本物のバグが確認された場合のみ進んでください (仮説0が棄却された)。

1. 最小変更の原則: バグを修正するために必要な最小限のコードのみを変更します
2. 影響分析: 修正が他のコードにどのような影響を与えるかを検証します
3. 修正を適用

5. Critic Loop

常に ${CLAUDE_SKILL_DIR}/../../docs/critic-loop-rules.md を読み、それに従ってください。

収束するまで Critic Loop を実行します。安全性上限: 5パス。

ファストパス: 修正が1行の変更 (null ガード、タイプミス、不足しているインポート) で動作上の副作用がない場合: 両方の基準で1パス実行します。1パス目で両方が PASS の場合、対立的チャレンジなしで直ちに収束します。

基準	検証
安全性	修正により他の機能が破損しないか? 副作用はないか?
正確性	実際に根本原因を解決しているか? 単に症状を隠していないか?

docs/critic-loop-rules.md に従い、判定処理と出力形式に従います。

6. 検証

{config.gate}

失敗時は修正後に再試行します (最大3回)。

7. 回顧エントリ (新しいパターンが見つかった場合)

このデバッグセッションが .claude/afc/memory/retrospectives/ に以前ドキュメント化されていないパターンを明らかにした場合:

.claude/afc/memory/retrospectives/{YYYY-MM-DD}.md に追記します:

## パターン: {カテゴリ}
**何が起きたか**: {具体的な説明}
**根本原因**: {このバグが発生した理由}
**予防ルール**: {実行可能なルール — 今後の plan/implement フェーズで使用可能}
**重大度**: Critical | Warning

パターンが新しく、実行可能な場合のみ記述してください。一般的な観察は禁止です。

8. 最終出力

バグが確認され修正された場合:

Debug complete
├─ Root cause: {1行の要約}
├─ Fixed files: {ファイルリスト}
├─ Critic: converged ({N} パス、{M} 修正、{E} エスカレーション)
├─ Verified: typecheck + lint passed
└─ Impact scope: {影響を受けるコンポーネント/機能}

バグではない場合 (意図された動作):

Debug complete
├─ Verdict: Not a bug — intended behavior
├─ Explanation: {この動作が正しい理由}
├─ Evidence: {コードパス、ドキュメント、または仕様への参照}
├─ Fixed files: none
└─ Suggestion: {動作が明らかでない場合はドキュメント改善、または「none」}

注記

• すべてのレポートがバグとは限りません: 常に「意図された動作」仮説を最初に評価してください。不正な期待に合わせてコードを変更しないでください。
• 過度な変更はしません: バグを修正するために必要なものだけを変更してください。周囲のコードをリファクタリングしないでください。
• 症状と原因: 表面的な症状ではなく根本原因を見つけてください。
• 3回の試行限度: 3回の試行後に修正に失敗した場合は、その状況をユーザーに報告してください。