improve-codebase-architecture

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

AI のようにコードベースを調査し、アーキテクチャ上の摩擦を明らかにし、テスト容易性を高める機会を見つけ、モジュールを深めるリファクタリングの RFC を提案します。ここでは用語を再定義せず、モジュール、インターフェース、深さ、シーム、アダプター、レバレッジ、局所性について、共通のcodebase-designの用語を使用します。

担当範囲：指定された領域を限定的に調査し、候補を比較して、そのリファクタリングの RFC を作成します。codebase-improverは、人間の承認を必要とする別個のリポジトリ全体のワークフローです。このスキルは、監査、実装、再帰的な深化を担当範囲に含めません。

ホスト間の移植性

委任権限がない場合は、探索と設計の各パスをインラインで順番に実行します。異なるワーカーを選ぶ前に、運用上のデフォルトを適用してください。インラインのパスが独立している、または並行しているとは主張しないでください。要求された結果に分離が不可欠な場合は、利用できないことを報告してください。

プロセス

1. コードベースを調査する

まず、最近変更が集中している箇所を確認します。ユーザーが指定した領域の未ステージ変更、ステージ済み変更、最近のコミットを調べてください。最近の変更は手がかりであり、アーキテクチャ上の重要性を証明するものではありません。確認できた証拠が最初の境界を越える場合にのみ範囲を広げてください。たとえば、呼び出し元、依存関係、失敗するテスト、または繰り返し発生する調査から、境界外の動作との結びつきが明らかになった場合です。調査範囲を広げるたびに、その証拠と新たに含めた範囲を記録してください。

その境界内では、特に指示がなければ自然な流れでインラインに調査します。固定的なヒューリスティックには従わないでください。自然に調査し、どこで摩擦を感じたかを記録します。

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

遭遇する摩擦こそが、シグナルです。

2. 候補を提示する

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

• クラスター：関係するモジュールや概念
• 結合している理由：共有型、呼び出しパターン、概念の共同所有
• 依存関係のカテゴリ：共通の依存関係カテゴリを使用
• テストへの影響：どの既存テストを境界テストに置き換えるか

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

視覚的なレポートは任意であり、デフォルトでは一時的なものです。候補間の関係を理解しやすくする場合に限り、会話内で図や表を使用してください。ユーザーから明示的に求められない限り、作成したりコミットしたりしないでください。このワークフローでデフォルトで永続化する成果物は、リファクタリングの RFC のみです。

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

4. 問題領域を整理する

設計パスの前に、選択された候補の問題領域について、ユーザー向けの説明を作成してください。

• 新しいインターフェースが満たす必要のある制約
• 依存先とする必要のある依存関係
• 制約を具体化するための大まかな説明用コードスケッチ。これは提案ではなく、制約を具体的に捉えるためのものです

これをユーザーに提示したら、ただちにステップ 5 に進んでください。設計パスの実行中に、ユーザーはこの説明を読めます。

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

デフォルトでは、3つ以上の設計演習をインラインで順番に実施します。 明示的な委任権限がある場合は、異なるワーカーを使って並行して実行してもかまいません。各演習では、対象モジュールを深く掘り下げたうえで、大きく異なるインターフェースを作成します。

各設計パスには、同じ技術的な概要（ファイルパス、結合の詳細、依存関係の分類、隠すべき内容）を提示します。この概要は、ステップ4のユーザー向け説明とは独立したものです。各パスには、それぞれ異なる設計上の制約を設定します。

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

各パスで、以下を出力します。

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

設計案を順番に提示した後、文章で比較します。

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

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

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

docs/ フォルダーに、Markdown ファイルとしてリファクタリング RFC を作成します。REFERENCE.md のテンプレートを使用してください。作成前にユーザーに確認を求めてはいけません。RFC を作成し、そのパスを共有してください。