recursive-tdd

recursive-tdd

概要

テスト駆動開発は、recursive-mode のすべての実装作業で必須です。このスキルにより、テストファーストの規律を厳格に守り、recursive-mode のツールで検証できる形で記録できます。

基本原則： テストが失敗するところを確認していないなら、そのテストが適切な対象をテストしているか分かりません。

recursive-mode の鉄則：

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

トリガーの例

• Implement Phase 3 for run '<run-id>'
• Add a failing regression test first, then fix the bug
• I already wrote the code; now add tests（TDD のリセット案内をトリガーする必要があります）
• Follow RED-GREEN-REFACTOR for this change

使用するタイミング

Phase 3（実装）では常に使用します：

• 新機能
• バグ修正
• リファクタリング
• 動作の変更

デフォルトのルール：

• 「単純な」変更でも省略しません
• 「時間に追われている」場合でも省略しません
• 「後からテストしても同じ目標を達成できる」という理由でも省略しません

明示的な例外経路のみ：

• 厳密な RED ファーストのフローが本当に実行不可能な場合は、Phase 3 の成果物に TDD Mode: pragmatic と記載します
• 具体的な例外理由を記録します
• /.recursive/run/<run-id>/evidence/ に代替の検証証拠を記録します
• これは明示的な逸脱として扱い、黙って近道をしないでください

RED-GREEN-REFACTOR サイクル

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    record [label="Record in\nPhase 3 artifact", shape=box];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> record;
}

RED - 失敗するテストを書く

期待する動作を示す、最小限のテストを1つ書きます。

要件：

• 1つのテストにつき1つの動作
• 明確で説明的な名前
• 実際のコードをテストする（避けられない場合を除き、モックは使いません）
• 期待する結果を示す明確なアサーション

```typescript test('rejects empty email with clear error message', async () => { const result = await submitForm({ email: '' }); expect(result.error).toBe('Email is required'); }); ``` ```typescript test('email validation works', async () => { const mock = jest.fn().mockResolvedValue({ valid: true }); const result = await validateEmail(mock); expect(mock).toHaveBeenCalled(); }); ```

RED を検証 - 失敗を確認する

必須です。絶対に省略しないでください。

npm test path/to/test.test.ts

確認事項：

• テストが失敗する（エラーではない）
• 失敗メッセージが想定どおりである
• 機能がまだ実装されていないために失敗している（タイプミスではない）

Phase 3 の成果物に記録：

### TDD Cycle for R3 (Email Validation)

TDD Mode: strict

RED Evidence:
- `/.recursive/run/<run-id>/evidence/logs/red/<file>.log`

GREEN Evidence:
- `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

**RED Phase:**
- Test: `rejects empty email with clear error message`
- Command: `npm test src/forms/email.test.ts`
- Expected failure: "Email is required" not found
- Actual failure: [paste output]
- RED verified: PASS

GREEN - 最小限のコードを書く

テストに合格する、最もシンプルなコードを書きます。

ルール：

• 合格に必要な分だけ書く
• 追加機能は実装しない
• 「ついでに」改善しない
• まだリファクタリングしない

```typescript function submitForm(data: FormData) { if (!data.email?.trim()) { return { error: 'Email is required' }; } // ... rest of form handling } ``` ```typescript function submitForm( data: FormData, options?: { strictMode?: boolean; customValidators?: Validator[]; onValidationError?: (err: Error) => void; } ) { // YAGNI - over-engineered } ```

Phase 3 の成果物に記録：

**GREEN Phase:**
- Implementation: Added null check for email field
- Command: `npm test src/forms/email.test.ts`
- Result: PASS
- GREEN verified: PASS

REFACTOR - 整理する

テストが合格してからのみ実施します：

• 重複を取り除く
• 名前を改善する
• ヘルパーを切り出す
• テストが合格する状態を維持する

リファクタリング中に動作を追加してはいけません。

Phase 3 の成果物に記録：

**REFACTOR Phase:**
- Extracted `validateRequired(field, name)` helper
- Renamed `submitForm` to `processFormSubmission` for clarity
- All tests still passing: PASS

よくあるプロセスの近道（STOP）

言い訳	実際のところ
「単純な修正だから、テストは不要」	単純なコードでも壊れます。テストは30秒でできます。
「修正がうまくいくと確認してからテストする」	テストが最初から合格しても、何も証明できません。バグを検出するところを見ていません。
「後からテストしても同じ目標を達成できる」	テストファーストのテストは「どう動くべきか」を問います。テスト後のテストは「これは何をするのか」を問います。
「手動ではすでにテストした」	場当たり的なテストは体系的なテストとは異なります。記録がなく、再実行できず、リグレッションを防げません。
「動いているコードを削除するのは無駄だ」	サンクコストの誤謬です。検証されていないコードを残すのは技術的負債です。
「TDD は独善的だ。私は現実的にやっている」	TDD は現実的です。コミット前にバグを見つけ、リファクタリングを可能にします。
「参考用にコードを残しておく」	そのコードを流用することになります。それはテストを後から追加するのと同じです。削除とは、削除することです。
「テストしにくいのは、設計が不明瞭だからだ」	テストの声に耳を傾けてください。テストしにくいものは、使いにくいものです。設計をシンプルにしてください。
「まず調査が必要だ」	問題ありません。調査用のコードは破棄し、新たに TDD を始めてください。
「これは……だから違う」	違いはありません。ルールに例外はありません。

危険信号 - STOP して最初からやり直す

次のいずれかに当てはまる場合は、コードを削除し、TDD でやり直してください：

• テストより先にコードを書いた
• テストがすぐに合格する（想定した内容をテストしていない）
• 「テストは後から追加する」
• 「テストするには単純すぎる」
• 「やり方は分かっている。決まりごとに従う必要はない」
• テストが失敗した（または失敗しなかった）理由を説明できない
• 実際の動作ではなく、モックの動作をテストしている
• 1つのテストに複数の動作が含まれている（テスト名に「そして」が含まれる）

recursive-mode Phase 3 との統合

ルーティングへの対応

TDD の実行でレビューの委任、テスト監査、または範囲を限定したルーティング済み実装支援を利用する場合は、委任する CLI／モデルを選択する直前に、以下を再度読み込み、場当たり的にモデルを選択するのではなく、ルーティングされたポリシーまたは明示的なフォールバックを使用してください。

• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

Phase 3 成果物の TDD セクション

すべての Phase 3 成果物には、以下を含める必要があります。

## TODO

- [ ] Replace every placeholder with concrete TDD evidence for the current implementation phase.

## Audit Context

Audit Execution Mode: self-audit / subagent
Subagent Availability: available / unavailable
Subagent Capability Probe: [what proved availability or unavailability]
Delegation Decision Basis: [why self-audit or delegation was chosen]

## TDD Compliance Log

TDD Mode: strict

RED Evidence:
- `/.recursive/run/<run-id>/evidence/logs/red/<file>.log`

GREEN Evidence:
- `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

### Requirement R1 (Feature X)

**Test:** `test/features/x.test.ts` - "should do Y when Z"
- RED: [timestamp] - Failed as expected: [output]
- GREEN: [timestamp] - Minimal implementation: [description]
- REFACTOR: [timestamp] - Cleanups: [description]
- Final state: PASS - all tests passing

### Requirement R2 (Bug Fix)

**Regression Test:** `test/bugs/issue-123.test.ts` - "reproduces crash on empty input"
- RED: [timestamp] - Confirmed bug: [output]
- GREEN: [timestamp] - Fix applied: [description]
- REFACTOR: [timestamp] - N/A (minimal fix)
- Final state: PASS - test passes, bug fixed

## Requirement Completion Status

- `R1` | `implemented` | Changed Files: `path/to/file`
- `R1` | `verified` | Evidence: `/.recursive/run/<run-id>/evidence/logs/green/<file>.log`

厳格モードに従えない場合は、成果物に以下を含める必要があります。

## Pragmatic TDD Exception

Exception reason: [specific reason strict RED-first flow was not feasible]
Compensating validation:
- [extra tests, targeted manual verification, diff review, etc.]
- `/.recursive/run/<run-id>/evidence/<supporting-file>`

Phase 3 カバレッジゲートの追加

## Coverage Gate

- [ ] Every new function has a corresponding test
- [ ] Every bug fix has a regression test that fails before fix
- [ ] All RED phases documented with failure output
- [ ] All GREEN phases documented with minimal implementation
- [ ] All tests passing (no skipped tests)
- [ ] No production code written before failing test

TDD Compliance: PASS / FAIL

Phase 3 承認ゲートの追加

## Approval Gate

- [ ] TDD Compliance: PASS
- [ ] Implementation matches Phase 3 plan
- [ ] No code without preceding failing test
- [ ] All tests documented in TDD Compliance Log

Approval: PASS / FAIL

バグ修正の TDD 手順

1. 最初に回帰テストを追加する

   • バグを再現するテストを記述します
   • テストを実行し、想定されるエラーで失敗することを確認します
   • Phase 3 成果物に失敗を記録します

2. 最小限の修正を実装する

   • テストを通すために必要な変更のみを行います
   • テストを実行し、成功することを確認します
   • Phase 3 成果物に修正内容を記録します

3. リグレッションがないことを確認する

   • テストスイート全体を実行します
   • 他の機能が壊れていないことを確認します
   • Phase 3 成果物に記録します

4. Phase 3 をロックする

   • TDD モードが宣言されている
   • TDD コンプライアンス：PASS
   • 承認：PASS
   • ステータス：LOCKED

例：Phase 3 の TDD セクション全体

## TDD Compliance Log

### R1: Add email validation

**Test:** `test/forms/validation.test.ts`

RED Phase (2026-02-21T10:15:00Z):
```bash
$ npm test test/forms/validation.test.ts
FAIL: Expected 'Email is required', got undefined

RED 確認済み：PASS

GREEN フェーズ（2026-02-21T10:18:00Z）：

• submitForm() 関数に null チェックを追加
• テスト成功 GREEN 確認済み：PASS

REFACTOR フェーズ（2026-02-21T10:22:00Z）：

• validateRequired() ヘルパーを抽出
• すべてのテストが引き続き成功 REFACTOR 完了：PASS

R2：空の配列でクラッシュする問題を修正

回帰テスト： test/utils/array.test.ts

RED フェーズ（2026-02-21T10:25:00Z）：

$ npm test test/utils/array.test.ts
FAIL: TypeError: Cannot read property 'map' of undefined

RED 確認済み：バグを再現 PASS

GREEN フェーズ（2026-02-21T10:27:00Z）：

• processItems() にガード節を追加
• テスト成功 GREEN 確認済み：PASS

REFACTOR：該当なし（2 行の最小限の修正）

検証

テストスイート全体の実行：npm test 結果：47 件成功、0 件失敗

## References

- **REQUIRED:** Follow this skill for all Phase 3 implementation work