use-workflow-tdd-cycle

name	use-workflow-tdd-cycle
description	RGRC サイクルと Baby Steps による TDD。
when_to_use	TDD, テスト駆動, Red-Green-Refactor, Baby Steps
allowed-tools	Read Write Edit Bash(ugrep:*) Bash(bfs:*)
context	fork
background	false
user-invocable	false

TDD サイクル

公開 API を通して振る舞いをテストする。Mock はシステム境界でのみ。

バリアント選択

トリガー	バリアント	参照
spec.md / 新機能 (/code)	Feature-driven	${CLAUDE_SKILL_DIR}/references/feature-driven.md
バグ報告 / リグレッション (/fix)	Bug-driven	${CLAUDE_SKILL_DIR}/references/bug-driven.md
既存コードベースのカバレッジギャップ	Coverage-driven	テストを active にし skip しない。下記 RGRC を再利用

何をテストするか

優先度	内容
必須	ビジネスロジック、サービス、クリティカルパス、エッジケース
文脈依存	複雑な util、custom hook、変換
スキップ	単純な accessor、UI レイアウト、外部ライブラリの挙動

TDD を使わない場面

文脈	理由
使い捨てのプロトタイプ	廃棄される可能性が高い、コスト > 効果
外部 API 連携	API を mock する。連携は mock しない
単純な one-off スクリプト	テストの方が長くなる
UI 実験	まずビジュアル、後でロジックを抽出

Feature-Driven と Bug-Driven の比較

観点	Feature-Driven	Bug-Driven
トリガー	仕様	バグ報告
テスト状態	当初 skip 状態	active
テスト数	すべて事前生成	主 1 件 + エッジケース
有効化	ユーザー制御	即時
焦点	機能の完成	リグレッション防止

テスト哲学 (Classical/Detroit)

原則	ルール
実装より振る舞い	内部呼び出しではなく公開 API の出力をテストする
状態検証	"X が呼ばれた" ではなく結果値をアサートする
まず実オブジェクト	実依存を使う。外部 I/O のみ mock
ブラックボックス視点	unit を公開インタフェース経由のブラックボックスとして扱う
Sociable テスト	協調オブジェクトを参加させる。境界でのみ隔離する

RGRC サイクル

フェーズ	目標	ルール	よくある間違い
Red	失敗するテスト	失敗が意図する挙動の差分と一致することを確認。syntax/import エラー不可	テストが即座にパスする
Green	テストをパス	"罪を犯してよい" - 汚いコードでも OK	実装しすぎ
Refactor	綺麗なコード	テストを green に保つ。読みやすくなる場合に限り縮める。基準は ~/.claude/rules/PRINCIPLES.md	振る舞いを変更してしまう。難読化する圧縮
Commit	状態を保存	全チェックがパス	チェックを飛ばす

Baby Steps (2 分サイクル)

30s. 失敗するテストを書く → 1min. パスさせる → 10s. テストを実行 → 30s. 小さくリファクタ → 20s. green ならコミット。バグは常に直近の 2 分の変更に潜む。

Vertical Slices のみ

RGRC サイクルは振る舞いごとに縦へ積む。全テストを先に書き、全実装を後でまとめる横方向の展開は決してしない。

Wrong (horizontal):
  Red:   test1, test2, test3, test4, test5
  Green: impl1, impl2, impl3, impl4, impl5

Right (vertical):
  Red → Green: test1 → impl1
  Red → Green: test2 → impl2
  ...

#	横方向スライスの危険
1	一括で書いたテストは実際の挙動ではなく想像した挙動を検証する
2	テストがデータ形状やシグネチャといった構造的なアサーションだけに退化する
3	挙動変化への感度が落ち、壊れていてもパスし正しくても落ちる
4	実装の知見がテスト構造を導くのではなく、テスト構造に追従する

テスト失敗の判断

テストが失敗したら、テストを直すか実装を直すかを判断する。/fix の bug-driven フローでは、再現手順が spec の役割を果たす。

判断	条件	アクション
実装バグ	テストが spec/FR-xxx と一致	実装を修正。テストには触らない
テストバグ	テストが spec から逸脱	テストを修正
不明確	spec が曖昧または欠落	ユーザーにエスカレーション

テスト設計

技法	用途	例
同値分割	同じ振る舞いをグループ化	年齢: <18, 18-120
境界値分析	エッジをテスト	17, 18, 120, 121
デシジョンテーブル	複数条件のロジック	isLoggedIn × isPremium

アサーション品質

すべてのテストは特定の結果を検証すること。弱いアサーションだけでは禁止。悪い例は expect(result).toBeTruthy()、良い例は expect(result).toEqual({ id: 1, name: "Alice" })。1 つのテストは 1 つの概念。同じ関数を同じ引数パターンでアサートする 2 テストがあれば、merge するか test.each で parameterize する。

カテゴリ	matcher	許容される条件
弱い (存在確認)	toBeTruthy, toBeDefined, toBeFalsy, toBeNull, toBeUndefined	同じテスト内に意味のあるアサーションがある場合のみ
意味のある (値)	toBe, toEqual, toStrictEqual, toMatch, toContain, toThrow, toHaveLength	常に推奨
意味のある (call)	toHaveBeenCalledWith, toHaveBeenCalledTimes, toHaveReturnedWith	副作用を検証する場合

Mock

システム境界で mock する。外部 API、データベース、ファイルシステム、ネットワーク、時刻や乱数のような非決定的な依存、2 分サイクルを阻害する遅い依存。

ルール	閾値
テストごとの mock 数	アサーション数を超えてはいけない
mock のスコープ	外部依存のみ
mock の対象	テスト対象モジュールは mock しない

アンチパターン	問題	代わりに
mock が呼ばれたことをアサート	コンポーネントの挙動ではなく mock の挙動をテスト	観測可能な出力または副作用をアサート
テスト用の本番メソッド	テストのために本番 API を汚染	テストユーティリティに抽出するか公開 API を使う
理解前に mock	実依存の挙動を隠す	まず依存を理解してから mock
部分的な mock 構造	フィールド欠落で誤って pass する	実 API の構造をそのままミラーする
mock の使いすぎ	mock がアサートより多い = 配線をテストしている	mock を減らすか意味のあるアサーションを追加

UT 隔離

unit test は次のみ import する。テスト対象モジュール、型、テストインフラ。テストデータは型またはリテラルから組み立てる。

テスト構造

AAA パターン

test("name", () => {
  // Arrange - 準備
  // Act - 実行
  // Assert - 検証
});

命名

レベル	パターン
Suite	describe("[Target]", ...)
Group	describe("[Method]", ...)
Test	it("when [condition], should [expected]", ...)

フレームワーク検出

条件	フレームワーク
vitest が deps に	Vitest
jest が deps に	Jest
bun がランタイム	Bun test
検出できない	Vitest

参照

トピック	ファイル
Feature-driven	${CLAUDE_SKILL_DIR}/references/feature-driven.md
Bug-driven	${CLAUDE_SKILL_DIR}/references/bug-driven.md
Flaky tests	${CLAUDE_SKILL_DIR}/references/flaky-test-management.md
Coverage	${CLAUDE_SKILL_DIR}/../../rules/development/TESTING.md