test-guard

Test Guard

コードがリリースされる前に、生成または変更されたテストコードをレビューします。最初のテスト作成を終えた後、テストを提示、コミット、またはマージする前に、以下のルールを適用してください。細かいことにこだわるのではなく、鋭いレビューを行ってください。保守の手間を増やすものや、実際のバグを見えにくくするものを指摘し、見た目の好みは無視してください。

これらのルールがあるのは、コーディングエージェントがテストを過剰に生成するためです。よくある失敗パターンは、実装の詳細を検証するモックだらけの単体テスト、値が一つ違うだけのほぼ重複したテスト本体、そしてプロジェクトのロジックではなくフレームワークを再検証するテストです。どれも差分では有意義に見えますが、その後ずっと保守の負担になります。

このスキルが有効になる場合

• コーディングエージェントが、言語を問わず新しいテスト関数やテストファイルを書いた直後
• 既存のテストを編集している場合
• テストの変更を含む差分をレビューしている場合
• ユーザーからテストの作成、追加、レビューを依頼された場合

まずプロジェクトに合わせる

これらのルールは普遍的ですが、適用方法はプロジェクトによって異なります。レビューの前に、次のことを行ってください。

1. プロジェクト固有のエージェント向け指示（CLAUDE.md、AGENTS.md）とテストに関するドキュメントを確認します。競合する場合は、プロジェクト固有のテストルールをこのスキルより優先します。
2. テストスタックを特定し、具体的なパターンについて該当するリファレンスを読みます。
   • Python / pytest → references/pytest.md
   • PHP / PHPUnit / Pest / WordPress → references/phpunit.md
   • JavaScript / TypeScript / Jest / Vitest → references/jest.md
3. プロジェクトが LLM API を呼び出す、エージェントフレームワークを使う、またはオブザーバビリティ／テレメトリーを組み込んでいる場合は、references/llm-app-testing.md も読みます。LLM アプリケーション固有のルールが3つ追加されています。
4. プロジェクトのシステム境界を把握します。ネットワーク呼び出し、データベース、ファイルシステム、時計と乱数、サードパーティ SDK、LLM API を確認してください。既存のフィクスチャやテストヘルパーを見ると、プロジェクトがどこに境界を設けているかが分かることがよくあります。

実施すること

1. テストコードを読みます。差分、新しいファイル、または変更対象のセクションを確認してください。
2. 各テストが以下のルールに従っているか確認します。
3. 違反があれば簡潔に報告します。ルール番号、場所、違反の理由、修正案を示してください。
4. ユーザーがテスト作成前にこのスキルを明示的に適用するよう求めた場合は、作成時点からルールを適用します。違反するテストを書いてから指摘するのではありません。

新しいテストを書くときは、テストごとに「このテストは、このスイートの他のテストでは検出できないどの具体的なバグを検出するのか？」と考えてください。明確に答えられない場合は、そのテストを書かないでください。

9つのルール

ルール1：実装ではなく動作をテストする

呼び出し側から見たコードの動作をテストします。戻り値と、観測可能な副作用を検証してください。内部ヘルパーが特定の引数で呼び出されたことは決して検証しないでください。そのテストは何も検出しないまま、リファクタリングのたびに壊れます。

違反パターン： システム境界ではない内部関数のモックが呼び出されたことを検証する。 修正方法： 戻り値、または呼び出し側が確認できる状態変化を検証する。

ルール2：すべてのモックには正当な理由が必要

モックはシステム境界でのみ使用します。ネットワークや HTTP の呼び出し、LLM API、データベース、外部ファイルへのファイルシステム入出力、時計と乱数、サードパーティ SDK が該当します。「単体」を切り離すために内部クラスやヘルパー関数をモックしないでください。そうした境界によって、検出すべき統合バグが隠れてしまいます。

境界をモックする場合は、モックが特定の引数を受け取ったことではなく、呼び出し側が応答に対して何をするかを検証してください。

ルール3：テスト1つにつきシナリオ1つ、バリエーションにはデータ駆動を使う

2つ以上のテストでセットアップが同じで、入力／出力の値だけが異なる場合は、1つのデータ駆動テストにまとめます（@pytest.mark.parametrize、PHPUnit の #[DataProvider]、Jest の test.each）。

テストを分けるのが適切な場合： セットアップ、検証内容、モックの設定が異なる場合、または同じ関数を実行するもののシナリオが実質的に異なる場合。

ルール 4：すべてのテストに存在意義が必要です

「ほかのどのテストでも検出できない、どんなバグを検出できますか？」と問いかけてください。タイプミスだけを検出するテスト、データクラスのデフォルト値を確認するテスト、単純な受け渡し処理をテストするものは削除してください。

存在意義がないテストの例： 属性を設定するコンストラクター、型システムですでに禁止されている入力を関数が拒否するかの確認、ログメッセージの文字列フォーマット、定数とそのリテラル値が等しいことの確認。

ルール 5：シナリオに基づいてテストに名前を付けます

パターン：test_<scenario>_<expected_outcome>。関数シグネチャを繰り返すのではなく、要件として読める名前にしてください。

悪い例	良い例
test_parse_response_missing_field	test_malformed_response_falls_back_to_default
test_get_language_no_class	test_element_without_class_returns_empty_language
test_add_tags_single_string	test_single_tag_normalizes_to_list

ルール 6：本番環境の回帰テストは神聖なものです

実際に本番環境で発生したバグを再現するテストには、常に存在意義があります。インシデント（発生日、課題 ID、または短い説明）をテスト名かコメントに記載し、決して削除しないでください。これらはルール 4 の適用対象外です。インシデントそのものが存在意義となります。

ルール 7：フレームワークの保証はテストしません

バリデーションライブラリが検証すること、ORM がコミットすること、ルーターが 404 を返すこと、テストフレームワークのフィクスチャが機能することをテストしないでください。フレームワーク上に構築した、独自のロジックをテストしてください。

違反のパターン： プロジェクト独自のコードをすべて削除し、フレームワークのデフォルトだけを残しても合格するテスト。

ルール 8：状態オブジェクトと値オブジェクトは実物を使い、決してモックにしません

データモデル、DTO、エンティティ、状態オブジェクトをモックにしないでください。実際のインスタンスを構築してください。状態をモックにすると、フィールド名のタイプミスや検証エラーが隠れてしまいます。これらは、まさに検出すべきバグです。実際のオブジェクトを構築するのが大変なら、それは設計を見直すためのフィードバックであり、モックを使う理由にはなりません。小さなビルダーまたはファクトリーヘルパーを追加してください。

ルール 9：テスト対象のインフラストラクチャには実際のインフラストラクチャを使います

データベースクエリ、スキーマの動作、永続化ロジックがテストの対象である場合は、フィクスチャを使って実際のマイグレーションを適用したテスト用データベースに対して実行してください。この場合、セッションをモックしても何もテストできません。永続化がテスト対象の動作における単なる副作用であれば、データベースをモックしてもかまいません。

報告形式

違反を指摘する場合は、次の形式を使ってください。

**Rule N violation** in `tests/path/file.ext::<test_name>`
- What: <one sentence describing the violation>
- Fix: <one sentence describing what to do instead>

違反はファイルごとにまとめてください。違反のないファイルには触れないでください。

重大度の目安

違反の重大度は同じではありません。状況に応じて判断してください。

• 必ず修正： ルール 1、2、8 — 実際のバグを見えにくくしたり、テストを壊れやすくしたりします
• 修正を推奨： ルール 3、4、5、7 — テストの肥大化とメンテナンス負荷につながります
• 神聖なもの： ルール 6 — 決して削除せず、常に許容してください
• 指摘する価値あり： ルール 9 — テストアーキテクチャに関するものです。指摘はしてください。ただし、小規模な変更を妨げる理由にはしないでください

参考資料

• references/pytest.md — Python/pytest のパターン：parametrize、フィクスチャ、モックの境界、実際の Pydantic インスタンス
• references/phpunit.md — PHP/PHPUnit/Pest のパターン：WordPress と WooCommerce のテスト境界を含む
• references/jest.md — Jest/Vitest のパターン：test.each、モジュールのモック、msw、スナップショットの規律
• references/llm-app-testing.md — LLM アプリケーション向けの追加ルール 3 つ：プロンプトの契約、可観測性の配線、エージェントフローの遷移

このスキルが行わないこと

• テストは実行しません。実行にはプロジェクトのテストランナーを使ってください。
• コードスタイルはチェックしません。それはリンターの役割です。
• 何をテストするかは決めません。どのようにテストするかだけを扱います。
• 監査を依頼された場合を除き、変更対象ではないファイルに以前からある違反は指摘しません。