improve-codebase-architecture

Improve Codebase Architecture

アーキテクチャ上の摩擦を表面化させ、深化機会（deepening opportunities） を提案します — 浅いモジュールを深いモジュールに変えるリファクタリングです。狙いはテスト可能性と AI ナビゲート可能性です。

用語集

すべての提案で、これらの用語を正確に使ってください。一貫した言語が肝心です。「component」「service」「API」「boundary」に流れないでください。完全な定義は LANGUAGE.md にあります。

• Module（モジュール） — インターフェースと実装を持つもの（関数、クラス、パッケージ、スライス）。
• Interface（インターフェース） — 呼び出し元がモジュールを使うために知らねばならないすべて: 型、不変条件、エラーモード、順序、設定。型シグネチャだけではありません。
• Implementation（実装） — 内部のコード。
• Depth（深さ） — インターフェースにおけるレバレッジ: 小さなインターフェースの背後に大量の振る舞い。Deep（深い） = 高レバレッジ。Shallow（浅い） = インターフェースが実装とほぼ同じ複雑さ。
• Seam（継ぎ目） — インターフェースが存在する場所。その場で編集せずに振る舞いを変えられる場所。（「boundary」ではなくこれを使う。）
• Adapter（アダプタ） — 継ぎ目でインターフェースを満たす具体的なもの。
• Leverage（レバレッジ） — 呼び出し元が深さから得るもの。
• Locality（局所性） — メンテナが深さから得るもの: 変更・バグ・知識が1か所に集中する。

主要原則（完全なリストは LANGUAGE.md 参照）:

• 削除テスト（deletion test）: モジュールを削除したと想像する。複雑さが消えるならパススルーだった。複雑さが N 個の呼び出し元にまたがって再出現するなら、価値を生んでいた。
• インターフェースがテスト面である。
• アダプタ1つ＝仮説上の継ぎ目。アダプタ2つ＝本物の継ぎ目。

このスキルはプロジェクトのドメインモデルに 情報を与えられて 動きます。ドメイン言語は良い継ぎ目に名前を与え、ADR はスキルが蒸し返すべきでない決定を記録しています。

プロセス

1. 探索

まずプロジェクトのドメイン用語集と、触れる領域の ADR を読んでください。

次に Agent ツールを subagent_type=Explore で使い、コードベースを歩いてください。硬直したヒューリスティクスに従わず、有機的に探索し、摩擦を感じる箇所を記録します:

• 1つの概念を理解するのに、多数の小さなモジュール間を行き来する必要があるのはどこか?
• モジュールが 浅い のはどこか — インターフェースが実装とほぼ同じ複雑さ?
• テスト可能性のためだけに純粋関数が抽出されたが、本当のバグはそれがどう呼ばれるかに潜んでいる（局所性 が無い）のはどこか?
• 密結合モジュールが継ぎ目を越えて漏れているのはどこか?
• コードベースのどの部分が未テストか、現在のインターフェースを通してテストしにくいか?

浅いと疑うものには 削除テスト を適用してください。削除すると複雑さが集中するか、単に移動するだけか? 「はい、集中する」が求めるシグナルです。

2. 候補を HTML レポートとして提示する

自己完結した HTML ファイルを OS の一時ディレクトリに書き、リポジトリには何も残さないようにします。一時ディレクトリは $TMPDIR から解決し、なければ /tmp（Windows では %TEMP%）にフォールバックし、<tmpdir>/architecture-review-<timestamp>.html に書いて実行ごとに新しいファイルにします。ユーザー向けに開いてください — Linux は xdg-open <path>、macOS は open <path>、Windows は start <path> — そして絶対パスを伝えます。

レポートはレイアウトとスタイリングに Tailwind（CDN 経由） を、グラフ/フロー/シーケンスが構造を確実に伝える図には Mermaid（CDN 経由） を使います。Mermaid と手作りの CSS/SVG ビジュアルを混ぜてください — 関係がグラフ状（コールグラフ、依存、シーケンス）のときは Mermaid、より編集的なもの（質量図、断面図、崩壊アニメーション）が欲しいときは手作りの div/SVG を使います。各候補に before/after の可視化 を付けます。視覚的にしてください。

各候補には、これまでと同じテンプレートを、カードとしてレンダリングします:

• Files — どのファイル/モジュールが関わるか
• Problem — 現在のアーキテクチャがなぜ摩擦を起こしているか
• Solution — 何が変わるかの平易な英語の説明
• Benefits — 局所性とレバレッジ、そしてテストがどう改善するかの観点で説明
• Before / After diagram — 並べて、自前で描き、浅さと深化を図示
• Recommendation strength — Strong、Worth exploring、Speculative のいずれか、バッジとして表示

レポートの最後は Top recommendation セクションで締めます: どの候補を最初に取り組むか、その理由。

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

ADR との衝突: 候補が既存の ADR と矛盾する場合、摩擦が ADR を見直す価値があるほど現実的なときだけ表面化させてください。カード内で明確にマークします（例: 警告コールアウト: 「ADR-0007 と矛盾 — だが再検討の価値がある理由は…」）。ADR が禁じる理論上のリファクタリングをすべて列挙しないでください。

完全な HTML スキャフォールド、図のパターン、スタイリングガイダンスは HTML-REPORT.md を参照してください。

まだインターフェースを提案しないでください。ファイルを書いた後、ユーザーに尋ねます: 「どれを掘り下げたいですか?」

3. 詰問（grilling）ループ

ユーザーが候補を選んだら、詰問の会話に入ります。設計ツリーを一緒に歩いてください — 制約、依存関係、深化したモジュールの形状、継ぎ目の背後に何があるか、どのテストが生き残るか。

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

• 深化したモジュールに CONTEXT.md に無い概念の名前を付ける? その用語を CONTEXT.md に追加します — /grill-with-docs と同じ規律です（CONTEXT-FORMAT.md 参照）。ファイルが無ければ遅延的に作成します。
• 会話中に曖昧な用語を鋭くする? その場で CONTEXT.md を更新します。
• ユーザーが説得力ある理由で候補を却下する? ADR を提案します。次のように枠付けして: 「将来のアーキテクチャレビューが再提案しないよう、これを ADR として記録しましょうか?」 提案するのは、その理由が将来の探索者が同じものの再提案を避けるために実際に必要となるときだけです — 一時的な理由（「今は割に合わない」）や自明な理由はスキップします。ADR-FORMAT.md 参照。
• 深化したモジュールの代替インターフェースを探索したい? INTERFACE-DESIGN.md 参照。