ai-refactoring

name	ai-refactoring
description	コード整理・重複除去・責務分離・共通化のためのリファクタリングスキル。「重複コードある」「責務分離したい」「共通化して」「整理して」「もっと綺麗に」「リファクタ」「クリーンアップ」「DRY にして」「ファイル分割したい」「ヘルパー切り出して」といった要望に対応する。グローバルの refactor-advisor が「提案を出す」役割なのに対し、本スキルは「実装まで進める」役割。ユーザーが /ai-refactoring と入力したら必ずこのスキルを使う。

AI リファクタリングスキル

このスキルは、既存コードの整理、重複除去、責務の見直し、共通化を行う際に使用する。

適用範囲

• 重複ロジックの削減
• 責務の分離と再配置
• 命名や構造の整理
• 既存挙動を維持したままの内部改善

必須ルール

1. リファクタリングでは挙動を変えない。挙動変更が必要なら、通常の機能変更として明示する。
2. 共通化は、共通処理を作るだけでなく既存の重複実装を除去して完了とする。
3. 同じ責務の処理が複数箇所に残る状態を許容しない。
4. 抽象化は最小限にする。呼び出し箇所が減らない抽象化や、名前だけ違う薄いラッパーは増やさない。
5. 変更は小さく分け、各段階で意図を説明できる状態を保つ。

判断基準

• 同じ責務で、入出力・分岐・組み立てがほぼ同じなら共通化を検討する。
• 型名や対象名だけが違い、処理の本質が同じなら共通概念へ寄せる。
• 現在の差分を説明できない分岐、ラッパー、派生 helper は削除候補とみなす。
• 将来のためだけの拡張ポイントは作らない。

禁止・非推奨

• 共通 helper を追加しただけで旧実装を残す。
• 重複を別名にして温存する。
• 将来使うかもしれない抽象化を先回りで入れる。
• リファクタリング名目で仕様変更を混ぜる。

プランニング

リファクタリングに着手する前に、以下を整理して改善計画を立てる。

1. 現状の問題を特定する
   • 重複、責務の混在、命名の不統一など、改善すべき箇所を洗い出す。
   • 問題の影響範囲（関連ファイル、呼び出し元）を把握する。
2. 改善案を定義する
   • 問題ごとに具体的な改善案を記述する（何を、どう変えるか）。
   • 複数の選択肢がある場合は比較し、最もシンプルな案を選ぶ。
3. 改善の進め方を決める
   • 変更を安全に進められる順序を決める（依存関係の少ない箇所から着手する等）。
   • 1ステップごとにテスト・確認が可能な粒度に分割する。
4. 改善前の状態を記録する
   • テスト結果、出力例、パフォーマンス指標など、変更前のスナップショットを取得する。
   • デグレ確認時の比較基準として使用する。
5. リスクを見積もる
   • 変更が影響する範囲と、デグレの起きやすい箇所を事前に特定する。
   • テストが不足している箇所があれば、リファクタリング前にテストを追加する。

進め方

1. 責務を分ける
   • 何が本当に異なり、何が重複しているかを整理する。
2. 共通化の単位を決める
   • 関数、型、変換、組み立て、分岐のどこを集約すべきか決める。
3. 利用側まで置き換える
   • 共通処理を作ったら、既存の重複実装を呼び出し側も含めて置き換える。
4. 残骸を消す
   • 旧 helper、同型関数、不要な分岐、使われない型や import を削除する。
5. デグレ確認を実施する
   • 「デグレ確認」セクションに従い、挙動が保持されていることを確認する。

チェックリスト（構造品質）

1. 共通化後に同じ責務の実装が複数箇所に残っていないか。
2. 共通化したのに利用側で同型の分岐・変換・組み立てを繰り返していないか。
3. 名前だけ違う同型関数や薄いラッパーを残していないか。
4. 抽象化の追加より、コード総量と判断箇所が実際に減っているか。

デグレ確認

リファクタリング完了後、挙動が変わっていないことを以下の観点で確認する。

1. テストの実行
   • 既存テストがすべてパスすることを確認する。
   • テストカバレッジが下がっていないことを確認する。
2. 入出力の一致確認
   • リファクタリング対象の関数・モジュールについて、変更前後で同じ入力に対して同じ出力が得られることを確認する。
3. エッジケースの検証
   • 境界値、空入力、エラーケースなど、通常のテストで漏れやすい箇所を重点的に確認する。
4. 依存先への影響確認
   • 変更した関数・型を利用している箇所で、呼び出し方や戻り値の扱いに問題がないことを確認する。
5. lint・型チェック・ビルドの通過
   • 静的解析やビルドが通ることで、構造的な破壊がないことを担保する。
6. デグレ発見時の対応
   • デグレが確認された場合は、該当の変更ステップまで差し戻す。
   • 部分修正で対応する場合は、修正内容が新たなデグレを生まないことを再確認する。

完了条件

• 重複の削減対象と、最終的に集約した責務を説明できる。
• 旧実装の残置がない、または残す理由を現在の差分として説明できる。
• 変更範囲に応じた確認（テスト / lint / 生成物確認）が終わっている。
• デグレ確認の全項目を実施し、挙動が保持されていることを確認済みである。