refactoring

リファクタリング：コードの臭いとテクニック

コードの臭いを検出し、リファクタリングテクニックを適用して、設計、明瞭さ、保守性を向上させるための包括的なガイドです。

---

必要なときに読む

読むタイミング	ファイル
コードの臭いを特定するとき、または差分／PR をレビューして肥大化を確認するとき	コードの臭いカタログ
使用するリファクタリングテクニックを決めるとき	リファクタリングテクニック
適切なパターン、シナリオに基づく判断、またはレビューワークフローを選ぶとき	判断ガイド
ユーザーが特定の言語でパターンを適用できる場所を尋ねた場合に限り	言語ごとの慣用表現
テストが少ないレガシーコードをリファクタリングするとき（ホットスポット、マイクロコミット、サブクラス化とオーバーライド、承認テスト）	レガシーコードの応急処置

---

常に守るガードレール

• TODO コメントを自動で削除しないでください。 TODO の対応には人間による判断が必要です。削除せず、見つけやすくしてください。
• 適切なタイミングで整理してください。 既知の動作変更の直前か直後に整理します。直前なら作業内容が明確で、直後なら設計上の摩擦が新鮮なうちに対処できます。固定の技術的負債の割り当ては避けてください。不適切なタイミングや場所で、憶測に基づく整理を招くためです。リーダーシップが作業時間を確保する場合は、割り当てではなく許可と余裕として捉え、適時の整理を妨げているインセンティブを改善してください。独立した整理作業の時間を区切るのは、意図的な練習、意識的な近道からの立て直し、または不慣れで健全でないコードベースの把握を目的とする場合に限ります。
• 抽出する前に「3回の法則」を適用してください。 Extract Method／Extract Class を行うのは、重複が 3回目 に現れてからにしてください。2か所だけでは、適切な抽象化を確実に判断できません。
• テストなしのリファクタリングは禁止です。 何も確認せずにリファクタリングしないでください。まず安全網を追加してください。
• 抽出に新たなテストは必要ありません。 リファクタリング中に抽出したヘルパーは、既存の公開 API の動作テストで引き続きカバーされます。ヘルパーに対するユニットテストを書くと、テストスイートが構造に再び結び付いてしまいます（テストにおけるモックの脆さに関するガイダンスを参照）。
• コメントの整理と併せて確認してください。 冗長なコメントを削除するときは、追加する価値のある 理由 を説明するコメントが不足していないかも確認してください。

---

コードの悪臭 → テクニック（クイックリファレンス）

コードの悪臭	検出の兆候	テクニック
長いメソッド	10 行超、複数の責務がある	メソッドの抽出 (三度目の法則)
巨大なクラス	10 個超のメソッド、複数の関心事がある、テストが困難	クラスの抽出 (三度目の法則)
プリミティブ型への執着	ドメイン概念に文字列／整数の定数を使用している	型／オブジェクトの作成
長いパラメーターリスト	3～4 個超のパラメーター、関連するパラメーターがある	パラメーターオブジェクトの導入
データの塊	同じ変数が複数箇所にある	クラスの抽出
コメント	コードの理解にコメントが必要（サブタイプについては smells.md を参照）	メソッド／変数の抽出、名前の変更、アサーションの導入、テストの作成
意味が伝わらない名前	名前にコメントが必要、1 文字の名前、汎用的な仮置きの名前、単位の欠落	名前の変更／変数の導入

テクニック → 使用する場面の一覧については、techniques.md を参照してください。

---

目標別のテクニック

• テスト容易性： メソッドの抽出 → クラスの抽出 → 条件分岐の置き換え
• 重複の削減： メソッドの抽出 → 条件分岐の置き換え → 変数の導入
• 可読性： 名前の変更 → 変数の導入 → 条件分岐の簡素化 → メソッドの抽出
• 設計／結合度の改善： クラスの抽出 → メソッド／フィールドの移動 → 条件分岐の置き換え

---

リファクタリングをしない場合

コードのサイズ、複雑さ、構造が妥当な場合もあります。

• 多くの行数を本当に必要とする複雑なアルゴリズム（理由を明確なコメントで説明する）
• 設定オブジェクトやテストデータなどの宣言的な構造（長いパラメーターリストを許容する）
• まもなく置き換えられる一時的なコード（リファクタリングのコストがメリットを上回る）
• 一度しか使わないユーティリティ（抽出すると、削減できる量よりボイラープレートが増える）
• まだ変更中の不安定なコード — 要件が安定するまで待つ
• パフォーマンスが重要な処理経路（リファクタリングで速度が低下する場合。まずプロファイリングする）
• テストのないコード — セーフティネットがある場合にのみリファクタリングする（常時適用のガードレールを参照）
• 類似コードが 2 箇所にしかない場合 — 三度目の法則（常時適用のガードレールを参照）。早すぎる DRY は、誤った抽象化につながりやすい

常に問いかけてください。「この複雑さはコードの目的に役立っているのか、それとも目的を分かりにくくしているのか？」

---

外部リファレンス

• Refactoring Guru： Code Smells - Bloaters
• Martin Fowler： Refactoring Catalog — 操作別に整理された 72 以上のテクニック
• 原則： SRP、OCP、DRY
• クレジット： Tim Ottinger（コメント）；Fowler Refactoring；Martin Clean Code

---

ベンチマーク

シナリオ：.benchmarks/scenarios/refactoring-001-long-method.md · 実行日：2026-06-14

モデル	なし	あり	差分
claude-opus-4-8	83%	100%	+17%
claude-sonnet-4-6	33%	100%	+67%
claude-haiku-4-5	0%	100%	+100%

合格（最も強いシグナル）。性能の低いモデルに対して決定的な効果（haiku 0→100%）があり、コードの悪臭の命名、メソッド抽出の優先、適用範囲の維持、三度目の法則を徹底します。現状を維持してください。.agents/skills/skill-optimizer/rules/release-gates.md に従ってゲートを適用してください。