| name | safe-refactor |
| description | 既存コードを振る舞いを変えずに小さく安全に改善したいとき。 機能追加よりも、保守性改善・責務分離・重複削減・命名改善に向く。
|
safe-refactor
既存コードを安全な小さな段階で整え、レビューしやすい差分で改善するための手順です。最小のコードで最大の効果を狙い、長い目で見て Happy にならない複雑化を避けます。
こんなときに使う
- 振る舞いを変えずに可読性や保守性を改善したいとき
- 長すぎる関数や重複ロジックを小さく整理したいとき
- 命名や責務の曖昧さを段階的に解消したいとき
- 大きな改修の前に安全な下準備を進めたいとき
- レビューしやすい小さな差分に分割したいとき
関連スキル
deep-review-preflight - 事前レビューで壊していないかを確認したいとき
modularity-review - 責務境界やモジュール分割を先に見直したいとき
ワークフロー: 安全に小さく改善する
Step 1: 対象の責務と守る振る舞いを固定する
変更対象が何を担当していて、どの振る舞いを絶対に変えないかを一文で定義します。
Why: 最初に境界を固定しないと、改善のつもりで仕様変更を混ぜやすくなるためです。
Step 2: 変更理由を 1 つに絞る
今回の変更意図を次のどれかに絞ります。
- 重複削減
- 命名改善
- 関数分割
- 条件分岐整理
- 依存の明確化
- I/O と純粋ロジックの分離
1 回の変更で複数の意図を混ぜないようにします。
Step 3: 先に確認手段を用意する
既存テストがあるなら先に実行し、ない場合でも最低限の比較手段を決めます。
- 既存テスト
- 手動確認シナリオ
- before / after の出力比較
- DryRun やログによる確認
Why: 確認手段なしのリファクタは、改善か退行かを判断できないためです。
Step 4: 小さな変更単位に分ける
1 回のコミットや差分では、1 つの関心事だけを扱います。外科的対応を既定にし、今回の改善意図に直接効かない整理は次回へ回します。
- 長すぎる関数を 1 つ分割する
- 意味の薄い名前を 1 系統だけ直す
- 重複ロジックを 1 箇所へ集約する
公開 API や外部契約に触れる場合は、その影響を明示します。
Step 5: 変更前後で同じ点と改善点を説明する
リファクタ後は、少なくとも次の 2 点を言語化します。
- 変更前後で同じ振る舞い
- 今回改善された保守性や可読性
Why: 差分の価値と安全性を同時に説明できると、レビューが速くなりやすいためです。
注意点
- 無関係な整形や命名変更を大量に混ぜない
- 抽象化のための抽象化をしない
- テストや確認手段なしで大きく動かさない
- 既存の style、framework、契約を無視しない
- token 消費やレビュー負荷だけを増やす横展開をしない
クイックリファレンス
- 責務と守る振る舞いを固定する
- 変更理由を 1 つに絞る
- 先に確認手段を用意する
- 小さな変更単位に分ける
- 変更前後で同じ点と改善点を説明する
出力形式
- 現状の問題
- 今回のリファクタ方針
- 小さな変更ステップ
- 互換性影響
- 必要なテスト
- 残課題