Refactoring

リファクタリング・技術的負債管理

目的

• コードの可読性・変更容易性を高め、バグの発生率と修正コストを下げる
• 技術的負債を「見えないコスト」から「管理できるバックログ」に変える
• 機能開発のスピードを中長期で維持する

使うタイミング

• ボーイスカウトルール: 今触っているファイルを、来た時より少し綺麗にして去る
• 道ならし: 機能追加の前に「まず変更しやすくしてから変更する」
• 3回ルール: 同じ場所で3回つまずいたら投資対効果が十分と判断する
• 負債返済スプリント: 開発の2割ルールで定期的に計画に組み込む
• 新機能追加・バグ修正と同じPR/コミットに混ぜない

進め方

1. テスト確認: 対象コードにテストがあるか確認する([[testing]])。なければ先に特性テスト(characterization test: 現状の振る舞いをそのまま固定するテスト)を書く
2. スコープ確定: 今回触る範囲を小さく区切る。「クラス全体」ではなく「このメソッド群」まで絞る
3. 現状計測: 変更前の複雑度・重複率・テストカバレッジを記録する
4. 小さいステップで実施: 1変更ごとにテスト実行→グリーン確認→コミット。いつでも中断・巻き戻しできる状態を保つ
5. 効果計測: 変更後の複雑度・重複率・変更所要時間を計測し比較する
6. 負債登録簿を更新: 返済したものをクローズし、発見した新たな負債を登録する

主要リファクタリングカタログ

手法	適用場面
名前変更(変数・関数・クラス)	意図が伝わらない命名
関数抽出	1関数が複数の責務を持つ、20行超の関数
重複の除去	同じロジックが3箇所以上(ただし早すぎる共通化に注意)
早期return	ネストした条件分岐の平坦化
ポリモーフィズム導入	型チェックのswitch/if-elseが複数箇所に散在
クラス分割	1クラスが複数の責務を持つ(フィールド数・メソッド数が多い)

技術的負債の管理

負債の種類と対応方針

• 意図的な負債: 期限前に意識して借りる。必ずその場で登録簿に記録してから借りる
• 偶発的な負債: 設計の理解不足や時間的圧力で生まれる。発見時に登録
• 陳腐化による負債: ライブラリ・言語バージョンの古さ。定期棚卸しで検出

優先度の付け方

「利子」= 放置し続けると毎スプリント払い続けるコストで判断する。

• 高: バグ頻発・レビュー時間増大・新人が触れない → 早期に返済
• 中: コードの理解に時間がかかる → 道ならしとして返済
• 低: 美的な問題 → ボーイスカウトルールで少しずつ

返済の組み込み方

• 2割ルール: スプリント容量の20%を技術的負債返済に割り当てる
• 道ならし返済: 機能Aを追加する前に、関連する負債Bを先に返済してからPRを出す(別PR)
• 返済専用スプリント: 利子が大きい高優先度負債が溜まった場合に設ける

大規模リファクタリング

• ビッグバンを避ける: 数週間続くブランチは作らない
• ストラングラーフィグパターン: 新実装と旧実装を並行稼働させ、段階的に新に切り替える
• フィーチャーフラグ: 切り替えをコードで制御し、問題時は即ロールバック

成果物テンプレート

技術的負債登録簿

# 技術的負債登録簿

最終更新: YYYY-MM-DD

| ID | 負債の内容 | 発生理由 | 利子（困りごと） | 返済コスト見積もり | 優先度 | 状態 |
|----|-----------|---------|----------------|------------------|--------|------|
| TD-001 | UserServiceが認証・通知・課金を全て持つ | MVP時の速度優先 | 変更時に影響範囲が読めずレビューに2時間かかる | L(3d) | 高 | 未着手 |
| TD-002 | 注文計算ロジックが3箇所に重複 | 担当者がコードを知らずコピー | バグ修正時に3箇所直さないといけない | S(0.5d) | 中 | 対応中 |
| TD-003 | テストDBのセットアップが手動 | CI構築を後回しにした | 新メンバーのオンボーディングに1日かかる | M(1d) | 中 | 未着手 |

凡例: コスト S=半日以内 / M=1〜2日 / L=3〜5日 / XL=1週間超

チェックリスト

• リファクタリング前にテストがグリーンであることを確認した
• 特性テストを書いた(テストがなかった場合)
• スコープを小さく区切った
• 機能追加・バグ修正と同じコミットに混ぜていない
• ステップごとにテストを実行した
• 変更前後の複雑度・重複率を記録した
• 技術的負債登録簿を更新した(返済完了・新規発見)

アンチパターン

• ビッグバンリファクタリング: 数週間ブランチが返ってこない。コンフリクト地獄になる
• 機能追加との混在PR: レビュアーが振る舞いの変化を見分けられなくなる
• テストなしで着手: 振る舞いを壊したことに気づけない
• 趣味的な書き換え: 動いているコードを好みで書き換えても利子は減らない
• 「いつか直す」と言って記録すらしない: 負債が見えなくなり、利子だけ払い続ける

モデル委譲ガイド

共通原則は [[orchestration]] を参照。

役割	タスク例
司令塔(メインモデル)	リファクタリング戦略の策定・優先順位の判断・負債登録簿のレビュー・PR分割の決定
Opus相当	大規模リファクタリングの設計(ストラングラーフィグ計画・クラス責務の再設計・アーキテクチャ変更を伴う分割)
Sonnet相当	機械的なリファクタリング実施(名前変更・関数抽出・重複除去)・特性テストの作成・負債登録簿の初期作成
Haiku相当	重複コードの検出・複雑度の高い箇所のリストアップ・コードメトリクスの収集

関連スキル

• [[testing]] — 特性テスト・リファクタリング後の回帰確認
• [[code-review]] — リファクタリングPRのレビュー観点
• [[architecture-design]] — 大規模リファクタリング時の設計判断
• [[implementation]] — リファクタリングと機能実装の切り分け
• [[git-workflow]] — 小さいステップのコミット戦略・ブランチ管理
• [[performance-optimization]] — パフォーマンス改善目的のリファクタリング
• [[debugging]] — バグの温床となっている技術的負債の特定
• [[orchestration]] — モデル委譲の共通原則