tdd

テスト駆動開発

一度に検証済みの小さな単位で、動作を実装または修正します。低コストでローカルに実行できるテスト経路では、最初に失敗するチェックを作成します。コストが高い、または不明確な経路では、その理由を明示し、最も近い実行可能な検証方法を使います。

契約

入力：

• 機能リクエスト、バグ報告、PRD、イシュー、または実装計画
• 既存のテストコマンドとプロジェクトの規約
• 保護する公開インターフェースまたはユーザー向けの動作

出力：

• 低コストで実行できる経路がある場合の、テストファーストの実装計画
• 実装を依頼された場合の、新規または更新したテストとコード
• 検証コマンド、および変更前に失敗し変更後に成功したことを示す証拠

作成／変更するもの：

• 依頼された動作に必要なテストファイルと本番コード
• 無関係なリファクタリングやテストスイート全体にわたる書き換えは行いません

外部への副作用：

• 既定ではありません
• テストに本番データや外部へのライブ書き込みを使用しないでください

確認が必要な場合：

• 公開 API、スキーマ、マイグレーション、または依頼の範囲を超えるユーザー向けの動作を変更する前

委譲先：

• 広範なテスト戦略やフレームワークのセットアップは testing-expert
• バグ固有の回帰テストと経路の同等性は testing-expert（AI regression mode）
• 根本原因がまだ不明な場合は debug
• テスト境界となるモジュールの seam をまだ整える必要がある場合は codebase-design
• 作業完了を主張する直前は verification-before-completion

低コスト経路の条件

新しいテストを作成するのは、その経路が低コストでローカルに実行できる場合に限ります。

• 対象のコードパスに対する、限定的な単体テスト、コンポーネントテスト、または既存の統合チェック
• 決定論的で、繰り返し実行できるほど高速であり、本番環境専用の状態に依存しない
• 現在壊れている実装ではなく、意図した動作を表す

広範なハーネスのセットアップ、壊れやすいモック、低速なエンドツーエンドのインフラ、曖昧な再現手順、または無関係なフィクスチャの大幅な変更が必要な場合は、新しいテストを作成しないでください。質の悪いテストを作るより、新しいテストを作らない方を選びます。

質の悪いテストとは、主にモックをテストするもの、実装の詳細を固定するもの、タイミングや無関係なグローバル状態に依存するもの、小さな修正に高コストなインフラを必要とするもの、または修正の証明後すぐに削除されるものです。

黙ってテストを省略しないでください。本番コードを変更する前に、失敗するテストにコストをかける価値がない理由と、最も近い実行可能なチェック（対象を絞ったスクリプト、再現コマンド、ブラウザ操作、スナップショット比較、ログアサーション、または限定的な統合チェック）を明示してください。

基本ルール

失敗する動作テストを1つ作成し、成功させてからリファクタリングします。これを繰り返します。

テストでは、公開インターフェースを通じて動作を検証してください。内部のリファクタリング後もテストが通るようにします。動作に問題がないのに、非公開ヘルパーの名前を変えただけで失敗するなら、そのテストは実装に依存しすぎています。

テストを書く前に

GLOSSARY.md と CONTEXT.md があればそれらを読み、関連する ADR も確認してください。テスト名とインターフェース用語が、プロジェクトのドメインに沿うようにします。

1. ローカルのパターンに合致する既存のテストまたは実装を少なくとも3つ見つけます。
2. 最も有用なテスト境界（ユーザーフロー、ルート、サービス API、CLI、または純粋関数）を特定します。
3. ユーザーまたは呼び出し元の用語で動作を説明します。
4. 新しいテストを実行する最小範囲のコマンドを選びます。
5. 有用な垂直スライスに必要な最初の1～3個の動作だけを列挙します。

公開される動作やインターフェースが本当に不明確な場合に限り、質問してください。それ以外の場合は、保守的な前提を置いて作業を進めます。

Red-Green-Refactor ループ

1. Red

観測可能な動作を1つ検証するテストを1つ追加します。

テストは、正しい理由で失敗しなければなりません。

• 非公開の詳細ではなく、公開される動作を実行します。
• 動作が欠けている、または壊れているために失敗します。
• 決定論的で、繰り返し実行できるほど小規模です。

本番コードを変更する前に、新しいテストを実行します。成功した場合、または無関係な理由で失敗した場合は、まずテストか再現手順を修正します。

2. Green

テストを成功させるために必要な、最小限の本番コード変更を行います。

テストが失敗している間は、推測に基づくオプション、将来のための分岐、無関係な整理を追加しないでください。

3. リファクタリング

テストが成功した後に、次の作業を行います。

• 重複を取り除きます。
• リポジトリですでに使われているドメイン用語に沿って、名前を改善します。
• 現在のスライスで必要性が確認できた場合に限り、より明確なインターフェースの背後に複雑さを隠します。
• リファクタリングの各ステップ後に、対象を絞ったテストを再実行します。

垂直スライス

水平方向にまとめて作業するより、薄いエンドツーエンドのスライスを優先します。

良い例：

• 1つの動作テスト
• 1つの実装経路
• 1つの検証コマンド
• デモまたは確認が可能な成果

悪い例：

• まずすべてのテストを作成し、その後ですべてを実装する
• 動作が存在する前に、想定上のデータ構造のテストを作成する
• 計画した設計に合わせるためだけに、内部の協力オブジェクトをモックする
• 個々のスライスに独立した有用性がないのに、レイヤーごとに作業を分割する

バグ修正

バグの場合は、まず再現します。原因が不明な場合は、debug を使います。

原因が分かっており、低コスト経路の条件を満たす場合は、次の手順で進めます。

1. 再現手順を、失敗する回帰テストに変換します。
2. 壊れた動作に対してテストが失敗することを確認します。
3. 動作を修正します。
4. 回帰テストが成功することを確認します。
5. 元の再現手順またはユーザーフローを再実行します。

コミットする場合は、修正前の失敗する再現テストを git の履歴に記録します。差分で経緯が分かるようにします。赤の後に緑です。

適切なテスト境界がない場合は、設計上の課題として明記します。実施可能な最善の検証を追加し、残るリスクを記載します。

ガードレール

• 誤った実装に合わせるためだけにテストを変更しないでください。
• 期待される動作が実際に変わっていない限り、既存のアサーションを弱めないでください。
• 回帰テストはバグに焦点を絞ってください。フィクスチャーに広範な変更を加えるのは避けます。
• バグが不安定な場合は、可能な限りテストを決定的にし、固定したシグナルを文書化してください。
• バグによってより広範な種類の障害が明らかになった場合は、まず対象を絞った経路をリリースし、その後、関連するケースのカバレッジを検討します。

モックのルール

• ネットワーク、時間、乱数、決済プロバイダー、メール、ストレージなど、外部システムをモックします。
• テスト対象のモジュールが所有するコードのモックは避けます。
• 動作の現実性を保てる場合は、フェイクまたはフィクスチャーを優先します。
• 呼び出し自体が公開契約でない限り、実装上の呼び出しをアサートしないでください。

完了チェックリスト

• 新しい動作を、少なくとも1つの失敗後に成功するテストでカバーしているか、スキップする場合は代わりに行う最も近いチェックを明記している。
• テスト名が実装ではなく動作を説明している。
• テストが、呼び出し元またはユーザーが利用できる公開インターフェースを使用している。
• 対象を絞った検証コマンドが成功している。
• 実施可能な場合は、関連するより広範なテストスイート、型チェック、またはリンターのコマンドが成功している。
• このスライスに無関係なリファクタリングや広範な書き換えが含まれていない。

最終応答

結果だけでなく、根拠を報告してください。

• 修正前に失敗したテストまたは実行可能なチェックと、その失敗内容を示します。
• 修正後に成功した実行と、併せて実施した検証を示します。
• 修正前の失敗を確認できなかった場合は、その理由を述べ、代わりに使った最も近い回帰チェックを説明します。

TDD 手順

上記の低コスト経路の条件と垂直スライスの契約を適用する際は、TDD 手順を読んでください。 このエントリーポイントで許可されたスコープとモードを、すべてのステップに適用してください。 この配布版の有効なカタログを通じて他のスキルを解決し、リソースはインストール済みのスキルディレクトリを基準に解決してください。