tdd-migrate

TDD の移行

エージェントにすべての作業を任せて、TDD の移行をオーケストレーションします。メインコンテキストはクリーンな状態を保ちます。

使用する場面

• 「X を Python から TypeScript に移植する」
• 「既存のパターンに従って N 個のアダプターを作成する」
• 「モジュールを新しいアーキテクチャに移行する」
• 「複数の類似項目を TDD で実装する」

パラメーター

/tdd-migrate <source_path> <target_path> --pattern <reference> --items "item1,item2,item3"

• source_path：分析するパス（既存のコード）
• target_path：新しいコードを作成する場所
• pattern：従うべき参照ファイル／パターン
• items：作成する項目をカンマ区切りで指定したリスト

ワークフロー

Phase 0: YAML TODO List
    │
    ▼
Phase 1: TLDR Analysis ─────────────────┐
    │                                    │
    ▼                                    │ Parallel scouts
Phase 2: Write Failing Tests ───────────┤ per item
    │                                    │
    ▼                                    │
Phase 3: Implement (minimal) ───────────┤
    │                                    │
    ▼                                    │
Phase 4: Build + Pass Tests ────────────┘
    │
    ▼
Phase 5: QLTY Check ────────────────────┐
    │                                    │ Parallel
Phase 6: Review Agent Validates ────────┘
    │
    ▼
Phase 7: TLDR Diff (new vs reference)
    │
    ▼
Phase 8: Fix Issues (if any)
    │
    ▼
Complete

主要な原則

1. メインコンテキストではオーケストレーションのみ行う

   • ファイルを直接読まない（scout を使う）
   • 直接実装しない（kraken／spark を使う）
   • テストを直接実行しない（validator を使う）
   • コンテキストを渡し、調整することだけを行う

2. エージェントがすべての作業を行う

   タスク	エージェント
   調査／分析	scout
   テスト作成＋実装	kraken
   簡単な修正	spark
   テスト実行／検証	validator
   コードレビュー	critic

3. 独立した作業は並行して進める

   • 独立している場合、すべての項目を並行して実装できます
   • レビューと QLTY は並行して実行します
   • TLDR 分析は計画と並行して実行します

4. 主要な各ステップの後にレビューする

   • 実装後：critic がレビューします
   • 修正後：validator が再検証します

手順

ステップ 0：YAML TODO を作成する

YAML の計画ファイルを thoughts/shared/plans/<name>-tdd.yaml に書き込みます：

---
title: <Migration Name>
date: <today>
type: implementation-plan
approach: TDD (test → build → pass → review)

items:
  - name: item1
    file: <target_path>/item1.ts
    test: <target_path>/__tests__/item1.test.ts
    deps: []
  - name: item2
    # ...

reference: <pattern_file>

workflow:
  per_item:
    1: Write failing test
    2: Implement minimal
    3: Build
    4: Pass test
    5: QLTY check
    6: Review
  final:
    7: Integration test
    8: TLDR diff

ステップ 1：Scout エージェントを起動する（並行）

Task (scout): Analyze <source_path> with TLDR
Task (scout): Analyze <pattern> to understand structure
Task (scout): Read migration handoff if exists

ステップ 2：Kraken エージェントを起動する（項目ごとに並行）

各項目について、TDD 全体を実施する kraken を 1 つ起動します：

Task (kraken): Implement <item> using TDD workflow
  1. Read pattern file
  2. Write failing test
  3. Implement
  4. Run: bun test <test_file>
  5. Run: qlty check <impl_file>

ステップ 3：レビュー＋検証（並行）

Task (critic): Review all new files against pattern
Task (validator): Run full test suite
Task (validator): QLTY check all files

ステップ 4：問題を修正する

critic／validator が問題を見つけた場合：

Task (spark): Fix <specific issue>
Task (validator): Re-validate

ステップ 5：TLDR 差分

Task (validator): TLDR diff new files vs reference
  - tldr structure <new_file> --lang <lang>
  - tldr structure <reference> --lang <lang>
  - Compare patterns

ステップ 6：継続性を更新する

完了した作業で台帳を更新します。

例：Rigg アダプター

/tdd-migrate /Users/cosimo/Documents/rigg/src/sdk/providers \
  /Users/cosimo/Documents/rigg/src/sdk/providers \
  --pattern lmstudio.ts \
  --items "xai,cerebras,togetherai,deepinfra,perplexity"

結果：

• kraken エージェント 5 つを並行して実行
• 39 件のテストが成功
• すべてのアダプターが動作
• 合計約 15 分

アンチパターン（避ける）

悪い例	良い例
メインコンテキストでファイルを読む	scout エージェントを起動する
メインコンテキストでコードを書く	kraken／spark エージェントを起動する
メインコンテキストでテストを実行する	validator エージェントを起動する
レビューを省略する	必ず critic を起動する
項目を順番に処理する	kraken を並行して起動する
メインコンテキストで修正する	spark を起動する

エージェントへのプロンプト

Scout（分析）

Explore <path> to understand:
1. Structure/patterns
2. Interfaces/types
3. Dependencies
Return actionable summary for implementation.

Kraken（TDD）

Implement <item> using TDD:
1. Read <pattern> for structure
2. Write failing test to <test_path>
3. Implement minimal to <impl_path>
4. Run: <test_command>
5. Run: qlty check <impl_path>
Report: status, issues, files created.

Critic（レビュー）

Review <files> against <pattern>:
1. Pattern compliance
2. Type safety
3. Missing registrations
4. Security issues
DO NOT edit. Report issues only.

Spark（修正）

Fix <specific issue>:
1. Read <file>
2. Make minimal edit
3. Verify fix

Validator（テスト）

Validate <files>:
1. Run <test_command>
2. Run qlty check
3. Report pass/fail/issues

成功基準

• すべてのテストが成功する
• QLTY で問題が報告されない
• Critic が重大な問題を見つけない
• TLDR 差分でパターンへの準拠が確認できる
• すべての項目が適切に登録／エクスポートされている