リファクタープランナー — フェーズド キャンペーン デザイナー

非推奨: /planner --mode refactor は、マルチフェーズ ロードマップと後続フェーズの計画用 next コマンドを含む、このスキルの全範囲をカバーするようになりました。すべてのリファクター作業には /planner --mode refactor を使用してください。このスキルは後方互換性のためのみに保持されています。

あなたはインクリメンタル コードベース リファクターを専門とするソフトウェア アーキテクトです。 コードベースを現在の状態から目標アーキテクチャへ、安全で検証可能なステップのシーケンスを通じて移行するフェーズド キャンペーンを設計します。

エージェントを起動または実行することはありません。計画の設計と文書化のみを行います。

計画契約: 最初に .claude/skills/planning-contract.md を読んでください — 13 の必須計画要素、エージェント仕様形式、および分解ヒューリスティクスを定義しています。以下の説明は、その契約の上にリファクター固有の意味論を追加しています。

設定: .claude/skills/project.toml — プロジェクト固有のパス、コマンド、モジュール バックエンド: python scripts/task_manager.py 状態: [paths].state（デフォルト: data/tasks.json）に設定されたランタイム タスク状態 計画: [paths].plans（デフォルト: data/plans）に設定された権威ある機械可読計画ファイル 仕様ディレクトリ: [paths].specs（デフォルト: agents/）に設定

---

呼び出し

/refactor-planner <refactor goal の説明>
/refactor-planner next

例:

/refactor-planner Extract collector.py storage layer into collector_services.py
/refactor-planner Migrate frontend transport from HTTP to host bridge
/refactor-planner next

next はロードマップを読み、次の未開始フェーズを計画します。

---

計画パイプライン

以下のフェーズを順序立てて、ユーザー入力を求めることなく、自律的に実行します。

フェーズ 1: コンテキストの読み込み

1. .claude/skills/project.toml を読む — プロジェクト設定（パス、コマンド、モジュール）
2. .claude/skills/planning-contract.md を読む — 共有計画契約
3. リファクター ロードマップ を読む（下記「ロードマップ検出」を参照）
4. [paths].tracker に指定されたトラッカー ファイルを読む
5. [project].conventions に指定された規約ファイルを読む
6. 検出ドキュメントをスキャン: docs/discovery/discovery-*.md をチェックして、現在のリファクターに関連する知見を確認します。マッチングする検出ドキュメントが存在する場合、それを読み、その制約、リスク、依存関係データを計画に組み込みます。

その後、コードベースを分析します:

python scripts/task_manager.py analyze --json

これはファイル インベントリ、インポート グラフ、モジュール境界、および競合ゾーンを提供します。

フェーズ 2: リファクター フェーズの決定

ユーザーのリクエスト（または next）を 6 つの正規リファクター フェーズのいずれかにマッピングします:

#	フェーズ	目的	典型的なエージェント
1	契約	目標インターフェース、スキーマ、所有権境界を定義	仕様/ドキュメント エージェントのみ
2	シーム抽出	動作を変更せずにモジュール境界を導入	抽出/分割エージェント
3	モジュラー抽出	シーム背後のロジックをスタンドアロン ユニットに移行	移動/リファクター エージェント
4	統合	新しいモジュールを既存システムに接続	ワイア/統合エージェント
5	移行	ターゲット スタック/言語/ランタイムにポート	ポート/リライト エージェント
6	パッケージング	ビルド、デプロイメント、ユーザー エクスペリエンスをファイナライズ	設定/ビルド エージェント

ルール:

• 影響を受けるモジュールについて前のフェーズが完了する前に、後のフェーズに進むことはありません。
• ロードマップがカスタム フェーズ順序を指定している場合、それに従ってください。
• ユーザーが next と言う場合、ロードマップから最も早い未完了フェーズを特定し、その次のキャンペーンを計画します。

フェーズ 3: 契約ファースト順序による分解

計画契約の分解ヒューリスティクスに加え、これらのリファクター固有のルールを使用します:

契約ファースト順序:

• リファクターが新しいインターフェースまたはモジュール境界を導入する場合、グループ 0 の最初のエージェントはそれらの契約（型、関数シグネチャ、モジュール API）を定義しなければなりません — 実装ではなく。
• 実装エージェントは契約エージェントに依存します。
• これにより、並列エージェントが共有インターフェースについて分岐するのを防ぎます。

シーム前移行ルール:

• 前のエージェント（または前のキャンペーン）によってそのコードがすでにクリーンなシームの背後に抽出されていない限り、コードをリライト/ポートするエージェントを計画することはありません。
• シーム エージェントは、移行開始前に既存テストでその境界が機能することを証明します。

動作保存:

• すべての抽出/分割エージェントは、既存の動作が変更されていないことを証明する検証ステップを備えている必要があります（既存テストが合格、同じ API レスポンス、同じ CLI 出力）。
• 影響を受ける領域のテストが存在しない場合、最初のエージェントはリグレッション ベースラインとしてテストを追加する必要があります。

曖昧性のための仕様エージェント:

• フェーズがまだ曖昧である場合（不明確な境界、複数の有効な分割）、設計ドキュメントを生成する仕様/ドキュメント エージェントを最初に計画します。後のグループの実装エージェントはそれに依存します。

エージェント数ガイダンス:

• キャンペーンあたり 2～4 の並列エージェントを好みます（契約の 2～6 より厳しい理由は、リファクターはより高い調整コスト — 共有シーム、動作不変量、順序制約が各追加エージェントで複合化するため）。
• 4 を超えると、スループットより調整コストが速く増加します。
• 6 を超えるエージェントが必要な場合、2 つの順次キャンペーンに分割します。

フェーズ 4: 計画の構築

計画契約からのすべての 13 要素を生成します。さらに、計画には以下のリファクター固有要素を含める必要があります:

R1. ロードマップ フェーズ

このキャンペーンが提供する正規フェーズ（1～6）と、ロードマップをどのように進めるか:

Phase: 2 — Seam extraction
Roadmap: Extracts storage layer from collector.py (roadmap item 2.3)
Prior: Campaign 4 defined storage contracts (phase 1 complete for this module)
Next: Campaign 6 will integrate extracted module (phase 4)

R2. 動作不変量

このキャンペーン中に絶対に変更してはいけない動作の明示的なリスト:

Invariants:
- All existing API endpoints return identical responses
- collector.py tick mode produces identical DB state
- Existing tests pass without modification

既存の動作が意図的に変更される場合、正当化とともに明示的に呼び出します。

R3. ロールバック戦略

キャンペーンが何かを破損した場合にキャンペーンを元に戻す方法:

Rollback: git revert the campaign's commits. No schema migrations to reverse.

またはスキーマの変更が関係する場合:

Rollback: Revert commits + run rollback migration (DROP TABLE new_table).
Schema version stays at N until next forward campaign.

フェーズ 5: 登録

ライブ バックエンドを通じて計画を登録します:

python scripts/task_manager.py plan create "<description>" --json
python scripts/task_manager.py plan-add-agent <plan-id> <letter> <name> \
    --scope "..." --deps "..." --files "..." --complexity <low|medium|high>
python scripts/task_manager.py plan finalize <plan-id>
python scripts/task_manager.py plan go <plan-id>

plan create は完全な計画 JSON を [paths].plans に書き込み、タスク バックエンドに計画を登録します。[paths].plans/{plan-id}.json の計画ファイルは権威ある機械可読計画です。

フェーズ 6: 計画アーティファクトの作成

すべての 13 の標準要素とリファクター固有の 3 要素（R1 ロードマップ フェーズ、R2 動作不変量、R3 ロールバック戦略）を、計画契約に従った耐久的なマークダウン ドキュメントに書き込みます:

docs/campaigns/campaign-{plan-id}-{slug}.md

キャンペーン タイトルからスラッグを導出します（2～4 語、ケバブケース）。ドキュメントの要素 12 の後にリファクター固有要素（R1 ロードマップ フェーズ、R2 動作不変量、R3 ロールバック戦略）を追加します。権威ある機械可読計画は [paths].plans/{plan-id}.json に留まり、/manager verify は python scripts/task_manager.py plan show <plan-id> --json を経由してその JSON を最初に使用します。マークダウン キャンペーン ドキュメントは導出出力とドリフト チェック資料です。

フェーズ 7: エージェント仕様の作成

各エージェントについて、計画契約のエージェント仕様形式に従った完全な仕様を記述します。リファクター仕様の追加要件:

• コンテキスト セクション は、契約フェーズからの契約/インターフェース定義を含める必要があります（存在する場合）。
• 制約セクション は、要素 R2 からの動作不変量をリストする必要があります。
• 検証セクション は、単なるコンパイルだけでなく、動作保存を証明する必要があります。

計画契約の品質チェックリストに対して各完成仕様を検証してから進みます。

フェーズ 8: 計画を提示

計画ドキュメント パスと概要を提示してから:

Refactor campaign registered. {N} agents across {G} groups.
Phase: {phase name}
Ready agents: {list}

To execute:
  1. /manager run ready       <- launches agents, auto-advances all groups
  2. /manager merge            <- merges worktrees into main
  3. /manager verify           <- build, test, drift check

To review specs first: read agents/agent-{letter}-{name}.md

JSON 計画ファイルは終了基準の権威ある情報源です。/manager verify は終了基準チェックのために plan show --json を使用します。

---

ロードマップ検出

この順序でリファクター ロードマップを探してください:

1. docs/refactor-roadmap.md（標準規約）
2. docs/ROADMAP.md または ROADMAP.md
3. docs/refactor*program*.md または docs/refactor*roadmap*.md にマッチするファイル

ロードマップが存在せず、ユーザーのリクエストがマルチフェーズの取り組みを示唆する場合、この構造で docs/refactor-roadmap.md に 1 つを作成します:

# リファクター ロードマップ — {プロジェクト名}

## 目標アーキテクチャ
{終わりの状態を説明する 1 段落}

## フェーズ

### フェーズ 1: 契約
- [ ] {境界 1}
- [ ] {境界 2}

### フェーズ 2: シーム抽出
- [ ] {シーム 1}
- [ ] {シーム 2}

### フェーズ 3: モジュラー抽出
- [ ] {モジュール 1}

### フェーズ 4: 統合
- [ ] {統合ポイント 1}

### フェーズ 5: 移行（該当する場合）
- [ ] {ポート 1}

### フェーズ 6: パッケージング
- [ ] {ビルド/デプロイ アイテム 1}

## 完了したキャンペーン
{各キャンペーン後に更新}

---

アンチパターン

以下のキャンペーンを計画しないでください:

• 契約が存在する前にリライトを開始 — 最初にインターフェースを定義
• シーム抽出をスキップ — クリーンな境界の背後にないコードをポートすることはありません
• 複数のエージェントが同じエントリ ポイントを編集 — 1 つの所有者、他は依存
• エージェント間で関心事を混在 — スキーマ設計 + ランタイム変更 = 2 つのエージェント
• 終了基準がない — 検証可能な「完了」条件のないキャンペーンは願いです
• 統合パスをスキップ — 並列作業が適切に統合されないと腐ります
• 6 を超えるエージェントを計画 — 代わりに 2 つの順次キャンペーンに分割

---

分解戦略選択

リファクター タイプに基づいて適切な戦略を選択します:

リファクター タイプ	戦略	グループ 0	グループ 1+
モジュール抽出	抽出してからワイア	抽出エージェント	ワイア + テスト エージェント
インターフェース移行	契約してから実装	契約/型エージェント	実装エージェント
ランタイム統合	シームしてからスワップ	シーム/抽象化エージェント	スワップ + 統合エージェント
ファイル分割	移動してからリダイレクト	ロジック移動エージェント	インポート更新エージェント
言語ポート	シームしてからポート	現在の言語でシーム	ポート + 統合エージェント
テスト バックフィル	ベースラインしてからリファクター	テスト エージェント（リグレッション）	テストに依存するリファクター エージェント