tdd-loop

TDD ループ

TDD は、失敗するテストを一つずつ成功させていく方法です。このスキルは、ループのゲート、完了を示す証拠、厳密なテストファーストが適さない作業のための例外プロトコルを含む手順です。

このループの位置づけ

/implement（Matt Pocock、任意）は一つのチケットを進め、事前に合意した各接点でこのループを呼び出します。これを使わない場合は、チケットごとにこのループを直接進めます。 /tdd（Matt Pocock）はテスト品質の参考資料です。優れたテストとは何か、接点をどこに置くか、アンチパターンは何かを説明します。これはループではありません。この手順の代わりに単独で使ってはいけません。

ループの前に

帰属表記は一切禁止です。出力には、共著者、AI、ツールの帰属表記を追加したり残したりしてはいけません。このワークフローが作成または更新する Markdown ファイルや設定ファイルにも、このルールを含めてください。

ローカルで作業し、本番環境にはアクセスせず、本番環境を対象とする PR も作成しないでください。緊急であることだけを理由に、テストを省略する許可は得られません。緊急のホットフィックスは例外プロトコルを通じて宣言し、課題をクローズする前に回帰テストの失敗を示す証拠が必要です。

1. 変更内容を観測可能な振る舞いとして言い換えます。 一文で、「<入力／操作>のとき、<観測可能な結果>となる」と記述します。この一文を書けない場合、依頼はまだ実装の準備ができていません。/feature-prompt（スコープが不明確な場合）または /diagnosing-bugs（原因が不明確な場合）に回し、そこで止めてください。
2. 接点を特定します。 その振る舞いを担うコード、既存のテスト、プロジェクトで対象を絞ったテストを実行するコマンド（1 ファイルまたは 1 テスト）を見つけます。まず周辺のテストとプロジェクトのスクリプト／CI を確認してください。コマンドがまだ不明確な場合は、references/test-commands.mdで該当するエコシステムの箇所だけを確認してください。ローカルのスタイル、フィクスチャ、命名規則に合わせます。 接点の選択について真に議論の余地がある場合はユーザーに尋ねます。ユーザーが不在なら、選択を明示して作業を進めてください。 実装を選ぶ前に、既存のプロジェクトヘルパーとコンポーネント、次に標準ライブラリまたはプラットフォーム機能、最後にインストール済みの依存関係を確認します。受け入れ基準とプロジェクトの規約を完全に満たす最初の選択肢を採用してください。確立されたプロジェクトコンポーネントは、ネイティブな代替手段より優先します。どれも適さない場合は、不足している振る舞いだけを書きます。数行で明確に書ける内容のために新たな依存関係を追加するのは避け、検証、エラー処理、セキュリティ、アクセシビリティを維持してください。再利用にも、同じ red／green チェックと宣言済みの例外プロトコルが適用されます。
3. 受け入れ基準をテストに対応づけます。 references/ac-matrix.mdに従ってマトリックスを作成します。基準ごと、経路ごと（正常系、境界条件、失敗、代替）に 1 行ずつ設け、さらに範囲チェックを加えます。実行中のアプリに関する行は、適切なプロジェクトの E2E テストで完了させます。それを実行できるランナーがない場合は、/agentic-qaに提出する証拠を記録してください。チケットに基準がない場合は、ステップ 1 の文から基準を作成し、その旨を伝えます。
4. 例外があれば、今ここで宣言します（「例外プロトコル」を参照）。コードを書く前に宣言してください。

宣言済みの例外を除き、対象を絞ったテストコマンドがなければループを実行できません。このリポジトリで 1 つのテストを実行する方法を見つけることはステップ 2 の作業であり、失敗テストを省略する理由にはなりません。

各フェーズの移行時に、Stage / Found / Next / Needs userをそれぞれ 1 行ずつ出力します。移行タイミングは、接点の特定時、各スライスの red から green への移行時、完了時です。

ループ

動作ごとに、まずは最小のスライスから繰り返します。1回のセッションで複数のチケットやバグ修正をまとめて扱う場合、各スライスでは対象を絞ったコマンドと範囲を広げたコマンドだけを実行します。プロジェクト全体のチェックは最後のスライスの後に1回だけ実行します。スライスごとに全体を実行しても、新しい情報は得られません。

1. Red。 新しい動作を検証する失敗するテストを1つだけ書きます。対象を絞ったテストを実行し、失敗の内容を確認します。
   • 失敗の原因は正しくなければなりません。つまり、インポートエラー、タイプミス、設定エラーではなく、動作の欠落による失敗（アサーション失敗）である必要があります。原因が違う失敗は、先に修正してから続行します。
   • 新しいテストがすぐに通った場合は中断の合図です。動作がすでに存在する（そのことを報告して中断する）か、テストが新しい内容を何も検証していない（テストを書き直す）かのどちらかです。このセッションで追加した未コミットのコードが動作を実現している場合は、その変更箇所を戻して失敗を確認してから再適用します。既存の動作として報告してはいけません。
2. Green。 対象を絞ったテストを通すために必要な最小限の変更を行います。推測に基づくパラメーターの追加や、隣接する箇所のクリーンアップは行いません。対象を絞ったテストを再実行します。
3. 範囲を広げる。 関連するテストスイート（モジュールまたはパッケージの範囲）を実行します。この段階ではプロジェクト全体のテストスイートを実行しません。変更によって発生した新しい失敗は、このスライスの一部として、ここで修正します。
   • 既存の失敗と思われるものは、隔離したベースラインのチェックアウト、または条件が一致する変更前の記録済み実行で確認します。作業ツリーの編集を保持し、ベースラインを作るために別の作業を stash してはいけません。ベースラインで実行したコマンドと結果を記録します。確認できない場合は未解決として報告し、古い失敗だと決めつけて対象範囲を問題なしとしてはいけません。
   • アサーションを弱めたり、失敗するテストを削除したりして、テストを通してはいけません。テストの契約を本当に変更する必要がある場合は、その旨を伝えてユーザーの判断を仰ぎます。ユーザーが不在の場合は、古いアサーションが合意済みの動作に反する場合に限って変更し、概要でその変更を明記します。
4. Green の場合のみリファクタリング。 このスライスで変更した箇所について、動作を維持したまま整理し、範囲を広げたテストを再実行します。必要がなければ省略します。
5. 次の行。 次に未対応のマトリックスの行について、Red に戻って繰り返します。変更したコードのガードから導かれる境界ケースも含めます。次のテストが、誰からも求められていない動作を検証することになる段階で終了します。

ループの後

• ドキュメント。 動作を変更した場合は、それを記載しているドキュメントを更新します。README の抜粋、API の例、古い契約を記載したコメントなどが該当します。該当するドキュメントがなければ、その旨を伝えて省略します。

• 概要。 最後に次の内容を記載します。

  Behavior: <the one-sentence behavior>
  Red → Green: <test name(s)> — seen failing (<how>), now passing
  Scope run: <focused command> · <widened command> · <full check | deferred to batch end | widest feasible — why>[; pre-existing failures: <names, baseline command and result>]
  AC map: <AC-n path → test | agentic-qa (surface) | deferred — why>; span check: <finding | none found>
  Edges: <covered: …> · <deferred: … — why>
  Docs: <path updated | nothing documents this behavior>
  Exception: <declared exception + follow-up test plan | none>
  

  エビデンスの項目を具体的に記述する方法が不明な場合に限り、references/summary-example.md を読み込みます。

  次に /code-review を提案し、その後 /commit-push-close または /commit-push-pr を提案します。変更が画面に反映される可能性がある場合、または対象となる行が1つでもある場合は、出荷済みのリビジョンに対する /agentic-qa も提案します。提案のみとし、自動で連続実行してはいけません。どこでも Project Matrix に記載された完全な PROJECT-CODE を使用します。あるプロジェクトの規約、トークン、コンポーネントを別のプロジェクトに混在させてはいけません。

完了基準 — 保証ではなく証拠

以下のすべてを示せる状態が完了です。例外を宣言した場合は、該当しないテストのチェックだけを、指定した検証コマンドまたは手順と確認結果に置き換えます。それらのテストには理由を添えて N/A と記し、成功・失敗の証拠を捏造してはいけません。残りのチェックとフォローアップ計画は維持します。緊急のホットフィックスを宣言した場合、修正前のコミットで回帰テストが失敗し、修正後に成功するのを確認できた時点でのみ完了です。それまでは /commit-push-close を提案せず、その旨を伝えてください。

• 新しいテストはすべて、成功する前に失敗するのを確認しました — 失敗した実行結果を引用してください。（特性評価テストは現状の動作を固定するもので、意図どおり成功します。代わりに、取得した固定出力を引用してください。）
• 絞り込んだテストに合格し、対象範囲を広げたテストにも合格しています（既存の失敗は既存のものと確認し、Scope 実行行に記載済みです）。両方のコマンドを明記してください。
• 出荷を提案する前に、プロジェクト全体のチェック（全テストスイートまたは CI コマンド）が The loop に従い、この一連の変更に対して一度はすべて成功しています — 既存のものと確認して記載した失敗は除きます。または、概要に対象範囲を広げた実行が実行可能な範囲で最も広い理由を記載してください。
• 成功させるためにアサーションを弱めたり、失敗するテストを削除したりしていません（または、契約の変更についてユーザーの判断を仰いでいます）。
• マトリクスのすべての行が、合格したテスト、/agentic-qa に委ねた項目、または理由を添えて延期した項目のいずれかで完了しています。対象範囲のチェックに回答済みで、マトリクス内のテスト品質チェックで未対応項目がないことを確認しています。
• ドキュメントを更新済み、または「この動作を記述したものはありません」と明記しています。
• すべての例外を事前に宣言し、フォローアップのテスト計画を記録しています。

自律性の境界

チケットに番号付きの受け入れ基準があり、境界が事前に合意されていて、要件が的を絞った質問を1回以内に明確にできる場合は、確認を求めずに進めてください。チケットの基準に番号が付いている場合は、各テストの説明に該当する基準を記載します（AC-3: 5回の失敗後にロックする）。トレーサビリティも証拠の一部です。

要件の曖昧さが解消されない場合、作業範囲がチケットの受け入れ基準を超える場合、または認証、決済、データ移行のシナリオにユーザーの承認がない場合は、作業を止めて確認してください。このセッションですでに明示的な承認を得ている場合は、それを有効なものとして扱います。テストを成功させるために、承認を再度求める必要はありません。

例外プロトコル

スパイク、レガシーな境界、緊急のホットフィックス、設定変更、または探索的なリファクタリングの場合は、編集前に references/exception-protocol.md を読み込んでください。ケース、理由、検証方法、フォローアップのテスト計画を宣言してください。例外を理由に、本番環境へのアクセスが認められたり、証拠の提示が黙って省略されたりすることはありません。