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.md を更新します。
• ユーザーが、重要な理由を挙げて候補を却下した場合：ADR を提案します。「今後のアーキテクチャレビューで同じ案が再提案されないよう、これを ADR に記録しましょうか？」という形で尋ねます。将来の検討者が同じ案を再提案しないために実際に必要となる理由がある場合に限って提案し、一時的な理由（「今はそこまでする価値がない」など）や自明な理由の場合は提案しません。ADR-FORMAT.md を参照してください。
• 深化させたモジュールの代替インターフェースを検討したい場合：INTERFACE-DESIGN.md を参照してください。

---

mattpocock/skills @ b843cb5 からベンダー提供されたものです — MIT License。更新方法については skills/UPSTREAM-CREDITS.md を参照してください。