コードベースアーキテクチャの改善
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(該当する場合): 「境界を越える依存関係に対してポート&アダプタパターンで設計する」
各サブエージェントは以下を出力します。
- インターフェースシグネチャ(型、メソッド、パラメータ)
- 呼び出し元による使用方法を示す使用例
- 内部で隠蔽する複雑さ
- 依存関係戦略(依存関係の処理方法——REFERENCE.mdを参照)
- トレードオフ
設計を順に提示し、散文で比較します。
比較後、自身の推奨事項を示します:どの設計が最も強力か、その理由。異なる設計の要素をうまく組み合わせられる場合は、ハイブリッド案を提案します。断言してください——ユーザーは単なるメニューではなく、強い意見を求めています。
6. ユーザーがインターフェースを選択(または推奨を受け入れる)
7. GitHub Issueの作成
gh issue createを使用してリファクタリングRFCをGitHub Issueとして作成します。REFERENCE.mdのテンプレートを使用します。作成前にユーザーにレビューを依頼せず、すぐに作成してURLを共有します。