| name | backend-refactor-planner |
| description | コードを触る前にリファクタの影響範囲・順序・ロールバック戦略を計画する。依存関係を洗い出し、安全に進められる小さなステップに分解する。「リファクタ計画立てて」「影響範囲調べて」「安全に直す手順を作って」などで起動。 |
Refactor Planner
リファクタに着手する前に、何を・どの順で・どう検証して 進めるかを明確化する。実装自体はこのスキルの範囲外。
いつ使うか
- 広範囲に影響するリネーム・分割・抽象化をする前
- 長年触られていないコードに手を入れる前
- 「ついでに直したい」が多発しそうなとき
- レビュアーに分かりやすい PR 戦略を立てたいとき
実行手順
1. ゴール確認
ユーザーに以下を確認（必要なら 1-2 個だけ聞く）:
- What: 何をどう変えたいか（「X を Y に置き換える」「A を B と C に分割する」）
- Why: なぜ今やるのか（バグ修正の土台、性能、可読性、削除予定の依存）
- Done criteria: どうなったら完了か（テストグリーン？ API 互換維持？）
- Constraint: 禁止事項（挙動変更禁止、API 変更禁止、1 日以内で終わらせたい等）
2. 影響範囲の洗い出し
対象シンボル/ファイルに対して、以下を調査:
- 参照元: Grep / LSP で利用箇所を列挙
- 型・インターフェース境界: 変えると波及する箇所
- テスト: 対象を覆っているテスト、触ると赤くなりそうなテスト
- 外部契約: 公開 API / DB スキーマ / ファイルフォーマット / イベントスキーマに波及しないか
参照元が 20 箇所以上 ある場合は、一括変更ではなく段階的移行を強く推奨する。
3. 段階分解
以下のパターンから該当するものを選ぶ。
A. Parallel Change（並行導入）
- 新実装を 別名 で追加（旧実装と共存）
- 利用箇所を新実装に切り替え（複数 PR に分割可）
- 旧実装を削除
適する場合: 広範囲に影響、段階的に切り替えたい、ロールバック容易性が欲しい
B. Strangler Fig
- ラッパー/アダプタで新旧両方を受け入れる
- 内部だけ新実装に置換
- 呼び出し側を徐々に新 API に移行
- ラッパーと旧実装を削除
適する場合: 公開 API を維持しつつ内部刷新
C. In-place（一括書き換え）
- テストで挙動を固定
- 一度に書き換え
- テスト緑で確定
適する場合: 参照元が 10 箇所未満、影響が局所、テストが厚い
4. 順序付け
各ステップについて以下を明記:
- 前提: 何が終わっていれば始められるか
- 変更: 何を何に変えるか
- 検証: 何で動作確認するか（test / type check / 手動確認）
- ロールバック: 失敗したら何を revert すれば戻せるか
- PR サイズ: 独立した PR にできるか、まとめるべきか
5. リスク列挙
- 見落としがちな呼び出し元（reflection, 文字列参照, 設定ファイル, 外部システム）
- テストでカバーされていない挙動
- 本番でしか再現しない条件（負荷、時刻依存、環境変数）
- デプロイ順序への依存（DB migration とアプリの順番など）
6. 計画提示
以下のテンプレで出力:
## リファクタ計画: <タイトル>
### ゴール
<what / why / done>
### 制約
<変更禁止事項>
### 影響範囲
- 参照箇所: N 件
- テスト: <ファイル一覧>
- 外部契約: <ありなし>
### 戦略
<Parallel Change / Strangler Fig / In-place>（理由: ...）
### ステップ
1. <ステップ名>
- 変更: ...
- 検証: ...
- ロールバック: <revert 対象>
- PR: 独立 / まとめる
2. ...
### リスク
- <見落としがち項目>
- <テスト未カバー領域>
### 着手判断
この計画で進めて良いですか？ それとも手順を調整？
7. 承認を待つ
計画提示で終わる。ユーザーの承認なく実装に入らない。
原則
- 挙動を変えるコミットを小さく。1 コミットでテストが壊れたら、その変更が原因と即特定できる
- テストを先に手厚く。リファクタはテストを武器に進める。テストが薄いなら先に追加する
- 計画の途中で新しい発見があれば計画を更新する。発見を握りつぶして計画通り進めない
- ロールバック不能な変更（スキーマ削除、データ破壊）は独立した PR に
