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

AIのようにコードベースを探索し、アーキテクチャ上の摩擦を表面化させ、テスト可能性向上の機会を発見し、モジュール深化のリファクタRFCをGitHubイシューとして提案します。

深いモジュール（John Ousterhout著『A Philosophy of Software Design』）は、小さなインターフェースが大きな実装を隠しています。深いモジュールはより高いテスト可能性を持ち、AIナビゲーション性に優れており、内部ではなく境界でテストできます。

プロセス

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

Agent ツールを subagent_type=Explore で使用してコードベースを自然に移動します。厳密なヒューリスティクスに従わず、有機的に探索し、摩擦を感じた箇所をメモします：

• 1つの概念を理解するために多くの小さなファイル間を移動する必要がある箇所はどこか？
• モジュールが非常に浅く、インターフェースが実装とほぼ同じくらい複雑な箇所はどこか？
• 純粋関数がテスト可能性のためだけに抽出されているが、実際のバグはそれらがどのように呼び出されるかに隠れている箇所はどこか？
• 密結合モジュールがモジュール間の境界に統合リスクを生み出している箇所はどこか？
• コードベースのどの部分がテストされていない、またはテスト困難か？

体験する摩擦こそが信号です。

2. 候補を提示する

深化の機会の番号付きリストを提示します。各候補について以下を表示します：

• クラスタ：関連するモジュール/概念
• なぜ密結合しているのか：共有型、呼び出しパターン、概念の共同所有
• 依存カテゴリ：REFERENCE.md の4つのカテゴリを参照
• テスト影響：既存のどのテストが境界テストで置き換わるか

まだインターフェースを提案しないでください。ユーザーに「これらのうちどれを掘り下げたいですか？」と聞きます。

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

4. 問題空間をフレームする

サブエージェントを起動する前に、選択された候補の問題空間をユーザー向けに説明します：

• 新しいインターフェースが満たす必要のある制約
• それが依存する必要のある依存関係
• 制約を具体的にするための大まかな図示的コードスケッチ。これは提案ではなく、制約を明確にするための方法です

これをユーザーに表示してから、すぐにステップ5に進みます。ユーザーはサブエージェントが並行して作業している間に読んで考えます。

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

Agent ツールを使用して3つ以上のサブエージェントを並行して起動します。各エージェントは深化されたモジュール用に根本的に異なるインターフェースを生成する必要があります。

各サブエージェントに個別の技術ブリーフ（ファイルパス、密結合の詳細、依存カテゴリ、隠れるもの）をプロンプトします。このブリーフはステップ4のユーザー向け説明とは無関係です。各エージェントに異なる設計制約を与えます：

• エージェント1：「インターフェースを最小化する。最大で1～3つのエントリーポイント」
• エージェント2：「柔軟性を最大化する。多くのユースケースと拡張性をサポート」
• エージェント3：「最も一般的な呼び出し元に最適化する。デフォルトケースを簡単に」
• エージェント4（該当する場合）：「ポート&アダプターパターンで境界を越えた依存関係を設計」

各サブエージェントが出力するもの：

1. インターフェースシグネチャ（型、メソッド、パラメータ）
2. 呼び出し元がどのように使用するかを示す使用例
3. 内部で隠れている複雑性
4. 依存戦略（依存関係の処理方法。REFERENCE.md参照）
5. トレードオフ

設計を順番に提示してから、散文で比較します。

比較後、独自の推奨を示します：どの設計が最も強力か、そしてなぜか。異なる設計の要素がうまく組み合わさる場合は、ハイブリッドを提案します。主観的になってください。ユーザーは強力な見方を求めており、メニューだけではありません。

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

7. リファクタRFCを作成する

refactors/ ディレクトリ内にリファクタRFCを作成します。REFERENCE.md のテンプレートを使用します。ユーザーに作成前にレビューするよう求めないでください。作成して、URLを共有するだけです。