tdd-migration-pipeline

TDD 移行パイプライン

コードベースを移行または書き換えるための、オーケストレーター専用ワークフローです。自分でファイルを読んだり、コードを書いたり、検証したりすることはありません。エージェントに指示し、コンテキスト（内容ではなくパス）を受け渡すだけです。

使用する場面

• コードベースを別の言語またはフレームワークに移行する場合
• TDD による保証を備えたシステムを書き換える場合
• 振る舞いの契約を伴う大規模なリファクタリングを行う場合
• オーケストレーターのコンテキストを増やしたくない場合

基本原則

1. オーケストレーターは一切実行しない - 指示とコンテキストの受け渡しのみ
2. すべての作業はエージェントが行う - 自分で読み取り、書き込み、検証を行わない
3. コンテキストウィンドウを一定に保つ - 内容ではなくパスを渡す
4. 新しいコードは別のディレクトリに配置する - ソースは決して変更しない

制約

• 「読んでみます」や「確認しています」と言わない
• 「エージェント X：Z を使って Y を実行してください」とだけ伝える
• 実行中にコンテキストを増やさない
• すべてのエージェントが qlty と tldr のスキルを使うこと

パイプラインのフェーズ

フェーズ 1：SPEC

Instruct spec-agent (use scout or architect):
- Analyze {source_path} using tldr-skill
- Output: spec.md with behavioral contracts, types, edge cases

エージェントプロンプトのテンプレート：

Analyze the codebase at {source_path} using tldr commands (tldr structure, tldr extract, tldr calls).
Create spec.md with:
- All behavioral contracts (what each function/class promises)
- Input/output types
- Edge cases and invariants
- Dependencies between components
Write to: {target_dir}/spec.md

フェーズ 2：失敗するテスト

Instruct test-agent (use arbiter):
- Read spec.md
- Write failing tests in {target_dir}/tests/
- Tests should define expected behavior before implementation

Instruct review-agent (use critic):
- Validate tests cover spec completely
- No gaps in behavioral coverage

フェーズ 3：敵対的レビュー（3 回反復）

Instruct premortem-agent (use premortem skill):
- Review spec + tests
- Identify failure modes, race conditions, edge cases
- DO NOT ASK - just add mitigations directly to spec
- Run 3 passes with fresh perspective each time

ポイント： 各回では、以前に見つかった問題を繰り返すのではなく、新しい問題を見つけてください。

フェーズ 4：段階的な計画

Instruct planner-agent (use architect or plan-agent):
- Input: spec.md + tests + mitigations
- Output: phased-plan.yaml
- Requirements:
  - Dependency-ordered phases
  - Each phase = one testable unit
  - Clear inputs/outputs per phase

フェーズ 5：ビルドループ（フェーズごと）

For each phase in phased-plan.yaml:

  Instruct builder-agent (use kraken or spark):
  - Write code to pass tests for this phase
  - Use qlty for quality checks
  - Run tests after each change

  Instruct review-agent (use critic or judge):
  - Validate implementation matches spec
  - Check for regressions in previous phases
  - Verify no breaking changes

フェーズ 6：統合検証

Instruct integration-agent (use atlas or validator):
- Use tldr to diff against {reference_repo}
- Check for:
  - No race conditions
  - No hangs or deadlocks
  - No breaking changes vs original
  - All behavioral contracts preserved
- Output: validation-report.md

呼び出し方法

このワークフローを呼び出す際は、次の内容を指定してください。

SOURCE: {path to source code}
TARGET_DIR: {new folder for migrated code}
TARGET_LANG: {typescript|python|go|rust|etc}
REFERENCE_REPO: {url or path for final diff comparison}
SKILLS: [tldr-code, qlty-check, {domain-specific}]

エージェントの割り当て

フェーズ	エージェントの種類	サブエージェント
仕様	調査	scout または architect
テスト	検証	arbiter
レビュー	レビュー	critic または judge
事前検討	レビュー	premortem スキル
計画	計画	architect または plan-agent
ビルド	実装	kraken（大規模）または spark（小規模）
統合	検証	atlas または validator

オーケストレーションの例

# Phase 1
Task(scout): "Analyze /src/old-system using tldr structure and tldr extract.
              Create spec.md at /migration/spec.md with all behavioral contracts."

# Phase 2
Task(arbiter): "Read /migration/spec.md. Write failing tests to /migration/tests/
               that define expected behavior."

Task(critic): "Review /migration/spec.md vs /migration/tests/.
              Report any behavioral gaps."

# Phase 3 (x3)
Task(premortem): "Review /migration/spec.md and /migration/tests/.
                 Identify failure modes. Add mitigations directly to spec. Pass 1/3."
[repeat with "Pass 2/3", "Pass 3/3"]

# Phase 4
Task(architect): "From /migration/spec.md and /migration/tests/,
                 create /migration/phased-plan.yaml with dependency-ordered phases."

# Phase 5 (loop)
Task(kraken): "Implement phase 1 from /migration/phased-plan.yaml.
              Code goes in /migration/src/. Run tests after."

Task(critic): "Review /migration/src/ against /migration/spec.md.
              Check for spec compliance and regressions."
[repeat for each phase]

# Phase 6
Task(atlas): "Run full integration tests on /migration/src/.
             Use tldr to diff against /src/old-system.
             Output /migration/validation-report.md."

アンチパターン（禁止）

• ファイルをコンテキストに読み込む（「コードを確認してみます……」）
• コードを直接書く（「この関数を実装します……」）
• 自分で何かを検証する（「テストを見ると、……」）
• ソースディレクトリを変更する
• 敵対的レビューのフェーズを省略する
• テストの前にビルドを実行する

成功基準

• すべてのテストが合格する
• qlty のレポートに問題がない
• tldr の差分に破壊的変更がない
• 競合状態やハングがない
• validation-report.md で振る舞いの同等性が確認されている