improve-codebase-architecture

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

アーキテクチャ上の摩擦を明らかにし、深化の機会、つまり浅いモジュールを深いモジュールに変えるリファクタリングを提案します。目的は、テスト可能性と AI によるナビゲーション性の向上です。

用語集

すべての提案で、これらの用語を正確に使用してください。一貫した表現が重要です。「コンポーネント」、「サービス」、「API」、「境界」などに言い換えないでください。定義の全文は LANGUAGE.md にあります。

• モジュール — インターフェースと実装を持つものすべて（関数、クラス、パッケージ、スライス）。
• インターフェース — 呼び出し側がモジュールを使うために知っておく必要があるすべてのこと。型、不変条件、エラーの種類、順序、設定などを含みます。型シグネチャだけではありません。
• 実装 — 内部のコード。
• 深さ — インターフェースがもたらすレバレッジ。小さなインターフェースの背後に多くの振る舞いがあることです。深い = レバレッジが高い。浅い = インターフェースが実装とほぼ同じ複雑さを持つ。
• シーム — インターフェースが存在する場所。実装を直接編集せずに振る舞いを変更できる箇所です（「境界」ではなく、この用語を使ってください）。
• アダプター — シームでインターフェースを満たす具体的なもの。
• レバレッジ — 深さによって呼び出し側が得られるもの。
• 局所性 — 深さによって保守担当者が得られるもの。変更、バグ、知識が一か所に集まります。

主な原則（一覧の全文は LANGUAGE.md を参照してください）：

• 削除テスト：モジュールを削除したと想像してください。複雑さが消えるなら、それは単なる中継役でした。複雑さが N 個の呼び出し側に再び現れるなら、そのモジュールには存在意義がありました。
• インターフェースがテスト対象です。
• アダプターが 1 つなら仮想的なシーム、2 つなら実在するシームです。

このスキルは、プロジェクトのドメインモデルに_基づいています_。ドメイン言語は適切なシームに名前を与え、ADR はこのスキルが再検討すべきでない決定を記録します。

プロセス

1. 調査する

まず、変更する領域のドメイン用語集と ADR を読みます。

次に、subagent_type=Explore を指定して Agent ツールを使い、コードベースを調べます。固定的なヒューリスティックに従うのではなく、自然に探索し、摩擦を感じた箇所を記録してください。

• 1 つの概念を理解するために、多数の小さなモジュールを行き来する必要があるのはどこですか？
• インターフェースが実装とほぼ同じ複雑さを持つ、浅いモジュールはどこですか？
• テスト可能性のためだけに純粋関数が切り出されている一方で、本当のバグはその呼び出し方に潜んでいるのはどこですか（局所性がない箇所）？
• 密結合したモジュールがシームを越えて漏れ出しているのはどこですか？
• コードベースのうち、テストされていない部分や、現在のインターフェース経由ではテストしにくい部分はどこですか？

浅いと思われる箇所には削除テストを適用してください。削除すると複雑さが集中しますか、それとも単に別の場所へ移るだけですか？「はい、集中する」が求める兆候です。

2. 候補を提示する

深化の機会を番号付きリストで提示します。候補ごとに、以下を示してください。

• ファイル — 関連するファイル／モジュール
• 問題 — 現在のアーキテクチャが摩擦を生んでいる理由
• 解決策 — 何を変更するかを平易な言葉で説明
• 利点 — 局所性とレバレッジの観点に加えて、テストがどう改善されるかも説明

ドメインには CONTEXT.md の語彙を、アーキテクチャには LANGUAGE.md の語彙を使ってください。 CONTEXT.md で「Order」が定義されているなら、「FooBarHandler」や「Order サービス」ではなく、「Order の受け入れモジュール」と表現してください。

ADR との矛盾：候補が既存の ADR と矛盾する場合、ADR の再検討に値するほど実際の摩擦が大きいときに限って提示してください。明確に示してください（例：「ADR-0007 と矛盾しますが、…のため再検討する価値があります」）。ADR が禁じる理論上のリファクタリングをすべて列挙しないでください。

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

3. グリリングループ

ユーザーが候補を選んだら、グリリング会話に入ります。制約、依存関係、深化されたモジュールの形、シームの背後にあるもの、生き残るテストなど、設計ツリーを一緒にたどっていきます。

決定が固まるにつれて、副作用はインラインで発生します：

• CONTEXT.md にない概念にちなんで深化されたモジュールを命名しますか？ その用語を CONTEXT.md に追加します — /grill-with-docs と同じ規律です（CONTEXT-FORMAT.md を参照）。ファイルが存在しない場合は遅延作成します。
• 会話中にあいまいな用語を明確にしますか？ その場で CONTEXT.md を更新します。
• ユーザーが重要な理由を添えて候補を却下しますか？ ADR を提案し、次のように枠組みます：「将来のアーキテクチャレビューで同じものを再提案しないように、これを ADR として記録しましょうか？」 将来の探索者が同じものを再提案しないためにその理由が実際に必要となる場合にのみ提案してください — 一時的な理由（「今はやる価値がない」）や自明な理由はスキップします。ADR-FORMAT.md を参照。
• 深化されたモジュールの代替インターフェースを探索しますか？ INTERFACE-DESIGN.md を参照。