deep-module-refactor について
deep-module-refactorは、コードベースの構造を調べ、結合が強い箇所やテストしにくい箇所を見つけて、モジュール深化のリファクタリング案を検討するスキルです。複数のインターフェース設計を比較し、選んだ案をGitHub issue RFCにまとめます。
主な機能
- 01コードベースの自然な探索
- 02アーキテクチャ上の摩擦の特定
- 03異なるインターフェース設計の比較
- 04テストへの影響とトレードオフの評価
- 05GitHub issue RFCの作成
活用シーン
- 01テストしにくいコード領域の発見
- 02モジュール境界のリファクタリング計画
- 03結合したコードのインターフェース案の比較
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/deep-module-refactorを入力して読み込まれたか確認します。
同梱ファイルLICENSEREFERENCE.md
詳細
コードベースのアーキテクチャを改善する
AI のようにコードベースを探索し、アーキテクチャ上の摩擦を明らかにして、テスト容易性を改善する機会を見つけ、モジュールを深くするリファクタリングを GitHub Issue の RFC として提案します。
深いモジュール（John Ousterhout 著「A Philosophy of Software Design」）とは、大規模な実装を小さなインターフェースの背後に隠すモジュールです。深いモジュールはテストしやすく、AI が理解しやすいだけでなく、内部ではなく境界でテストできます。
プロセス
1. コードベースを探索する
Agent ツールで subagent_type=Explore を使い、自然な形でコードベースをたどります。厳格なヒューリスティックには従わず、有機的に探索し、摩擦を感じる箇所を記録してください。
- ある概念を理解するために、多数の小さなファイルを行き来する必要がある箇所はどこですか？
- インターフェースが実装とほぼ同じくらい複雑な、浅いモジュールはどこですか？
- テスト容易性だけを目的に純粋関数が切り出されている一方で、実際のバグはその呼び出し方に潜んでいる箇所はどこですか？
- 密結合したモジュール同士の境界に、統合上のリスクが生じている箇所はどこですか？
- テストされていない、またはテストが難しいコードベースの領域はどこですか？
探索中に感じる摩擦こそが、手がかりです。
2. 候補を提示する
モジュールを深くする機会を番号付きリストで提示します。各候補について、次の内容を示します。
- まとまり：関係するモジュールや概念
- 結合している理由：共有型、呼び出しパターン、概念の共同所有など
- 依存関係のカテゴリ：REFERENCE.md の 4 つのカテゴリを参照してください
- テストへの影響：境界テストに置き換えられる既存のテスト
まだインターフェースを提案してはいけません。ユーザーに「どれを詳しく検討しますか？」と尋ねます。
3. ユーザーが候補を選ぶ
4. 問題領域を整理する
サブエージェントを起動する前に、選ばれた候補の問題領域について、ユーザー向けの説明を書きます。
- 新しいインターフェースが満たす必要のある制約
- そのインターフェースが依存する必要のあるもの
- 制約を具体化するための、おおまかな説明用コードスケッチ。これは提案ではなく、制約を具体的に把握するためのものです
これをユーザーに提示したら、すぐにステップ 5 に進みます。サブエージェントが並行して作業している間に、ユーザーが説明を読んで考えられるようにします。
5. 複数のインターフェースを設計する
Agent ツールを使って、3 つ以上のサブエージェントを並行して起動します。それぞれが、深くしたモジュールに対して根本的に異なるインターフェースを作成する必要があります。
各サブエージェントには、個別の技術ブリーフ（ファイルパス、結合の詳細、依存関係のカテゴリ、隠蔽する対象）を提示します。このブリーフは、ステップ 4 でユーザーに説明した内容とは独立したものです。各エージェントには異なる設計上の制約を与えます。
- Agent 1：「インターフェースを最小限にすること。エントリーポイントは最大 1～3 個を目指してください」
- Agent 2：「柔軟性を最大限にすること。多くのユースケースと拡張をサポートしてください」
- Agent 3：「最も一般的な呼び出し元に最適化すること。デフォルトケースをシンプルにしてください」
- Agent 4（該当する場合）：「境界をまたぐ依存関係には、Ports & Adapters パターンを中心に設計してください」
各サブエージェントは、以下を出力します。
- インターフェースのシグネチャ（型、メソッド、パラメーター）
- 呼び出し元での利用方法を示す例
- 内部で隠蔽する複雑さ
- 依存関係の戦略（依存関係の扱い方。REFERENCE.md を参照）
- トレードオフ
設計案を順番に提示してから、文章で比較します。
比較後に、自分の推奨案も提示します。どの設計が最も優れていると考えるか、その理由を説明してください。複数の設計の要素をうまく組み合わせられる場合は、ハイブリッド案を提案します。ユーザーが求めているのは強い見解であり、選択肢の一覧だけではありません。明確な立場を示してください。
6. ユーザーがインターフェースを選ぶ（または推奨案を採用する）
7. GitHub Issue を作成する
gh issue create を使って、GitHub Issue としてリファクタリング RFC を作成します。REFERENCE.md のテンプレートを使ってください。作成前にユーザーにレビューを求めず、そのまま作成して URL を共有します。