tdd

テスト駆動開発

TDD は、赤 → 緑のループです。このスキルは、そのループで維持する価値のあるテストを作成するためのリファレンスです。優れたテストとは何か、テストをどこに配置するか、アンチパターン、ループのルールを説明します。すべてのセクションは各サイクルに適用されます。ループの後ではなく、ループの前と最中に参照してください。

コードベースを調べる際は、テスト名とインターフェースの語彙がプロジェクトのドメイン用語に合うよう、CONTEXT.md が存在する場合は読み、作業対象の領域に関する ADR を尊重してください。

優れたテストとは

テストでは実装の詳細ではなく、公開インターフェースを通じて動作を検証します。コードは全面的に変更される可能性がありますが、テストはそうあるべきではありません。優れたテストは仕様のように読めます。「ユーザーは有効なカートでチェックアウトできる」であれば、どのような機能があるのかが明確にわかります。また、内部構造に依存しないため、リファクタリング後も有効です。

例については tests.md を、モックのガイドラインについては mocking.md を参照してください。

接点 — テストする場所

接点とは、テストする公開境界、つまり内部に立ち入らずに動作を観察するインターフェースです。テストは接点に置き、内部実装はテストしません。

事前に合意した接点のみをテストしてください。 テストを書く前に、テスト対象の接点を書き出し、ユーザーに確認してください。確認されていない接点ではテストを書きません。すべてをテストすることはできません。事前に接点に合意しておくことで、あらゆるエッジケースではなく、重要な経路や複雑なロジックにテストの労力を集中できます。

次のように尋ねてください。「公開インターフェースは何ですか。どの接点をテストすべきですか？」

インターフェースの形状自体が検討対象となる場合、つまりモジュールの深さ、接点を配置する場所、インターフェースで公開する内容を決める場合は、用語について /codebase-design スキルを利用してください。これは、モジュール、インターフェース、深さ、接点、アダプター、レバレッジ、局所性に関する用語の共通の情報源です。セッションを実行するためのものではなく、参照するためのリファレンスです。

アンチパターン

• 実装との結合 — 内部の協調要素をモックする、プライベートメソッドをテストする、またはサイドチャネルを通じて検証する（インターフェースを使わずにデータベースへ問い合わせるなど）。見分けるポイントは、動作が変わっていないのにリファクタリングでテストが失敗することです。
• 同語反復的 — アサーションで期待値をコードと同じ方法で再計算する（expect(add(a, b)).toBe(a + b)、同じ方法で手作業から導いたスナップショット、定数が自身と等しいというアサーションなど）ため、必然的に成功し、コードと食い違うことがありません。期待値は、信頼できる既知のリテラル、具体例、仕様など、独立した真実の情報源に基づく必要があります。
• 水平分割 — すべてのテストを書いてから、すべての実装を書くことです。大量のテストで検証するのは 想像上の 動作です。ユーザー向けの動作ではなく、物事の 形 をテストすることになり、実際の変更にテストが反応しなくなり、実装を理解する前にテスト構造を確定してしまいます。代わりに垂直スライスで進めてください。テストを 1 つ書き、実装し、繰り返します。各テストは、直前のサイクルで得た学びに応じて進むトレーサー・ブレットです。

ワークフロー

1. 計画

コードベースを調べる際は、テスト名とインターフェースの語彙がプロジェクトの言葉に合うよう、プロジェクトのドメイン用語集を使い、作業対象の領域に関する ADR を尊重してください。ループの中でコミットする場合はプロジェクトのコミットスタイルに従い、後で見直すために実装中の判断を記録する場合はプロジェクトのパンくずリストの規約に従ってください。プロジェクトにエージェント向けドキュメントがある場合、どちらもそこに記載されています。

コードを書く前に、次のことを行ってください。

1. モジュールとそのインターフェースの形を定めます。深さ、接点の配置、テスト容易性を考慮した設計については、いずれも /codebase-design スキルを参照してください
2. テストする動作を一覧にします（実装手順ではありません）
3. スライスで UI を描画する場合は、ビジュアルサイクルのルールと agent-browser-vs-design-source ゲートについて、frontend-verification.md を参照してください

2. トレーサーバレット

システムについて1つのことを確認するテストを1つだけ作成します。

RED:   Write test for first behavior → test fails
GREEN: Write minimal code to pass → test passes

これがトレーサーバレットです。処理経路がエンドツーエンドで機能することを証明します。

ビジュアルスライスの場合、RED の成果物はテストではなく、ストーリーや開発用ルートのレンダリングになることがあります。その場合は、ビジュアルゲートで GREEN を完了させます。垂直スライスのルールは同じです。frontend-verification.md を参照してください。

3. インクリメンタルループ

残りの振る舞いごとに、次の手順を繰り返します。

RED:   Write next test → fails
GREEN: Minimal code to pass → passes

ルール：

• 一度にテストは1つ
• 現在のテストに合格するのに必要な分だけコードを書く
• 将来のテストを先回りしない
• 観測可能な振る舞いにテストを集中させる

4. リファクタリング

すべてのテストが合格したら、リファクタリング候補を確認します。

• 重複を抽出する
• モジュールを深化させる（複雑さをシンプルなインターフェースの背後に移す）
• 自然な場合は SOLID 原則を適用する
• 新しいコードから既存のコードについて何がわかるか検討する
• リファクタリングの各ステップ後にテストを実行する

RED の間は絶対にリファクタリングしないでください。 まず GREEN に到達してください。

サイクルごとのチェックリスト

[ ] Test describes behavior, not implementation
[ ] Test uses public interface only
[ ] Test would survive internal refactor
[ ] Code is minimal for this test
[ ] No speculative features added
[ ] Commit follows the project's commit style (one logical change per commit)
[ ] Any non-obvious in-impl decision is captured as a breadcrumb

しおり

実装内の自明でない選択をした場合は、プロジェクトのしおりの規約に従って .scratch/<feature>/decisions.md に項目を追加します。機械的または明白な選択は省略してください。ノイズが増えると、レビュアーは読むのをやめてしまいます。重要なアーキテクチャ上の決定は、しおりではなく ADR に記録してください。

ループが終わったら、次のステップは /prepare-for-review です。