code-refactoring

コードのリファクタリング

意図した動作を変えずに構造を改善する作業には、このスキルを使用します。

このスキルの中心は、小さく、繰り返し実行できる内容に保ちます。

1. 実際に手元にある整理対象のパケットを特定します。
2. 1つのリファクタリングモードを選びます。
3. 動作を守るための条件を明確にします。
4. レビュー可能な単位に分けて作業を進めます。
5. 残りの作業を正直に検証し、適切な担当先へ引き継ぎます。

不慣れな整理作業に取り組む前に、次のサポートドキュメントを読んでください。

• references/intake-packets-and-route-outs.md
• references/refactor-modes.md
• references/handoff-boundaries.md
• references/safe-refactor-checklist.md

このスキルを使用する場面

• 関数、コンポーネント、サービス、スクリプト、モジュールが複雑に絡み合っており、動作を変えずに構造を整理する必要がある場合。
• 現在の動作が不安定、または十分に理解されていないため、まず現状を固定してからレガシー領域を整理する必要がある場合。
• 同じ API、命名、または構造の変更が多くのファイルで繰り返されており、codemod／移行概要が必要な場合。
• 差分に整理作業と意味上の変更が多く混在しており、レビュー可能な小さな単位に分割する必要がある場合。
• ユーザーが、リファクタリング、分解、重複の解消、安全な名前変更、整理作業の段階化、または動作を維持する移行計画を依頼した場合。

このスキルを使用しない場面

• 主な作業が、動作が誤っている理由の証明、障害の再現、またはリグレッションの切り分けである場合 → debugging
• 主な作業が、具体的な差分／PRを安全にマージできるか判断することである場合 → code-review
• 主な作業が、組織全体の検証範囲、ベンチマーク方針、またはリリース基準の決定である場合 → testing-strategies
• 主な作業が、トレース、フレームグラフ、CWVレポート、またはプロファイラーの出力からボトルネックを特定することである場合 → performance-optimization
• 主な作業が、整理方法を選ぶ前にシンボル、呼び出し箇所、または影響範囲を特定することである場合 → codebase-search

手順

ステップ 1：整理対象のパケットから始める

references/intake-packets-and-route-outs.md を使用します。

ユーザーがすでに用意しているパケットを選びます。

• 複雑なファイル／コンポーネント／サービスが1つ
• 現在の動作への確信が乏しい、不安定なレガシー領域
• 多くのファイルにまたがる、繰り返しの移行パターン
• レビュー前に再構成が必要な、整理作業が中心の差分
• 「まず該当箇所をすべて見つけたい」という漠然とした要望のみ

インテークの概要を簡潔に出力します。

## Cleanup Packet
- Current artifact:
- Why it is enough (or not enough):
- Missing evidence to collect next:

ルール：直近のニーズが検索、診断、レビュー、またはパフォーマンスの根拠の確認だけである場合、無理に大規模なリファクタリング計画を立てないでください。

ステップ 2：主要なリファクタリングモードを1つ選ぶ

references/refactor-modes.md から、主要なモードを1つだけ選びます。

主要モード：

• local-safe-refactor
• behavior-freeze-first
• repetitive-migration-codemod
• diff-shaping-cleanup

簡易選択表：

シグナル	モード
1つのファイルまたは範囲の狭いモジュールで、意図が明確かつ、少なくとも1つの迅速なガードレールがある	local-safe-refactor
不安定なレガシー領域で、隠れた不変条件があり、テストへの信頼性が低い	behavior-freeze-first
同じ API または構造が多くのファイルで繰り返されている	repetitive-migration-codemod
整理作業がリスクの高いレビュー差分に混在しており、より小さな単位への分割が必要	diff-shaping-cleanup

ルール：主要モードは1つにし、必要であれば補足を1つ加えます。すべての整理手法を1つの回答に混在させないでください。

ステップ 3：動作のガードレールを固定する

大規模な編集に入る前に、意図が変わっていないことをどのように証明するかを決めます。

ガードレールの情報源には、次のようなものがあります。

• 既存の単体テスト／結合テスト／エンドツーエンドテスト
• 型チェックとリンター
• 特性テストや記録済みの例
• フィクスチャのスナップショットやゴールデン出力
• UI 作業のスクリーンショット／プレビューのキャプチャ
• 変更前と変更後のサンプル入出力テーブル
• 自動化が十分でない場合の手動スモークテスト手順

最低限のルール：

• 局所的な整理 → 少なくとも 1 つの高速な検証手段を用意する
• 壊れやすいレガシーコードの整理 → まず動作を固定する
• 繰り返しの移行 → まず小規模で代表的なサンプルを使って試行する
• 差分の再構成 → 機械的な整理と意味上の変更を分離する

ユーザーが主に検証プログラム全体の設計支援を必要としている場合は、testing-strategies に案内してください。

ステップ 4：信頼できる最小限の整理計画を立てる

計画はレビューしやすい状態に保ちます。

推奨する作業単位：

1. 名前変更／移動／抽出
2. 重複コードや不要コードの整理
3. 機械的な移行や codemod の展開
4. 必要な場合に限り、意味上の変更を追加で実施
5. 検証と引き継ぎ

各作業単位について、次の項目を記録します。

• 目標
• 維持する動作
• 検証に使う証拠／ガードレール
• リスクがある箇所
• 次のステップを別のスキルが担当するかどうか

ルール：

• 大規模な一度きりの書き換えよりも、目立った問題のない差分を段階的に重ねることを優先します。
• 可能であれば、構造上の整理と意味上の動作変更を分離します。
• 移行では、規模を拡大する前に、変換元のパターン、変換先のパターン、既知の例外、ロールバック方法を定義します。

ステップ 5：適切なモードのパケットを使う

references/intake-packets-and-route-outs.md にある該当するパケットを使います。

• 局所的な整理パケット
• 壊れやすいレガシーコード／動作の固定を優先するパケット
• 繰り返しの移行／codemod パケット
• 差分再構成パケット

各モードでの有効な進め方：

• local-safe-refactor → 不明瞭な概念の名前を変更し、純粋なロジックを抽出し、副作用を境界に移し、よく似た重複をまとめる
• behavior-freeze-first → 例を記録し、特性テストを追加し、接合点を 1 つ見つけ、その接合点の背後でリファクタリングする
• repetitive-migration-codemod → 変換元／変換先のパターンを定義し、まずサンプルで試行し、誤検出を確認し、試行の信頼性が確認できてから対象を拡大する
• diff-shaping-cleanup → 整理と意味上の変更を分け、生成された編集や機械的な編集を切り分け、残る注意箇所についてレビュー用のメモを残す

ステップ 6：検証し、残りの作業を案内する

「すっきりしたように見える」だけで終わらせないでください。

検証の概要：

## Refactor Brief
- Primary mode:
- Behavior to preserve:
- Guardrail used:
- Smallest planned slices:
- Risks still open:
- Recommended next move:

必ず明記する項目：

• どの動作を維持する意図だったか
• その検証にどのような証拠を使ったか
• どの点にリスクが残るか、または対象範囲外なのか
• 作業内容が変わった場合に、次のステップを担当すべき隣接スキル

出力形式

## Cleanup Packet
- Current artifact:
- Primary mode:
- Why this mode fits:

## Behavior Guardrail
- Intended behavior to preserve:
- Evidence available:
- Missing evidence:

## Planned slices
1. ...
2. ...
3. ...

## Verification
- Fast checks:
- Higher-risk checks:

## Route-outs
- Use `debugging` for:
- Use `code-review` for:
- Use `testing-strategies` for:
- Use `performance-optimization` for:
- Use `codebase-search` for:

例

例 1：肥大化したサービスハンドラー

入力：「この 180 行のチェックアウトハンドラーを、動作を変えずに読みやすくリファクタリングしてください。」

望ましい応答の形：

• local-safe-refactor を選ぶ
• クーポン／税金／在庫切れの動作を明示的に維持する
• 検証、価格計算、永続化のヘルパーを抽出する
• テスト／型チェックをガードレールとして維持する
• 構造上の整理と、その後の意味上の変更を分ける

例 2：壊れやすいレガシーモジュール

入力：「このレポートサービスは保守が不可能な状態ですが、テストもほとんど信用できません。安全にリファクタリングできるよう支援してください。」

望ましい応答の形：

• behavior-freeze-first を選ぶ
• 大規模な整理に入る前に、特性を捉えたケースを記録する
• すべてを再設計するのではなく、一度に 1 つずつ接合点を特定する
• 期待される動作がまだ不明確な場合は、根本的な失敗調査を debugging に案内する

例 3：繰り返しの API 移行

入力：「フレームワークをアップグレードする前に、220 個の TypeScript ファイルで非推奨のクライアント API を置き換える必要があります。」

望ましい応答の形：

• repetitive-migration-codemod を選ぶ
• 変換元と変換先のパターンを定義する
• まず一部のファイルで変換を試行する
• 機械的な書き換えと意味上の変更を分ける
• テスト、型チェック、リポジトリ内検索で検証する

例 4：検索を優先した振り分け

入力：「リファクタリングを始める前に、この古いヘルパーの呼び出し箇所とラッパーをすべて見つけて、影響範囲を把握できるようにしてください。」

望ましい応答の形：

• 主なタスクを codebase-search に振り分けます
• リファクタリング計画全体を主な回答として提示しないでください
• 影響範囲のマップができた後に行う整理作業として、code-refactoring を位置づけます

ベストプラクティス

1. 理想化した整理のワークフローではなく、ユーザーが実際に持っている情報から始めます。
2. アクションを提案する前に、主なモードを 1 つ選びます。
3. 動作の維持を明示し、暗黙の前提にしないでください。
4. 1 つの巨大な整理差分より、小さくレビューしやすい単位を優先します。
5. 繰り返しの多さがセットアップコストに見合う場合に限り、コードモッドや構造的な書き換えを使用します。
6. 診断、レビュー判断、テスト方針の設計、パフォーマンス調整、シンボルの一覧化は、取り込まずに隣接するスキルへ振り分けます。
7. 検証済みの事項と、引き続きリスクがある事項の証拠を残します。

参考資料

• インテークパケットと振り分け
• リファクタリングのモード
• 引き継ぎの境界
• 安全なリファクタリングのチェックリスト
• Martin Fowler — リファクタリング
• VS Code のリファクタリングに関するドキュメント
• IntelliJ IDEA のリファクタリングに関するドキュメント
• OpenRewrite のドキュメント
• jscodeshift
• ast-grep