Bug Fix

Bug Fix (バグ修正スキル)

核心コンセプト: "再現 → 根本原因 → 修正 → 回帰防止" (Reproduce → Root Cause → Fix → Prevent Regression)

このスキルはバグレポートを受け取り体系的に分析し、根本原因を特定して修正し、同じバグが再発しないようテストを追加します。

プロジェクト技術スタック前提

役割分担

入力 (Input)

プロトコル (Protocol)

Phase 1: バグ分析 (Bug Analysis)

目標: バグの正確な位置と条件の把握

Step 1.1: 症状整理

## バグ症状整理

| 項目         | 内容                           |
| ------------ | ------------------------------ |
| **症状**     | [ユーザーが報告した問題]       |
| **期待動作** | [正常に動作すべき方式]         |
| **実際動作** | [現在発生している問題]         |
| **深刻度**   | Critical / High / Medium / Low |

Step 1.2: 関連コード探索

# キーワードで関連ファイル検索
Grep "<keyword>" src/ --type ts --type tsx

# 特定画面/機能の関連ファイル確認 (Feature-First構造)
Glob src/features/<feature>/components/
Glob src/features/<feature>/hooks/

Step 1.3: 再現条件確認

Phase 2: 根本原因分析 (Root Cause Analysis)

目標: "なぜ" バグが発生したかを把握

Step 2.1: コードフロー追跡

Feature-First + Simplified Clean Architecture 基準のフロー分析:

[UI Event] → [Custom Hook] → [API Call] → [Response]
     ↓            ↓              ↓            ↓
   確認        状態変更       fetch実行    データ処理

Step 2.2: 仮説立案と検証

### 仮説リスト

| #   | 仮説    | 検証方法   | 結果  |
| --- | ------- | ---------- | ----- |
| 1   | [仮説1] | [検証方法] | OK/NG |
| 2   | [仮説2] | [検証方法] | OK/NG |
| 3   | [仮説3] | [検証方法] | OK/NG |

Step 2.3: 根本原因確定

## 根本原因

**位置**: `src/features/<feature>/hooks/<file>.ts:123`

**原因**: [具体的な原因説明]

**影響範囲**: [他の機能への影響]

Phase 3: 修正実装 (Fix Implementation)

目標: 最小限の変更でバグ修正

Step 3.1: 修正方針決定

選択基準:

• 最小変更範囲
• 既存パターン準拠
• 副作用最小化

Step 3.2: 回帰テスト先行作成 (TDD)

バグ修正前に、バグを再現するテストケース作成:

// tests/unit/features/<feature>/<file>.test.ts

describe('BUG: [バグタイトル]', () => {
  it('should [正常動作] when [条件]', async () => {
    // Arrange - バグ発生条件設定
    // Act - バグトリガー
    // Assert - 正常動作確認 (現時点では失敗)
  });
});

# テスト失敗確認 (Red) - 必ず失敗してから進行
npm test -- tests/unit/features/<feature>/<file>.test.ts

Step 3.3: 失敗確認 (Red)

• テストが 成功した場合 → テストが不正 → 修正して再実行
• テストが 失敗した場合 → 次のステップへ進行

Step 3.4: コード修正 (Green)

// 修正前
// [問題のあるコード]

// 修正後
// [修正されたコード]

# テスト通過確認
npm test -- tests/unit/features/<feature>/<file>.test.ts

Step 3.5: 静的分析

npm run lint

Phase 4: 検証と完了 (Verification & Completion)

Step 4.1: 全体テスト実行

npm test

Step 4.2: 影響範囲確認

⚡ CHECKLIST UPDATE RULE (MANDATORY): 各確認項目の完了時にチェックリストを再出力し [ ] を [x] に更新すること。 全項目 [x] 確認後に次ステップへ進行すること。 未更新のまま次段階に進行 = Violation Protocol 違反 (severity: HIGH)

• 修正されたファイルと関連する他の機能の動作確認
• 修正による新しい警告なし
• 既存テストすべて通過

Step 4.3: 完了報告

## バグ修正完了

### バグ要約

| 項目         | 内容                  |
| ------------ | --------------------- |
| **症状**     | [症状]                |
| **根本原因** | [原因]                |
| **修正位置** | `<ファイルパス>:<行>` |

### 変更履歴

| ファイル    | 変更タイプ | 説明       |
| ----------- | ---------- | ---------- |
| `src/...`   | 修正       | [説明]     |
| `tests/...` | 追加       | 回帰テスト |

### 検証結果

- 回帰テスト追加・通過
- 全体テスト通過
- npm run lint 通過

### 次のステップ

→ コミット準備完了

特殊ケース処理

Case 1: エラーログがある場合

## エラーログ分析

**エラータイプ**: [Exception/Error タイプ]
**発生位置**: [スタックトレースから抽出]
**発生条件**: [ログから把握した条件]

Case 2: 再現が困難な場合

1. ログ強化: 疑わしい箇所に logger 追加
2. 条件範囲の絞り込み: 可能な条件を一つずつテスト
3. 類似ケース検索: 同じパターンの他のコードを確認

Case 3: 複数原因が複合した場合

1. 分離: 各原因を別イシューに分離
2. 優先順位: 最も影響が大きいものから修正
3. 順次修正: 一つずつ修正しながら中間検証

Case 4: SPECに関連するバグ

バグがSPEC仕様のエラーに起因する場合:

SPEC修正が必要

**問題**: SPECの[セクション]に明示された動作が実際の要件と異なる

**提案**:

1. SPEC修正: `/feature-spec-updater <機能ID>`
2. その後バグ修正を進行

バグ深刻度分類

エラーハンドリング規約 (復習)

API層

/** データ取得 */
async function fetchData(id: string): Promise<DataModel | null> {
  try {
    const response = await fetch(`/api/data/${id}`);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return (await response.json()) as DataModel;
  } catch (error) {
    logger.error('fetchData', `Error fetching data: ${error}`);
    return null;
  }
}

Custom Hook層

/** データ取得Hook */
function useData(id: string) {
  const [data, setData] = useState<DataModel | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    const load = async () => {
      try {
        const result = await fetchData(id);
        if (result === null) {
          setError(MESSAGES.ERROR.DATA_NOT_FOUND);
          return;
        }
        setData(result);
      } catch (e) {
        logger.error('useData', `Error: ${e}`);
        setError(MESSAGES.ERROR.LOAD_FAILED);
      }
    };
    load();
  }, [id]);

  return { data, error };
}

AI 行動指針

DO (すべきこと)

• バグ症状を正確に把握してから分析開始
• 仮説を立てて検証しながら根本原因を探索
• 修正前に必ず回帰テスト作成 (TDD)
• 最小限の変更で問題解決
• 既存コードパターン・コンベンション準拠
• npm run lint 通過確認
• 修正完了後に全体テスト実行
• 変更履歴と検証結果を明確に報告

DON'T (してはいけないこと)

• 症状だけ見て原因推測で修正開始
• テストなしでコード修正
• バグと無関係なリファクタリングを同時進行
• 副作用検討なしに修正完了
• Workaround/一時的対処の適用 (根本解決必須)
• エラー無視 (catch (e) {})
• サイレント失敗の導入

CONTEXT.json 直接更新

状態遷移: Any State → BugFixing

バグ修正作業はどの状態からでも開始可能。作業開始/完了時に CONTEXT.json を直接更新:

バグ修正開始時

## CONTEXT.json 更新内容

1. Read `docs/features/<id>/CONTEXT.json`
2. Edit:
   - quick_resume.current_state → "BugFixing"
   - quick_resume.current_task → "バグ分析: [症状]"
   - quick_resume.next_actions → ["根本原因把握", "回帰テスト作成", "修正実装"]
   - quick_resume.last_updated_at → 現在時刻
   - history[] += 状態遷移記録

バグ修正完了時

{
  "quick_resume": {
    "current_state": "SyncingStatus",
    "current_task": "バグ修正完了、状態同期待ち",
    "next_actions": ["feature-status-sync 実行", "index.md 状態反映"],
    "last_updated_at": "2026-02-11T15:30:00+09:00"
  },
  "decisions": [
    {
      "at": "2026-02-11T15:30:00+09:00",
      "summary": "バグ根本原因: [原因要約]",
      "rationale": "[修正方針選択理由]"
    }
  ],
  "history": [
    {
      "at": "2026-02-11T15:30:00+09:00",
      "from_state": "BugFixing",
      "to_state": "SyncingStatus",
      "triggered_by": "bug-fix",
      "note": "バグ修正完了 - [症状] → [修正内容]"
    }
  ]
}

Wisdom 直接記録

目的: バグ修正過程の学習内容を Wisdom に直接記録し、類似バグの再発防止

作業開始時

Wisdom 参照 (既存エラーパターン確認):

Read(".claude/wisdom/common-errors.md")
Read(".claude/wisdom/project-patterns.md")

作業中に学習発生時

即座に Wisdom に記録 (APPENDのみ使用):

1. 新しいエラーパターン発見時

## {エラー名}

**症状**: {バグ発生状況}
**根本原因**: {なぜ発生したか}
**解決方法**: {どう修正したか}

\`\`\`typescript
// 修正前
{問題コード}

// 修正後
{解決コード}
\`\`\`

**再発防止**: {同一バグ予防策}
**テスト**: {回帰テスト追加}

2. 新しい解決パターン発見時

## {パターン名}

**状況**: {いつ使用するか}
**実装**: \`\`\`typescript
{コード例}
\`\`\`
**根拠**: {なぜこの方法が良いか}

注意事項

バグ修正特化ルール:

• 再現手順 記録必須 (他の開発者が理解できるよう)
• エラーログ 全文含む (スタックトレース全体)
• 回帰テスト 必ず作成 (同一バグ再発防止)

使用例

# 直接呼び出し
/bug-fix "説明パネルでストリーミングが途中で止まる"

# エラーログと共に
/bug-fix "クイズ回答時にNull エラー発生" --log "<エラーログ>"

# 特定ファイル指定
/bug-fix "Diff表示が崩れる" --file src/features/diff-view/components/DiffViewPanel.tsx

参照文書

• CLAUDE.md - エラーハンドリング規約

変更履歴