sc-tdd

テスト駆動開発（TDD）スキル

自動検証によって、厳格な Red-Green-Refactor ワークフローを徹底します。

このスキルは、バリデーターを通じて規律を徹底する TDD ワークフローのステートマシンとして機能します。よくある TDD のアンチパターンを防ぎ、適切なテストファースト開発を実現します。

クイックスタート

# Start TDD for a new feature
/sc:tdd "add user password validation"

# TDD with specific framework
/sc:tdd payment-module --framework pytest

# Fast mode (skip full suite after green, run at end)
/sc:tdd api-endpoint --fast

# Allow snapshot tests
/sc:tdd ui-component --allow-snapshots

動作フロー

このスキルは、7 ステップの Red-Green-Refactor サイクルを徹底します。

1. 初期化 - スコープとフレームワークを検出し、状態を作成します
2. RED：失敗するテストを作成 - 不足している機能のテストを作成します
3. RED：失敗を検証 - バリデーターを実行し、意味的な失敗（コンパイルエラーではなくアサーション）であることを確認します
4. GREEN：最小限の実装 - テストに合格する最小限のコードを記述します
5. GREEN：合格を検証 - バリデーターを実行し、テストの合格とリグレッションがないことを確認します
6. REFACTOR：設計を改善 - テストを安全網としてコードを整理します
7. REFACTOR：安定性を検証 - テストスイートを再実行し、引き続き合格することを確認します

ステートマシン

IDLE → RED_PENDING → RED_CONFIRMED → GREEN_PENDING →
GREEN_CONFIRMED → REFACTOR_PENDING → REFACTOR_COMPLETE → [cycle repeats]

重要なルール：

• バリデーターの出力が唯一の判断基準です - バリデーターがブロックと判定した場合、必ず停止してください
• 終了コードが重要です：0 = 許可、2 = ブロック、3 = エラー（ユーザーに助けを求めてください）
• バイパスは禁止です - フェーズを移行するには、必ずバリデーターの承認が必要です

フェーズ 1：初期化（IDLE → RED_PENDING）

タイミング：ユーザーが TDD ワークフローを要求したとき

実行すること：

1. スコープのルートを検出します：

python .claude/skills/sc-tdd/scripts/framework_detector.py \
  --detect-scope $(pwd) \
  --json

2. 状態を初期化します：

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <detected_scope> \
  --init \
  --json

3. RED_PENDING に移行します：

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <scope> \
  --phase RED_PENDING \
  --evidence "User requested: <feature_description>" \
  --json

出力：初期化を確認し、RED フェーズのルールをユーザーに説明します

フェーズ 2：失敗するテストを作成（RED_PENDING）

ルール：

• ユーザーが最初にテストを作成します
• テストの作成を支援してもかまいません
• テストをコンパイルできるように、空のスタブやインターフェースを追加してもかまいません（例：pass、raise NotImplementedError、空の関数）
• まだ本番実装を書いてはいけません

実行すること：

1. ユーザーによるテストファイルの作成を支援します
2. テストはコンパイルエラーではなく、アサーションによって失敗する必要があることを説明します
3. テストが作成されたら、検証に進みます

フェーズ 3：RED の検証（RED_PENDING → RED_CONFIRMED）

重要：先に進む前に、必ずこのバリデーターを実行してください。

コマンド：

python .claude/skills/sc-tdd/scripts/validate_red.py \
  --scope-root <scope> \
  --json

判定方法：

• 終了コード 0 + "allowed": true → RED_CONFIRMED に進みます
• 終了コード 2 + "allowed": false → 停止し、reasons をユーザーに提示して修正を依頼します

よくあるブロック理由：

• "Test failed but NOT with semantic assertion" - コンパイルエラーです。テストを修正する必要があります
• "Test PASSED (expected failure)" - テストが実際には機能を検証していません
• "No changed test files found" - テストの作成を忘れています

ブロックされた場合：reasons 配列と artifacts.test_output をユーザーに提示し、問題への対処を依頼します。バリデーターが許可するまで、本番コードを提案してはいけません。

許可された場合：artifacts.intent_test の情報を保存して状態を移行し、GREEN フェーズに進みます。

フェーズ 4：最小限の実装（RED_CONFIRMED → GREEN_PENDING）

ルール：

• テストに合格する最小限の実装を書きます
• 完璧さではなく、テストに合格させることに集中します
• 先走った最適化は禁止です
• テスト要件を超える機能の追加は禁止です

実行すること：

1. 現在の状態が RED_CONFIRMED であることを確認します
2. 最小限の本番コードを実装します
3. 実装方針を説明します
4. GREEN_PENDING に移行します：

python .claude/skills/sc-tdd/scripts/tdd_state_machine.py \
  --scope-root <scope> \
  --phase GREEN_PENDING \
  --evidence "Implemented: <description>" \
  --json

5. 検証に進みます

フェーズ 5：GREEN の検証（GREEN_PENDING → GREEN_CONFIRMED）

重要：成功を宣言する前に、必ずこのバリデーターを実行してください。

コマンド（標準）：

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --json

コマンド（高速モード。テストスイート全体を省略）：

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --skip-full-suite \
  --json

判定方法：

• 終了コード 0 + "allowed": true → GREEN_CONFIRMED に移行し、リファクタリングに進みます
• 終了コード 2 + "allowed": false → 停止します。実装が不十分です

よくあるブロック理由：

• "Intent test still FAILING" - 実装によってテストが合格しませんでした
• "Full test suite FAILED - REGRESSION DETECTED" - 既存のテストを壊しました

ブロックされた場合：失敗の詳細をユーザーに提示し、実装を修正して再検証します。

許可された場合：テストに合格し、リグレッションもありません。ユーザーにリファクタリングするか、サイクルを完了するかを尋ねます。

フェーズ 6：リファクタリング（任意、GREEN_CONFIRMED → REFACTOR_PENDING）

ルール：

• 動作を変更せずにコード品質を向上させます
• テストが引き続きパスする必要があります
• 許可される変更：メソッドの抽出、変数名の変更、明確さの向上、重複の削除
• 許可されない変更：機能の追加、テストの期待値の変更、テストの弱体化

実施すること：

1. リファクタリングするかどうかをユーザーに尋ねます
2. はいの場合は、REFACTOR_PENDING に移行します
3. リファクタリング案を提示します
4. 変更を適用します
5. テストを再実行し、安定性を確認します

フェーズ 7：リファクタリングの検証（REFACTOR_PENDING → REFACTOR_COMPLETE）

コマンド：

python .claude/skills/sc-tdd/scripts/validate_green.py \
  --scope-root <scope> \
  --json

（同じバリデーターを使用し、テストが引き続きパスすることを確認します）

許可された場合：サイクル完了です！ユーザーに次のことを尋ねます：

• 次のテストに進みますか？（新しい RED サイクルを開始）
• 機能は完成しましたか？

フラグ

フラグ	型	デフォルト	説明
--framework	string	auto	テストフレームワーク：auto、pytest、jest、vitest、go、cargo
--fast	bool	false	GREEN でのフルスイートをスキップし、機能完成時のみ実行します
--allow-snapshots	bool	false	スナップショットテストを意味上の失敗として許可します
--strict	bool	false	RED ではスタブを許可しません（純粋なテストファーストが必須です）

有効化されるペルソナ

• agent-test-automator - テスト設計の専門知識
• guardian - テスト品質の検証
• agent-python-pro / agent-typescript-react-expert - 言語固有の実装
• architect - アーキテクチャに関する指針

MCP 連携

• PAL MCP
  • mcp__pal__codereview - テスト品質と実装をレビューします
  • mcp__pal__debug - 予期しないテスト失敗を調査します

検出・ブロックされるアンチパターン

バリデーターによってブロックされます：

• テストが失敗する前に本番コードを作成する
• コンパイルエラーを「red」として扱う（実行時のアサーションが必要です）
• 失敗するべきテストがパスする
• GREEN フェーズ中にアサーションを弱める
• フルスイートでのリグレッション

バリデーターによって警告されます：

• スナップショットテスト（--allow-snapshots が指定されていない限りブロックされます）
• 不安定なパターン：モックを使わない sleep、ネットワーク、ランダム処理
• アサーションのないテスト
• 常にパスするテスト

ツールの連携

• Read - 既存のテストファイル、実装コード、フレームワーク設定を読み取ります
• Write - 新しいテストファイル、状態ファイルを作成します
• Edit - テストと実装を段階的に変更します
• Bash - バリデータースクリプトを実行します（必須。バリデーターは必ず実行してください）
• Glob - テストファイル、マニフェストファイル、CI 設定を検索します
• Grep - テストパターン、フレームワークの使用状況を検索します

品質の評価項目

以下の項目で評価されます：

• 正確性（30%） - テストがパスし、仕様どおりに実装が動作する
• 完全性（20%） - すべてのテストシナリオを網羅し、エッジケースに対応している
• テスト容易性（20%） - テストが明確で、保守しやすく、高速かつ決定的である
• 保守性（15%） - コードが整理され、構造が適切で、重複がない
• 規律（15%） - TDD プロセスに従い、近道をせず、適切な Red-Green-Refactor を実施している

基準値：機能完成とするには 70 点以上が必要です

例

例 1：機能開発

/sc:tdd "add password validation: minimum 8 characters"

# Workflow enforced:
# 1. Initialize state for current directory scope
# 2. User/Claude writes test_password_validation.py:
#    def test_password_min_length():
#        assert validate_password("short") == False
#        assert validate_password("longenough") == True
# 3. Run validate_red.py → confirms test FAILS with AssertionError (no validate_password function)
# 4. Claude implements:
#    def validate_password(password: str) -> bool:
#        return len(password) >= 8
# 5. Run validate_green.py → confirms test PASSES, full suite GREEN
# 6. Ask user about refactoring
# 7. Feature complete or next cycle

例 2：TDD によるバグ修正

/sc:tdd "fix: user deletion doesn't cascade to posts" --framework pytest

# Workflow:
# 1. Write test exposing bug (test fails showing cascade doesn't work)
# 2. Validate RED (confirms bug exists)
# 3. Fix cascade behavior
# 4. Validate GREEN (confirms bug fixed, no regressions)

例 3：モノレポのパッケージ

cd backend/user-service
/sc:tdd "add email validation"

# Auto-detects:
# - scope_root: backend/user-service (nearest package.json)
# - framework: jest (from package.json devDependencies)
# - Runs tests only in this package scope

トラブルシューティング

「テストフレームワークが検出されません」

解決策：

1. テストフレームワークがインストールされているか確認します
2. 手動で指定します：--framework pytest
3. フレームワーク設定（pytest.ini、jest.config.js など）が存在することを確認します

「テストは失敗しましたが、意味的なアサーションによる失敗ではありません」

原因：コンパイルエラー、インポートエラー、構文エラー

解決策：

1. テストを修正し、コンパイルして実行できるようにします
2. 必要に応じて空のスタブを追加します：def my_function(): raise NotImplementedError
3. validate_red.py を再実行します

「フルテストスイートがタイムアウトしました」

解決策：

1. サイクルを速くするには --fast モードを使用します
2. フルスイートは機能完成時のみ実行します
3. 遅いテストを調査します

「複数のテストファイルが変更されました」

原因：複数のテストファイルが変更されています（TDD では集中して取り組む必要があります）

解決策：

1. ほかの変更をコミットまたはスタッシュします
2. 一度に 1 つのテストに取り組みます
3. 複数のマイクロサイクルを使用します

状態の復旧

状態ファイルが失われた場合、または破損した場合：

1. バリデーターは git diff と現在のテスト結果からの復旧を試みます
2. 手動で再初期化できます：python tdd_state_machine.py --init --scope-root <path>
3. 状態はスコープごとに管理されるため、複数のパッケージでそれぞれ独立した TDD 状態を保持できます

重要な注意事項

1. フェーズを移行する前に、必ずバリデーターを実行してください - これは必須です
2. 推測よりバリデーターの出力を優先してください - バリデーターがブロックと判定した場合は、停止してください
3. 終了コードは重要です：終了コードと JSON の "allowed" フィールドの両方を確認してください
4. 一度にテストは1つだけ - TDD では小さな単位で進めることが重要です
5. 対象となるのはセマンティックな失敗のみです - コンパイルエラーは適切な「レッド」とは見なされません
6. テストスイート全体が重要です - --fast モードを明示的に使用する場合を除き、スキップしないでください

---

バージョン：1.0.0 最終更新日：2025-01-09 メンテナー：SuperClaude Framework