tdd

TDD

価値: フィードバック — 検証可能な証拠を伴う短いサイクルにより、AI が生成したコードの信頼性を保ち、人間が主導権を握れます。テストは意図を表し、証拠は進捗を確認します。

目的

実行するハーネスに応じて適応する、5 ステップの TDD サイクル（RED、DOMAIN、GREEN、DOMAIN、COMMIT）を指導します。利用可能な委譲機能を検出し、ガイドモード（人間が各フェーズを進行）または自動モード（システムがフェーズを統括）に振り分けます。モードにかかわらず、プリミティブ型への過度な依存、レビューの省略、未テストの複雑さを防ぎます。

プラクティス

5 ステップのサイクル

すべての機能は、次のサイクルを繰り返して構築します：RED -> DOMAIN -> GREEN -> DOMAIN -> COMMIT。

1. RED -- アサーションを 1 つだけ含む失敗するテストを 1 つ書きます。テストファイルのみを編集します。まだ存在しない型や関数を参照し、実現したいコードを書きます。テストを実行し、失敗の出力を貼り付けます。そこで停止します。 完了条件：テストが実行され、失敗する（コンパイルエラーまたはアサーション失敗）。

2. DOMAIN（RED の後） -- プリミティブ型への過度な依存や無効な状態のリスクについて、テストをレビューします。スタブ本体（todo!()、raise NotImplementedError など）を含む型定義を作成します。ロジックは実装しません。そこで停止します。 完了条件：テストはコンパイルできるが、引き続き失敗する（コンパイルエラーではなく、アサーション失敗またはパニック）。

3. GREEN -- 直近のエラーに対処します。一度に「テストを通す」ことは絶対にしません。変更の前にスコープを確認します。関数の範囲内の作業（約 20 行、1 ファイル）で修正できますか？はい → 変更してテストを実行し、次のエラーを確認します。いいえ → 必要な最小の要素について失敗するユニットテストを書いて掘り下げ、役割を入れ替えた標準の TDD サイクルに回します。掘り下げる場合を除き、本番コードのファイルのみを編集します。変更ごとに出力を貼り付けます。 完了条件：最小限の実装でテストが成功する。

4. DOMAIN（GREEN の後） -- 貧血モデル、漏れ出したバリデーション、見過ごされたプリミティブ型への過度な依存など、ドメイン上の違反がないか実装をレビューします。違反が見つかった場合は懸念を提示し、修正案を提案します。 完了条件：型が適切で、テストも引き続き成功する。

5. COMMIT -- テストスイート全体を実行します。すべての変更をステージし、GWT シナリオを参照する git コミットを作成します。コミット後に git status を実行し、未コミットのファイルが残っていないことを確認します。これは必須のゲートです。このコミットが作成され、作業ツリーがクリーンになるまで、新しい RED フェーズを開始できません。 完了条件：git コミットが作成され、すべてのテストが成功し、作業ツリーがクリーンである。

ステップ 5 の後は、次の RED フェーズを開始するか、コードを整理します（構造上の変更のみを行い、別のコミットにします）。

コンパイル失敗はテストの失敗です。コンパイルエラーを避けるために、型を先回りして作成しないでください。型はテストから導かれるものであり、テストに先立つものではありません。

ドメインレビューは、プリミティブ型への過度な依存や、無効な状態を表現可能にする設計に対する拒否権を持ちます。解決するか、人間にエスカレーションするまで議論を続けます。ラウンド数に制限はありません。

ユーザー向けモード

ガイドモード（/tdd red、/tdd domain、/tdd green、/tdd commit）： 各フェーズでは、そのステップの詳細な手順が記載された references/{phase}.md を読み込みます。フェーズを明示的に制御したい経験豊富なエンジニア向けです。委譲機能を必要とせず、どのハーネスでも動作します。次のフェーズに進むタイミングは人間が決めます。

自動モード（/tdd または /tdd auto）： システムがハーネスの機能を検出し、実行戦略を選択して、サイクル全体を統括します。ユーザーにはコードの作成過程ではなく、動作するコードが表示されます。フェーズの移行や証拠を含む詳細な出力を表示するには、/tdd auto --verbose を使用します。

機能検出（自動モード）

自動モードが有効になったら、次の順序で利用可能なプリミティブを検出します。

1. サブエージェントを利用できますか？ Agent ツールがあるか確認します。利用できる場合は、フェーズごとに特化したエージェントを使うサブエージェント戦略を採用します。
2. フォールバック。 連鎖戦略を使います。単一のコンテキスト内でフェーズごとに内部の役割を切り替えます。

利用可能な中で最も高機能な戦略を選択してください。必要なプリミティブがない場合は、より上位の戦略を試みないでください。

あなたはオーケストレーターです。 このファイルを読むエージェントが機能検出を行い、直接ディスパッチします。単一の「オーケストレーター」サブエージェントを起動して代行させないでください。そうすると作業が隠され、戦略の検出が迂回され、誤った戦略が事前に選択されます。/tdd、パイプライン、その他の呼び出し元のいずれから起動された場合も、あなた自身で機能を検出し、戦略を選択し、フェーズエージェントを起動してください。

戦略を決定した後は、その戦略のエントリーポイントファイルだけを読んでください。

戦略	エントリーポイントファイル
サブエージェント	references/orchestrator.md
連鎖	（エントリーファイルなし ― 以下の連鎖のセクションに従ってください）

連鎖を使用する場合は、orchestrator.mdを読まないでください。

orchestrator.mdでは、すべての戦略に適用されるルール（ドメインによる拒否、外側から内側への進行、パイプライン統合、実装前のコンテキストチェックリスト）としてreferences/shared-rules.mdを参照しています。戦略のエントリーポイントファイルで指示された場合は、shared-rules.mdを読んでください。

実行戦略：連鎖（フォールバック）

委任用のプリミティブがない場合に使用します。エージェントが各役割を順番に担います。

1. references/red.mdを読み込みます。RED フェーズを実行します。
2. references/domain.mdを読み込みます。テストのDOMAINレビューを実行します。
3. references/green.mdを読み込みます。GREEN フェーズを実行します。
4. references/domain.mdを読み込みます。実装のDOMAINレビューを実行します。
5. references/commit.mdを読み込みます。COMMIT フェーズを実行します。
6. 繰り返します。

このモードでは、役割の境界は指針です。エージェントはフェーズの境界を自ら厳守し、現在のフェーズで許可されたファイル形式だけを編集してください（references/phase-boundaries.mdを参照）。

実行戦略：サブエージェント

Agent ツールを利用して、対象を絞ったサブエージェントを起動できる場合に使用します。各フェーズは、範囲を限定した独立のサブエージェントで実行します。

• references/{phase}-prompt.mdのプロンプトテンプレートを使い、各フェーズエージェントをAgent(subagent_type="<agent-name>", prompt="...")で起動します。
• オーケストレーターは、連携ルールに従ってreferences/orchestrator.mdを参照します。
• 構造化引き継ぎスキーマ（references/handoff-schema.md）：各フェーズエージェントは、証拠フィールド（テスト出力、変更したファイルのパス、ドメイン上の懸念事項）を必ず返してください。証拠フィールドが欠けている場合は、引き継ぎを保留します。スキーマが満たされるまで、オーケストレーターは次のフェーズに進みません。
• コンテキストの分離により構造的な制約が実現されます。各サブエージェントには、そのフェーズに関連するファイルのみが渡されます。

名前付きチームメンバーのペルソナ（サブエージェント戦略）

.claude/agents/の定義（ensemble-teamスキル由来）が存在する場合、サブエージェント戦略ではping役とpong役に名前付きペルソナを使用します。オーケストレーターはスライスのコンテキストに基づいてチームメンバーを選択し、Agent(subagent_type="<agent-name>", prompt="...")でサブエージェントとして起動して、結果を次のサブエージェントに渡すコンテキストとして収集します。

連携ルールについてはreferences/orchestrator.mdを、ペルソナの選択、ローテーション、ペアリング履歴についてはreferences/ping-pong-pairing.mdを参照してください。

フェーズ境界ルール

各フェーズで編集できるのは、そのフェーズ専用のファイル形式のみです。これにより、ずれを防止します。ファイル形式の完全な一覧は references/phase-boundaries.md を参照してください。

フェーズ	編集可能	編集不可
RED	テストファイル	本番コード、型定義
DOMAIN	型定義（スタブ）	テストロジック、実装本体
GREEN	実装本体	テストファイル、型シグネチャ
COMMIT	なし -- git 操作のみ	すべてのソースファイル

境界によって作業が妨げられる場合は、停止してオーケストレーター（自動）に戻すか、 ユーザー（ガイド付き）に報告してください。境界を決して迂回してはいけません。

まずウォーキングスケルトンを作成する

最初の垂直スライスは、すべてのアーキテクチャレイヤーが接続されていることを証明する、最小限のエンドツーエンドの経路であるウォーキングスケルトンにする必要があります。ハードコードされた値やスタブを使用してもかまいません。他のスライスに着手する前に作成してください。アーキテクチャのリスクを低減し、後続のスライスが拡張できる、実証済みの配線経路を提供します。

アウトサイドイン TDD

アプリケーション境界、つまり外部入力がシステムに入る地点で受け入れテストを開始します。そこからユニットテストを通じて内部へ進みます。外側の受け入れテストが RED のまま、内側のユニットテストではそれぞれ独自の red-green-domain-commit サイクルを進めます。外側の受け入れテストが通過した時点でのみ、スライスは完了です。

内部関数を直接呼び出すテストは、ユーザーに見える動作を検証していても、受け入れテストではなくユニットテストです。

モードごとの境界の適用：

• パイプラインモード： CYCLE_COMPLETE の証拠には、受け入れテストの boundary_type と boundary_evidence を含める必要があります。パイプラインの TDD ゲートは、受け入れテストが内部関数を直接呼び出す証拠を拒否します。
• 自動モード（パイプライン以外）： オーケストレーターが境界の範囲を確認し、最初のテストが境界テストでない場合は再委任します。これは勧告であり、進行を阻止するゲートはありません。
• ガイド付きモード： 境界レベルのテストを確実にする責任は人間にあります。スキルの説明は正しい動作を指示しますが、それを強制することはできません。

サイクル完了の証拠

RED-DOMAIN-GREEN-DOMAIN-COMMIT の完全なサイクルが終了するたびに、以下を含む CYCLE_COMPLETE 証拠パケットを作成します：slice_id、acceptance_test {file, name, output, boundary_type, boundary_evidence}、unit_tests {count, all_passing, output}、domain_reviews [{phase, verdict, concerns}]、 commits [{hash, message}]、rework_cycles、team {ping, pong, domain_reviewer}。

コンテキストメタデータに pipeline-state が指定されている場合、TDD スキルはパイプラインモードで動作します。このモードでは slice_id を受け取り、証拠を .factory/audit-trail/slices/<slice-id>/tdd-cycles/cycle-NNN.json に保存します。 単独で実行する場合、証拠は参考情報にすぎず、保存されません。

完全なスキーマについては references/cycle-evidence.md を参照してください。

ハーネス固有のガイダンス

Claude Code で実行する場合は、フックベースの適用を含むハーネス固有のルールについて、references/claude-code.md も読んでください。機械的な適用を最大限にするには、bootstrap スキルに references/hooks/claude-code-hooks.json のオプションのフックをインストールするよう依頼してください。

適用に関する注意

• ガイド付きモード：勧告です。人間がフェーズの移行を制御して適用します。
• チェーンモード：勧告です。エージェントがフェーズ境界を自ら適用します。
• サブエージェントモード：構造的です。コンテキストの分離と引き継ぎスキーマによってフェーズ境界を適用します。証拠が不足している場合、引き継ぎはブロックされます。
• パイプラインモード：ゲート方式です。証拠ゲートが不完全なフェーズ移行を拒否します。
• オプションのフック（Claude Code）：機械的に適用します。ツール使用前のフックが、フェーズごとに許可されていないファイル編集をブロックします。references/claude-code.md を参照してください。

厳格な制約：

• フェーズ境界違反（誤ったフェーズで誤ったファイル形式を編集）：[H]
• ドメインの拒否権のエスカレーション（異議のある設計判断）：[RP]
• コミットゲート（前のサイクルがコミットされる前に新しい RED に進まない）：[H]

パイプラインモードでの、テンプレートディレクトリにある references/constraint-resolution.md を参照してください。ここでは、パイプラインの手戻り予算の競合とドメインの拒否権の解決方法について説明しています。

制約

• 連鎖モードの自己強制：自己強制とは、別々のエージェントが制約を適用した場合と同じファイル種別の制限を、自ら守ることです。RED フェーズで本番コードを書くのは、たとえそれを防ぐ仕組みがなくても、この制約に違反します。連鎖モードではフェーズの境界が適用されない理由を考えていることに気づいたら、それは制約に違反しています。
• 「約 20 行、1 ファイル」のスコープ確認：これは厳密な基準ではなく、判断の目安です。趣旨は、変更が複数の関心事や複数のファイルに及ぶ場合、または離れたコードを理解する必要がある場合、その変更は 1 サイクルには大きすぎるということです。1 つのファイル内の 2 つの関数にまたがる 40 行の変更を「1 ファイル」と称して、この目安をすり抜けようとしてはいけません。

検証

サイクルの完了後、以下を検証します。

• 失敗するテストはすべて、実装の前に作成されている
• すべての RED フェーズと GREEN フェーズの後に、ドメインレビューが行われている
• フェーズ境界のルール（ファイル種別の制限）が守られている
• 各引き継ぎ時に証拠（テスト出力）が提示されている
• 完了した RED-GREEN サイクルごとにコミットが存在する
• GREEN フェーズでは、一度に 1 つずつ失敗に対処している（一度に実装を完了させていない）
• 各 COMMIT の後に作業ツリーがクリーンである（git status で確認済み）
• Walking Skeleton が最初に完了している（最初の垂直スライス）

ハードゲート -- COMMIT（新しい RED フェーズを開始する前に必ず通過すること）：

• すべてのテストが成功している
• 現在の GWT シナリオに言及したメッセージで Git コミットが作成されている
• このコミットを作成する前に、新しい RED フェーズを開始していない

依存関係

このスキルは単体で動作します。ワークフローを強化するには、以下と連携します。

• domain-modeling： parse-don't-validate、セマンティック型、無効な状態の防止という原則により、ドメインレビューフェーズを強化します。
• code-review： TDD サイクル完了後に、3 段階のレビュー（仕様への準拠、コード品質、ドメインの整合性）を行います。
• mutation-testing： 本番コードに注入したミューテーションをテストが検出できるかを確認し、テストの品質を検証します。
• ensemble-team： ペア選択とモブレビューに、実務経験に基づく専門家のペルソナを提供します。

依存関係が見つかりませんか？以下を使ってインストールしてください。

npx skills add jwilger/agent-skills --skill domain-modeling