bug-fix

バグ修正の検証

品質を確保し、リグレッションを防ぐための体系的なバグ修正検証ワークフローです。

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

次の場合にこのスキルを使用します。

• 報告されたバグを修正するとき
• バグ修正の PR を作成するとき
• バグ修正の検証を記録する必要があるとき
• 修正によってリグレッションが発生しないことを確認したいとき
• バグ解決に体系的な手順が必要なとき

バグ修正の検証が重要な理由

解決できる問題

• ❌ 根本原因ではなく、症状を修正してしまう
• ❌ 古いバグを修正する際に新しいバグを持ち込む
• ❌ エッジケースのテストが不十分
• ❌ バグが実際に修正された証拠がない
• ❌ 修正理由の記録が不十分

メリット

• ✅ バグが隠されただけでなく、本当に修正されたことを確認できる
• ✅ 根本原因の分析を記録できる
• ✅ テストによってリグレッションを防止できる
• ✅ 関係者に明確な証拠を提示できる
• ✅ チームのコードベースに関する知識を向上できる

バグ修正ワークフロー

ステップ 1：修正前に再現する

重要：まず再現せずにバグを修正してはいけません。

再現チェックリスト

• 再現するための正確な手順を記録する
• エラーメッセージや動作をスクリーンショットで記録する
• 発生頻度を記録する（100％再現する、断続的に発生するなど）
• UI 関連または複雑な操作の場合は動画を録画する
• 影響を受けるバージョンや環境を特定する
• ユーザーが見つけた回避策があれば記録する
• クリーンな環境でもバグが発生することを確認する（ローカル環境だけではない）

再現記録のテンプレート

## Bug Reproduction

### Steps to Reproduce
1. Navigate to `/dashboard`
2. Click "Export Data" button
3. Select date range: Jan 1 - Dec 31
4. Click "Generate Report"

### Expected Behavior
- Report downloads as CSV file
- File contains all transactions for date range
- Download completes in < 5 seconds

### Actual Behavior
- Error appears: "Failed to generate report"
- Console error: `TypeError: Cannot read property 'map' of undefined`
- No file downloads
- Issue occurs 100% of the time

### Environment
- Browser: Chrome 120.0.6099.109
- OS: macOS 14.2
- User Role: Admin
- Data Size: ~10,000 transactions

### Screenshots
![Error message](screenshots/export-error.png)
![Console error](screenshots/console-error.png)

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

何が起きるかだけでなく、なぜバグが発生するかを調査します。

調査手順

1. エラーログを確認する：サーバーログ、ブラウザーのコンソール、エラー追跡を確認する
2. コードパスをたどる：トリガーポイントからエラーまでの実行を追跡する
3. 問題が発生する箇所を特定する：バグが発生する正確な行や関数を見つける
4. 状況を把握する：なぜコードがこのように動作するのかを確認する
5. 最近の変更を確認する：最近のコミットでこの問題が発生したかを確認する
6. 関連コードを確認する：ほかの場所にも似たパターンがないか確認する

根本原因の記録

## Root Cause Analysis

### Investigation
- Error occurs in `generateReport()` function at line 45
- Function assumes `transactions` array always exists
- When date range returns no results, backend returns `null`
- Frontend doesn't handle `null` case, tries to call `.map()` on `null`

### Root Cause
- Missing null check before array operations
- Backend API doesn't return consistent data structure (sometimes `[]`, sometimes `null`)
- No validation of API response shape

### Why This Wasn't Caught
- Unit tests only covered happy path (data exists)
- Integration tests didn't test empty result scenario
- Backend inconsistency not documented in API contract

ステップ 3：修正を実装する

症状ではなく、根本原因を修正します。

修正のガイドライン

• 変更を最小限にする：必要な箇所だけを修正する
• 防御的なコーディング：検証やガードを追加する
• 一貫したパターン：既存のエラー処理パターンに従う
• 型安全性：型を使用して同様のバグを防ぐ
• ドキュメント：自明でない修正にはコメントを付ける

修正の例

// BEFORE (Bug)
function generateReport(transactions) {
  return transactions.map(t => ({
    date: t.date,
    amount: t.amount,
  }));
}

// AFTER (Fixed)
function generateReport(transactions) {
  // Guard against null/undefined from backend
  if (!transactions || !Array.isArray(transactions)) {
    console.warn('No transactions to export');
    return [];
  }

  return transactions.map(t => ({
    date: t.date,
    amount: t.amount,
  }));
}

ステップ 4：修正を検証する

体系的なテストによって、バグが修正されたことを確認します。

検証チェックリスト

• 同じ再現手順を実行する
• バグが発生しなくなったことを確認する
• 修正箇所に関連するエッジケースをテストする
• 新たなエラーが発生していないことを確認する
• 複数の環境（開発環境、ステージング環境）で修正が機能することを確認する
• 修正が期待される動作に合致していることを確認する

検証記録

## Fix Verification

### Testing Performed
1. ✅ Followed original reproduction steps - bug no longer occurs
2. ✅ Tested with empty date range - shows "No data to export" message
3. ✅ Tested with valid date range - exports successfully
4. ✅ Tested with large dataset (50k+ transactions) - works correctly
5. ✅ Tested in Chrome, Firefox, Safari - all working
6. ✅ Tested on staging environment - fix confirmed

### Edge Cases Tested
- Empty result set → Shows appropriate message
- Null response from API → Handled gracefully
- Single transaction → Exports correctly
- Malformed transaction data → Logs error, doesn't crash

### No New Issues
- ✅ No console errors
- ✅ No memory leaks
- ✅ No performance degradation
- ✅ Other export features still work

ステップ 5：リグレッション防止のテストを追加する

重要：すべてのバグ修正にテストを含める必要があります。

テスト要件

• 元のバグを再現するテスト（修正後に成功すること）
• 調査中に判明したエッジケースのテスト
• 複数のコンポーネントが関係するバグの場合は統合テスト
• 新しいシナリオに対応する必要がある場合は、既存のテストを更新する

テストの例

describe('generateReport', () => {
  // Test that reproduces original bug
  it('should handle null transactions gracefully', () => {
    const result = generateReport(null);
    expect(result).toEqual([]);
    expect(console.warn).toHaveBeenCalledWith('No transactions to export');
  });

  // Edge cases
  it('should handle undefined transactions', () => {
    const result = generateReport(undefined);
    expect(result).toEqual([]);
  });

  it('should handle empty array', () => {
    const result = generateReport([]);
    expect(result).toEqual([]);
  });

  it('should handle single transaction', () => {
    const transactions = [{ date: '2025-01-01', amount: 100 }];
    const result = generateReport(transactions);
    expect(result).toHaveLength(1);
    expect(result[0]).toEqual({ date: '2025-01-01', amount: 100 });
  });

  // Original happy path (should still work)
  it('should transform multiple transactions correctly', () => {
    const transactions = [
      { date: '2025-01-01', amount: 100 },
      { date: '2025-01-02', amount: 200 },
    ];
    const result = generateReport(transactions);
    expect(result).toHaveLength(2);
  });
});

ステップ 6：PR に記録する

バグ修正のための包括的な PR の説明を作成します。

バグ修正用 PR テンプレート

## Bug Fix: [Brief Description]

**Ticket**: #123 / ENG-456 / JIRA-789

### Problem
[Clear description of the bug]

### Reproduction Steps (Before Fix)
1. [Step 1]
2. [Step 2]
3. [Error occurs]

**Expected**: [What should happen]
**Actual**: [What happened instead]

### Root Cause
[Detailed explanation of why bug occurred]

- Where: `src/utils/report.ts`, line 45
- Why: Null check missing before array operation
- Impact: Affects all users trying to export with empty date ranges

### Solution
[Explanation of how fix works]

- Added null/undefined check before array operations
- Return empty array instead of crashing
- Added user-facing warning message
- Updated API response handling to be more defensive

### Fix Verification (After)
1. ✅ Followed reproduction steps - bug no longer occurs
2. ✅ Tested edge cases (null, undefined, empty array)
3. ✅ Tested across browsers (Chrome, Firefox, Safari)
4. ✅ Verified on staging environment
5. ✅ No new console errors or warnings

### Test Coverage
- Added unit tests for null/undefined handling
- Added tests for empty array edge case
- Updated integration tests for export feature
- All existing tests still passing

**Coverage**: +15 lines covered, 0 lines uncovered

### Regression Prevention
- [x] Tests added that would catch this bug if reintroduced
- [x] Similar patterns checked in codebase (found 2, fixed in this PR)
- [x] Documentation updated to note API response inconsistency

### Screenshots/Evidence
**Before (Bug)**:
![Error state](screenshots/before-error.png)

**After (Fixed)**:
![Success state](screenshots/after-success.png)
![Empty state](screenshots/after-empty.png)

### Deployment Notes
- No migrations required
- No environment variable changes
- Safe to deploy immediately
- Rollback: Revert this commit

### Related Issues
- Closes #123
- Related to #456 (similar null handling issue)

避けるべきよくある落とし穴

調査中

• ❌ 確認せずに原因がわかったと思い込む
• ❌ 根本原因ではなく、症状を修正する
• ❌ ほかの場所に同様のバグがないか確認しない
• ❌ クリーンな環境での再現を省略する

実装中

• ❌ バグの修正に必要な範囲を超えて変更する
• ❌ バグ修正の PR で無関係なコードをリファクタリングする
• ❌ バグの修正中に機能を追加する
• ❌ 判明したすべてのエッジケースに対応しない

検証中

• ❌ 修正後に正常系だけをテストする
• ❌ 複数の環境でテストしない
• ❌ リグレッションテストを省略する
• ❌ テストした内容を記録しない

ドキュメント作成時

• ❌ 曖昧な PR の説明（「バグを修正」）
• ❌ 根本原因を説明していない
• ❌ 修正前後の証拠がない
• ❌ 元のバグ報告へのリンクがない

バグ修正の品質基準

最低要件

• ✅ 根本原因を特定し、記録している
• ✅ 修正が最小限で、対象が絞られている
• ✅ リグレッションを防ぐテストを追加している
• ✅ 証拠を添えて検証結果を記録している
• ✅ 新たなバグを引き起こしていない
• ✅ サポート対象のすべての環境で動作する

優れた取り組みの指標

• ✅ 類似パターンを確認し、修正している
• ✅ 複数のエッジケースをテストしている
• ✅ パフォーマンスへの影響を測定している
• ✅ チーム内でナレッジを共有している（wiki／ドキュメントを更新）
• ✅ 予防策を提案している

自動化のサポート

バグ修正 PR テンプレート

.github/PULL_REQUEST_TEMPLATE/bug_fix.md を作成します：

## Bug Fix

**Ticket**: [Ticket number/link]

### Problem
[Description of bug]

### Reproduction Steps (Before Fix)
1.
2.
3.

**Expected**:
**Actual**:

### Root Cause
[Explanation of why bug occurred]

### Solution
[How fix works]

### Verification (After)
- [ ] Original reproduction steps no longer trigger bug
- [ ] Edge cases tested
- [ ] Tested in multiple browsers/environments
- [ ] No new errors or warnings

### Test Coverage
- [ ] Tests added for bug scenario
- [ ] Tests added for edge cases
- [ ] All existing tests passing

### Screenshots
**Before**: [Screenshot]
**After**: [Screenshot]

バグ修正 PR 向けの GitHub Actions

name: Bug Fix Verification
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  verify-bug-fix:
    if: contains(github.event.pull_request.labels.*.name, 'bug')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check PR description
        run: |
          PR_BODY="${{ github.event.pull_request.body }}"
          if [[ ! "$PR_BODY" =~ "Root Cause" ]]; then
            echo "::error::Bug fix PR must document root cause"
            exit 1
          fi
          if [[ ! "$PR_BODY" =~ "Verification" ]]; then
            echo "::error::Bug fix PR must document verification steps"
            exit 1
          fi

      - name: Run tests
        run: npm test

      - name: Check test coverage
        run: |
          COVERAGE=$(npm test -- --coverage --json | jq '.total.lines.pct')
          if (( $(echo "$COVERAGE < 90" | bc -l) )); then
            echo "::warning::Test coverage is below 90%"
          fi

成功基準

バグ修正の完了条件

• ✅ バグを再現できなくなっている
• ✅ 根本原因を理解し、記録している
• ✅ 修正が最小限で、対象が絞られている
• ✅ テストでリグレッションを防止している
• ✅ エッジケースに対応している
• ✅ すべての環境で動作する
• ✅ PR のドキュメントが包括的である
• ✅ 新たな問題を引き起こしていない

関連スキル

• universal-verification-pre-merge - マージ前の検証チェックリスト
• universal-verification-screenshot - UI のバグに対する視覚的な検証
• universal-debugging-systematic-debugging - 体系的なデバッグ手法
• universal-debugging-root-cause-tracing - 根本原因の分析手法
• universal-testing-testing-anti-patterns - 避けるべきテストのパターン