| name | improve-codebase-architecture |
| description | コードベースを探索し、アーキテクチャ改善の機会を見つける。浅いモジュールを深くすることで、テスタビリティの向上に焦点を当てる。ユーザーがアーキテクチャの改善、リファクタリングの機会の発見、密結合なモジュールの統合、またはAIがナビゲートしやすいコードベースにしたい場合に使用する。 |
| ref | https://github.com/mattpocock/skills/blob/main/improve-codebase-architecture/SKILL.md |
コードベースアーキテクチャの改善
AIのようにコードベースを探索し、アーキテクチャ上の摩擦を浮き彫りにし、テスタビリティ向上の機会を発見し、モジュール深化のリファクタリングをGitHub issueのRFCとして提案する。
深いモジュール（John Ousterhout著「A Philosophy of Software Design」）は、大きな実装を隠す小さなインターフェースを持つ。深いモジュールはよりテストしやすく、AIがナビゲートしやすく、内部ではなく境界でテストできるようになる。
プロセス
1. コードベースを探索する
Agent toolのsubagent_type=Exploreを使って、コードベースを自然にナビゲートする。厳格なヒューリスティクスに従わず、有機的に探索し、摩擦を感じた箇所を記録する：
- 1つの概念を理解するために多くの小さなファイルを行き来しなければならないのはどこか？
- インターフェースが実装とほぼ同じ複雑さを持つほど浅いモジュールはどこか？
- テスタビリティのためだけに純粋関数が抽出されているが、本当のバグはそれらの呼び出し方に潜んでいるのはどこか？
- 密結合なモジュールがモジュール間の接合部に統合リスクを生み出しているのはどこか？
- テストされていない、またはテストが難しい部分はどこか？
あなたが感じる摩擦こそがシグナルである。
2. 候補を提示する
深化の機会を番号付きリストで提示する。各候補について以下を示す：
- クラスター: 関連するモジュール/概念
- 結合の理由: 共有する型、呼び出しパターン、概念の共同所有
- 依存関係のカテゴリ: 4つのカテゴリについてはREFERENCE.mdを参照
- テストへの影響: 境界テストに置き換えられる既存のテスト
まだインターフェースを提案しないこと。ユーザーに「どの候補を掘り下げたいですか？」と尋ねる。
3. ユーザーが候補を選ぶ
4. 問題空間をフレーミングする
サブエージェントを生成する前に、選ばれた候補の問題空間をユーザー向けに説明する：
- 新しいインターフェースが満たすべき制約
- 依存する必要がある依存関係
- 制約を具体化するための大まかなコードスケッチ — これは提案ではなく、制約を具体的にするためのもの
これをユーザーに示し、すぐにステップ5に進む。サブエージェントが並行して作業する間、ユーザーは問題について読んで考える。
5. 複数のインターフェースを設計する
Agent toolを使って3つ以上のサブエージェントを並行して生成する。各サブエージェントは深化されたモジュールに対して根本的に異なるインターフェースを作成する必要がある。
各サブエージェントに個別の技術概要（ファイルパス、結合の詳細、依存関係のカテゴリ、隠されるもの）を渡す。この概要はステップ4のユーザー向け説明とは独立している。各エージェントに異なる設計制約を与える：
- Agent 1: 「インターフェースを最小化する — エントリーポイントを最大1〜3個に抑える」
- Agent 2: 「柔軟性を最大化する — 多くのユースケースと拡張をサポートする」
- Agent 3: 「最も一般的な呼び出し元に最適化する — デフォルトのケースを自明にする」
- Agent 4（該当する場合）: 「境界を跨ぐ依存関係にはPorts & Adaptersパターンで設計する」
各サブエージェントの出力：
- インターフェースシグネチャ（型、メソッド、パラメータ）
- 呼び出し元がどのように使うかを示す使用例
- 内部に隠される複雑さ
- 依存関係の戦略（依存関係の扱い方 — REFERENCE.mdを参照）
- トレードオフ
設計を順番に提示し、その後散文で比較する。
比較した後、自分自身の推奨を示す：どの設計が最も優れていると考えるか、その理由を述べる。異なる設計の要素がうまく組み合わさる場合は、ハイブリッドを提案する。意見を持つこと — ユーザーが求めているのは単なるメニューではなく、強い見解である。
6. ユーザーがインターフェースを選ぶ（または推奨を受け入れる）
7. GitHub issueを作成する
gh issue createを使ってリファクタリングRFCをGitHub issueとして作成する。テンプレートはREFERENCE.mdを使用する。作成前にユーザーにレビューを求めないこと — そのまま作成してURLを共有する。
