test-first-bugs

テストファーストのバグ修正

回帰を防ぎ、修正の試行を並行して進められる、規律あるバグ修正ワークフローを徹底します。

基本的なワークフロー

バグが報告されたら、次の手順を順番に実行します。

フェーズ 1：再現と記録

1. バグを理解する。期待される動作と実際の動作について詳細を確認します
2. テストの場所を特定する。プロジェクト内でテストが配置されている場所を確認します（tests/、__tests__/、spec/、*.test.*、*.spec.* のパターンを確認します）
3. 失敗するテストを書く。バグを再現するテストを作成します

フェーズ 2：サブエージェントで修正

4. 修正サブエージェントを起動する。Task ツールで subagent_type=general-purpose を指定し、修正を試みます
5. テストを実行する。対象のテストを実行して修正を検証します
6. 必要に応じて繰り返す。テストが失敗する場合は、新しい方法で追加のサブエージェントを起動します

フェーズ 3：検証と完了

7. テストスイート全体を実行する。回帰が発生していないことを確認します
8. 成功を報告する。テストの合格を証拠として、バグが修正されたことを確認します

失敗するテストを書く

テストの命名規則

バグの内容がわかる名前をテストに付けます。

# Python (pytest)
def test_user_login_fails_when_email_has_uppercase():
    ...

# Python (unittest)
def test_should_handle_empty_input_without_crashing(self):
    ...

// JavaScript (Jest/Vitest)
it('should not crash when input array is empty', () => { ... });
test('handles special characters in username', () => { ... });

// TypeScript
describe('UserService', () => {
  it('returns null when user not found instead of throwing', () => { ... });
});

テストの構成

バグ再現テストはすべて、次のパターンに従います。

def test_bug_description():
    # 1. ARRANGE - Set up the conditions that trigger the bug
    input_data = create_problematic_input()

    # 2. ACT - Perform the action that causes the bug
    result = function_under_test(input_data)

    # 3. ASSERT - Verify the expected (correct) behavior
    assert result == expected_value  # This should FAIL initially

適切なテストファイルを見つける

既存のテストパターンをプロジェクトの構造から確認します。

# Find test files
find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" | head -20

# Find test directories
ls -la tests/ __tests__/ spec/ test/ 2>/dev/null

# Check package.json for test command
grep -A5 '"test"' package.json

修正サブエージェントの起動

Task ツールを使って、修正の試行を並行して進めます。

Task tool parameters:
- subagent_type: "general-purpose"
- description: "Fix [bug description]"
- prompt: Include:
  1. The bug description
  2. The failing test location and contents
  3. Suspected cause (if known)
  4. Constraint: "Run the test to verify your fix works"

並行して試す修正方法

異なる方法を試す複数のサブエージェントを起動します。

1. 直接修正エージェント。バグの原因となっているコードを直接修正します
2. 根本原因エージェント。より深いアーキテクチャ上の問題を調査します
3. エッジケースエージェント。関連コードに類似のバグがないか確認します

テストがないプロジェクトの場合

プロジェクトにテスト基盤がない場合は、次の手順を実行します。

1. まず最小限のテストフレームワークをセットアップします
2. 適切な場所にテストファイルを作成します
3. 今後の利用に備えて、テストのセットアップ方法を記録します

テストをすばやくセットアップするコマンド

# Python
pip install pytest
mkdir -p tests && touch tests/__init__.py

# JavaScript/TypeScript
npm install --save-dev jest
# or
npm install --save-dev vitest

# Go
# Tests are built-in, create *_test.go files

修正を検証する

サブエージェントが完了を報告したら、次の手順を実行します。

# Run the specific test
pytest tests/test_module.py::test_bug_description -v
npm test -- --grep "bug description"
go test -run TestBugDescription -v

# Run full suite to check for regressions
pytest
npm test
go test ./...

ワークフローの例

ユーザーからの報告：「メールアドレスにスペースが含まれていると、ログイン関数がクラッシュします」

フェーズ 1、失敗するテストを書く：

# tests/test_auth.py
def test_login_handles_email_with_spaces():
    """Bug: Login crashes when email contains spaces"""
    auth = AuthService()

    # This should return an error, not crash
    result = auth.login("user @example.com", "password")

    assert result.success == False
    assert "invalid email" in result.error.lower()

テストを実行して失敗を確認する：

pytest tests/test_auth.py::test_login_handles_email_with_spaces -v
# Expected: FAILED (demonstrates the bug)

フェーズ 2、サブエージェントを起動する：

Task tool:
- subagent_type: "general-purpose"
- description: "Fix email space crash"
- prompt: "Fix the login crash when email contains spaces.

  Bug: AuthService.login() crashes instead of returning error when email has spaces.

  Failing test: tests/test_auth.py::test_login_handles_email_with_spaces

  After fixing, run: pytest tests/test_auth.py::test_login_handles_email_with_spaces -v

  The test must pass to confirm the fix."

フェーズ 3、検証する：

# Specific test passes
pytest tests/test_auth.py::test_login_handles_email_with_spaces -v
# PASSED

# No regressions
pytest tests/test_auth.py -v
# All tests pass

フックとの連携

このプラグインの bug-report-detector フックは、自動的に次の処理を行います。

1. ユーザーがバグを報告したことを検出します
2. Claude にテストファーストのワークフローに従うよう促します
3. テストファイルが作成または変更されるまで、Edit/Write ツールをブロックします

追加リソース

参照ファイル

• references/test-frameworks.md：フレームワーク固有のテストパターン
• references/common-bugs.md：よくあるバグのパターンとテスト方法

サンプルファイル

• examples/python-bug-test.py：Python の pytest の例
• examples/js-bug-test.js：JavaScript の Jest の例

スクリプト

• scripts/find-tests.sh：プロジェクト内のテスト基盤を特定します