improve-codebase-architecture

コードベースのアーキテクチャを改善する

AI のようにコードベースを探索し、アーキテクチャ上の摩擦を明らかにし、テスト容易性を高める機会を見つけ、モジュールを深くするリファクタリング案を GitHub issue の RFC として提案します。

深いモジュール（John Ousterhout 著「A Philosophy of Software Design」）とは、大規模な実装を小さなインターフェースの内側に隠すモジュールです。深いモジュールはテストしやすく、AI がコードベース内を探索しやすいほか、内部ではなく境界でテストできます。

プロセス

1. コードベースを探索する

Agent ツールを subagent_type=Explore で使い、自然にコードベース内を探索します。厳格なヒューリスティックには従わず、自由に探索して、どこで摩擦を感じるかを記録してください。

• ある概念を理解するために、小さなファイルをいくつも行き来する必要があるのはどこですか？
• インターフェースが実装とほぼ同じくらい複雑になっている、浅いモジュールはどこですか？
• テスト容易性のためだけに純粋関数が切り出されているものの、本当のバグは呼び出し方に潜んでいるのはどこですか？
• 密結合したモジュールが、その継ぎ目で統合リスクを生んでいるのはどこですか？
• テストされていない、またはテストが難しいコードベースの部分はどこですか？

遭遇した摩擦こそが、手がかりです。

2. 候補を提示する

モジュールを深くする機会を番号付きリストで提示します。各候補について、以下を示してください。

• クラスター：関係するモジュールや概念
• 結合している理由：共有する型、呼び出しパターン、概念の共同所有
• 依存関係のカテゴリ：4 つのカテゴリについては REFERENCE.md を参照してください
• テストへの影響：どの既存テストが境界テストに置き換わるか

まだインターフェース案を提案しないでください。ユーザーに「どれを詳しく検討しますか？」と尋ねてください。

3. ユーザーが候補を選ぶ

4. 問題の範囲を整理する

サブエージェントを起動する前に、選ばれた候補について、問題の範囲をユーザー向けに説明してください。

• 新しいインターフェースが満たす必要のある制約
• 依存する必要のあるもの
• 制約を具体的に示すための、概略的なコード例。これは提案ではなく、制約を明確にするためのものです

これをユーザーに示したら、すぐにステップ 5 に進んでください。サブエージェントが並行して作業している間に、ユーザーが説明を読み、検討できます。

5. 複数のインターフェースを設計する

Agent ツールを使って、3 つ以上のサブエージェントを並行して起動します。それぞれが、深くしたモジュールについて大きく異なるインターフェースを作成する必要があります。

各サブエージェントには、個別の技術概要（ファイルパス、結合の詳細、依存関係のカテゴリ、隠す対象）を提示してください。この概要は、ステップ 4 のユーザー向け説明とは独立したものにします。各エージェントには、異なる設計上の制約を与えてください。

• エージェント 1：「インターフェースを最小限にする――エントリーポイントは最大 1～3 個を目指す」
• エージェント 2：「柔軟性を最大限にする――多くのユースケースと拡張に対応する」
• エージェント 3：「最も一般的な呼び出し元向けに最適化する――デフォルトのケースを簡単にする」
• エージェント 4（該当する場合）：「境界をまたぐ依存関係には、ポートとアダプターのパターンを採用する」

各サブエージェントは、以下を出力します。

1. インターフェースのシグネチャ（型、メソッド、パラメーター）
2. 呼び出し元がインターフェースを使用する例
3. 内部に隠す複雑さ
4. 依存関係の方針（依存関係の扱い方。REFERENCE.md を参照）
5. トレードオフ

設計案を順番に提示した後、文章で比較してください。

比較したら、どの設計が最も優れていると考えるか、その理由とともに自分の推奨案を示してください。異なる設計の要素をうまく組み合わせられる場合は、ハイブリッド案を提案してください。ユーザーが求めているのは強い見解であり、単なる選択肢の一覧ではありません。明確な見解を示してください。

6. ユーザーがインターフェースを選ぶ（または推奨案を受け入れる）

7. issue ファイルを作成する

REFERENCE.md のテンプレートを使い、リファクタリング RFC を issues/ 内のローカル Markdown ファイルとして作成します。作成前にユーザーへレビューを求めないでください。そのまま作成し、パスを伝えてください。