tdd

テスト駆動開発

実行可能な証拠を真実の根拠として扱います。このワークフローを使って、よくある次の5つのエージェントの失敗を防ぎます。

• 証明せずに推測する
• 何も学ぶ前に大量のテストを書く
• 振る舞いではなく、形や内部実装をテストする
• 自分が管理するコードを過剰にモックする
• フィードバックループが遅くなりすぎて、TDDが機能しなくなる

セッションを始める

コードを編集する前に：

1. AGENTS.md、CLAUDE.md、パッケージやテストのスクリプトなど、リポジトリ内の指示を読みます。
2. 近くにある本番コードとテストを確認し、命名規則、シーム、フィクスチャ、最も速い対象コマンドを把握します。
3. あらかじめ次の2つのコマンドを特定します。
   • 対象の単一テストを実行する最速のコマンド
   • 作業を終える前に、変更した境界を検証するより広範なコマンド
4. 振る舞いを証明できる、最小の公開または準公開シームを選びます。seams.mdを参照してください。
5. 公開コントラクト、意図する振る舞い、必要なカバレッジの範囲に重大な曖昧さがある場合に限り、ユーザーに確認します。

リポジトリ内の指示がこのスキルより厳しい場合は、その指示に従ってください。

垂直方向に進める

テストをすべて先にまとめて書き、その後で実装することは避けてください。

Wrong:
  RED:   test1, test2, test3
  GREEN: impl1, impl2, impl3

Right:
  RED -> GREEN -> REFACTOR: test1 -> impl1
  RED -> GREEN -> REFACTOR: test2 -> impl2
  RED -> GREEN -> REFACTOR: test3 -> impl3

失敗するテストを1つ書きます。妥当な最小限の変更で、そのテストを通します。リファクタリングはテストが成功している状態でのみ行います。これを繰り返します。

取り組み方を選ぶ

新機能

1. リリースする価値のある、ユーザーまたは呼び出し元から見える最小の振る舞いから始めます。
2. 選んだシームで、トレーサーバレットテストを1つ書きます。
3. 正しい理由で失敗することを確認します。
4. テストを成功させるための最も薄い実装を行います。
5. 現在の振る舞いが実証されてから、次の振る舞いを追加します。

バグ修正またはリグレッション

1. コードを変更する前に、考えられる仮説を2〜3個挙げます。
2. バグを検出できたはずの、最小の失敗するリグレッションテストで再現します。
3. 最初の再現が不明瞭な場合は、ログ、アサーション、またはより低いシームを使って再現範囲を絞ります。
4. 失敗しているテストのもとでコードを修正します。
5. 修正が偶然ではなく、対象に限定されたものだと証明できる場合に限り、隣接するテストを1つ追加します。

詳細なミニループについては、bugfixes.mdを参照してください。

レガシーコードまたはリファクタリング

1. 内部構造を変更する前に、特性テストで現在の振る舞いを固定します。
2. より良いシームが設計上に現れるまで、安全策のもとでリファクタリングします。
3. シームが改善したら、広すぎる特性テストのカバレッジを、より焦点を絞った振る舞いテストに置き換えます。
4. テストが成功している状態を保ちながら、モジュールの責務を明確にし、インターフェースを簡素化します。

seams.md、deep-modules.md、refactoring.mdを参照してください。

コアループを実行する

各サイクルで次を行います。

1. RED：1つの振る舞いを証明するテストを1つ書くか、既存のテストを絞り込みます。失敗することを確認します。
2. GREEN：その振る舞いだけを通すための、本番コードへの最小限の変更を行います。
3. REFACTOR：テストが成功している状態を保ちながら、重複、命名、構造を整理します。
4. まず最も関連性の高い小さなコマンドを再実行し、その後、自信が深まるにつれて検証範囲を広げます。

テストが失敗しないなら、ループは無効です。意図的に壊す、シームを低くする、または信頼する前に不足している可観測性を追加してください。

フィードバックを速く保つ

次の順序で進めます。

1. 反復中は対象の単一テストを実行します。
2. 小さな成功サイクルをいくつか重ねたら、周辺のファイル、パッケージ、または焦点を絞ったテストスイートを実行します。
3. 作業を終える前に、関連する統合テストスイート、型チェック、リント、または変更した境界に対する全テストなど、より広範な検証を実行します。
4. 時間、ツール、または環境の制約で広範なチェックを実行できない場合は、検証の不足を明示します。

ループが遅いと感じる場合、シームのレベルが高すぎる可能性があります。振る舞いが本当にブラウザー内またはシステム境界をまたぐ場所にある場合を除き、1つ下のレベルに移動します。

リファクタリング後も通用するアサーションを選ぶ

• ヘルパー関数の呼び出しではなく、観測可能な結果をアサートします。
• 内部の協調オブジェクトより、公開インターフェイスを優先します。
• 制御できないシステム境界だけをモックします。詳しくはmocking.mdを参照してください。
• テストは実装の形を記録するものではなく、振る舞いの仕様として扱います。
• 1つの振る舞いに複数のアサーションが必要な場合でも、各テストは1つの振る舞いを対象にします。

例と書き換えについてはtests.mdを参照してください。

サブエージェントは慎重に使う

他のエージェントに協力してもらう場合：

• 失敗するテスト、レッド／グリーンのサイクル、最終検証の責任はメインスレッドが持ち続けます。
• ワーカーには、既存の失敗するテストを前提に、実装のアイデアやリファクタリングを検討してもらいます。
• テストが誤った振る舞いを検証していた場合を除き、テストを弱めることでしか通らない修正は採用しません。

次のアンチパターンを避ける

• 意味のある失敗テストを確認する前に、対象の振る舞いに合わせて本番コードを編集する
• テスト計画を最初にすべて書く
• 1回のレッド／グリーンのサイクルで複数の振る舞いを解決する
• ほかの方法でもっと速く検証できるロジックに、ブラウザーまたはエンドツーエンドテストを使う
• テストを手軽にするためだけに、自分が所有するモジュールをモックする
• デバッグ用の足場、推測に基づく分岐、未検証のリファクタリングを残す

証明をもって完了する

次の条件を満たした場合にのみ、タスクが完了したと判断します。

• 変更した振る舞いが、変更前には失敗したテストでカバーされている
• 対象のテストが通る
• 関連する、より広範な検証コマンドを実行済みであるか、未実施の理由が明確に記録されている
• リファクタリングはグリーンの状態でのみ行われている
• 最終的な要約に、今回証明された振る舞いと、手動検証に依存する点が記載されている

必要な場合にのみ、さらに読む

• 長期にわたって有効な振る舞いレベルのアサーションと、悪い例から良い例への書き換えについてはtests.md
• 境界のみをモックするルールについてはmocking.md
• 境界の選定、テストレベル、高速なフィードバックについてはseams.md
• 回帰テストを先に書くデバッグについてはbugfixes.md
• テスト可能なインターフェイスについてはinterface-design.md
• 小さなAPIの背後に複雑さを隠す方法についてはdeep-modules.md
• グリーンの状態でのみ行うクリーンアップの対象についてはrefactoring.md