refactoring-guide

リファクタリングガイド

LLM がリファクタリングで一貫して誤る原則について説明します。このスキルは、結合分析、型レベルの設計、モジュール境界、安全な移行戦略に関する体系的な盲点を解消します。

根本的な問題は、LLM がコードの「見た目」（構造上の類似性）を最適化するのに対し、優れたモジュール化ではコードが「一緒にどう変化するか」（時間的凝集性）を最適化することです。ここで扱うすべての原則は、この隔たりに対処します。

自己進化するスキル：このスキルは使用を通じて改善されます。指示が誤っている、パラメーターにずれが生じている、または回避策が必要だった場合は、先延ばしにせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合にのみ更新してください。

使用するタイミング

• リファクタリングタスク：モジュールの抽出、ファイルの分割、結合の低減、再構成
• コードレビュー：問題の兆候を見つけ、表面的な対処ではなく適切な修正を提案する
• アーキテクチャの決定：モジュール境界、依存関係の方向、統合ポイント
• 先回りして対応する場合：以下の検出ヒューリスティクスの表にある兆候を検出したとき

ワークフロー

リファクタリングでは、次の手順に従います。

1. 検出 — 検出ヒューリスティクスの表に照らしてコードを確認します。該当する問題の兆候を特定します。
2. 診断 — 問題の兆候ごとに、対応するリファレンスファイルを読み、適切な原則を理解します。
3. 計画 — 適切な手法を使ってリファクタリングを設計します。複数ファイルにまたがる変更（3 ファイル超）では、Mikado メソッドを使用します（references/architecture.md を参照）。
4. 実行 — 変更を適用します。共有インターフェースには、拡張・縮小方式を使用します（references/tactical-moves.md を参照）。
5. 検証 — 手順 1 で特定した結合の種類が、リファクタリングによって低減したことを確認します。

検出ヒューリスティクス

適用する原則を特定するため、次の兆候がないか確認します。

シグナル	よくあるコードの問題	原則	参考
同じパラメーター群が3つ以上の関数に渡されている	データの塊	検証するのではなく解析する — パラメーターオブジェクトを抽出する	type-design.md §1
メソッドが自身のクラスよりも別のクラスのフィールドを多く使っている	機能への執着	データのある場所にメソッドを移動する	module-boundaries.md
2つを超える分岐を持つif isinstance／型の切り替え	ポリモーフィズムの欠如	条件分岐をポリモーフィズムに置き換える	type-design.md §2
モジュール間の循環インポート	非循環性の違反	共有要素を抽出するか、依存関係を逆転させる	module-boundaries.md §2
公開APIのブール値パラメーター	フラグ引数	メソッドを分けるか、列挙型を使う	tactical-moves.md §5
3か月以上前の# TODO: remove after migration	デッドコード	今すぐ削除する	tactical-moves.md §1
関数がreturnと副作用（データベース／ファイル／ネットワーク）の両方を使う	関心事の混在	関数型コア、命令型シェル	architecture.md §1
テストに3つを超える依存関係のモックが必要	過剰な結合	境界が不足している — 特定して作成する	structural-coupling.md §1
1つの機能を変更すると3つを超えるディレクトリに手を入れる	不適切な分割	レイヤーではなく機能ごとにパッケージ化する	module-boundaries.md §1
常に同じPRで変更される2つのモジュール	モジュール分割の不足	共通閉包 — 2つを統合する	module-boundaries.md §3
1つのモジュールが無関係な理由で変更される	変更の分散	変更理由ごとに分割する	structural-coupling.md §4
1つの論理的変更で5つ以上のファイルに手を入れる	ショットガン手術	散在する関心事を統合する	structural-coupling.md §4
process()の前にinit()を呼び出す必要がある	時間的結合	型状態パターン	type-design.md §4
ビジネスロジックの深部で外部APIの型を使っている	統合の漏出	境界に腐敗防止層を設ける	architecture.md §2
同じ構造体が3つ以上の異なるモジュールで変更される	データ所有権が不明確	データ型ごとに所有するモジュールを指定する	structural-coupling.md §5
コアロジックでベンダーSDKの型を使っている	変動性の漏出	狭く安定したインターフェースの背後にラップする	structural-coupling.md §6
モジュールが操作ではなくセッターを公開している	不変条件が保護されていない	意図が伝わる操作を公開する	module-boundaries.md §5
インフラストラクチャの例外がビジネスロジックに表出する	エラーの漏出	モジュール境界でエラーを変換する	module-boundaries.md §6
ロジックのない中継レイヤー（呼び出しを転送するだけ）	偽のモジュール化	不要な間接層を取り除く	tactical-moves.md §9
モジュール名がutils、common、helpers、shared	何でも置き場	実際の利用者のまとまりごとに分割する	module-boundaries.md §4
コントローラー、ハンドラー、ジョブの中にドメインロジックがある	ビジネスロジックの配置ミス	ドメインモジュールに抽出する	architecture.md §1
各所に散在するサービスが、それぞれ独自の依存関係を構築している	コンポジションルートの欠如	アプリケーションのエントリーポイントで配線を一元化する	architecture.md §5
調整とすべての判断を行う巨大なサービス	オーケストレーションの混在	オーケストレーションと計算を分離する	architecture.md §1

原則の概要

各原則の詳細は references/ に記載されています。該当する問題に遭遇したら、関連するファイルを読んでください。

構造的結合（references/structural-coupling.md）

1. シームの特定 — 抽出する前に自然なシームを見つけ、その境界を横切って切り分けないでください
2. コネサンスのスペクトラム — 結合には9段階の強さがあり、より弱い形式へリファクタリングしてください
3. 安定性の指標 — 安定性の高い方向（不安定性の低い方向）に依存してください
4. 変更の発散とショットガン手術 — 反対の修正が必要となる、相反する問題です。混同しないでください
5. データの所有権 — すべてのデータ構造には、それを所有するモジュールが1つあります。他のモジュールは契約を通じて読み取り、決して変更しないでください
6. 変動性の分離 — 変更頻度の高い依存関係を、狭く安定したインターフェースの背後に隠してください

型レベルの設計（references/type-design.md）

1. 検証するのではなくパースする — 境界で型付きの結果にパースし、生の入力を下流に渡さないでください
2. 不正な状態を表現不能にする — ブール値やオプションフィールドより、判別共用体を使用してください
3. ニュータイプ／ブランド型 — プリミティブ型を別個の型でラップし、意味上の混同を防いでください
4. 時間的結合 → 型状態 — 現時点で有効なメソッドのみを公開する新しい型を返してください

アーキテクチャ（references/architecture.md）

1. 関数型コア、命令型シェル — 判断には純粋関数を使い、副作用は薄いIOシェルに閉じ込めてください
2. 腐敗防止層 — 統合境界で外部モデルを変換してください
3. ストラングラーフィグ — 段階的に移行し、一括書き換えは避けてください
4. ミカドメソッド — 大規模なリファクタリングでは、試行し、失敗を記録し、元に戻し、下位から取り組んでください
5. コンポジションルート — すべての配線を1つのエントリーポイントに集約し、モジュール内に散在させないでください

モジュール境界（references/module-boundaries.md）

1. レイヤーではなく機能ごとにパッケージ化する — 垂直方向のスライス化により、機能の変更を局所化できます
2. 非巡回依存関係 — モジュールグラフはDAGでなければなりません
3. 共通閉包 — 技術的な類似性ではなく、変更理由ごとにグループ化してください
4. インターフェース分離 — 使用しないエクスポートへの依存を利用側に強制しないでください
5. 不変条件の保証 — モジュールは自身の不変条件を守り、セッターではなく操作を公開してください
6. エラー境界での変換 — 各モジュールはエラーを独自のドメイン語彙に変換してください

戦術的な手法（references/tactical-moves.md）

1. 削除もリファクタリング — 最良のリファクタリングは、行数を減らすことがよくあります
2. 3回のルール — 抽象化する前に、3つの事例が現れるのを待ってください
3. インライン化してから再抽出する — 混乱したコードをまず平坦化し、その後、明確に再分解してください
4. 拡張・縮小 — 共有インターフェースでは、新旧を並行して追加し、移行してから古い方を削除してください
5. ブール値パラメーターの禁止 — 分割するか、代わりに列挙型を使用してください
6. 設定を明示的な依存関係にする — 設定を渡し、グローバルにインポートしないでください
7. 特性テストを先に書く — リファクタリング前に動作を固定してください
8. コンウェイの法則に合わせる — モジュール境界はチーム境界と一致させてください
9. 過度なモジュール化の確認 — 境界はファイルを整理するだけでなく、変更の分離性を高める必要があります
10. モジュール文書のテンプレート — 各モジュールについて、責務、所有権、依存関係、不変条件、エラーモデルを記載してください

Rust固有（references/rust-specific.md）

Rustのコードベースをリファクタリングする際に読んでください。アーキテクチャとしての可視性、公開APIの範囲制御、クレートとモジュールの境界、Cargoの機能、ワークスペースにおける機能の統合、依存関係ポリシーのツールについて説明しています。

Swift/macOS固有（references/swift-macos-specific.md）

macOS上のSwiftコードベースをリファクタリングする際に読んでください。アーキテクチャとしてのアクセス制御（package修飾子）、明示的なインポート可視性（SE-0409）、ターゲット／フレームワーク境界の選択、マクロの分離、APIガバナンスのツールについて説明しています。

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功していない場合は、失敗の原因となった手順またはエラーテーブルを修正します。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して一致させます。
3. 回避策が必要でしたか？ — 別のフラグや追加手順など、その場で工夫する必要があった場合は、次回の実行で同じ回避策が不要になるよう、この SKILL.md を更新します。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測で更新しないでください。