improve-codebase-architecture

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

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

使用するタイミング

• ユーザーが英語でこのスキルを依頼または言及した場合（例：「use /improve-codebase-architecture」、「run improve-codebase-architecture」）。
• ユーザーがポルトガル語でこのスキルを依頼または言及した場合（例：「use /improve-codebase-architecture」、「execute improve-codebase-architecture」）。

用語集

提案では、以下の用語を必ずそのまま使用してください。一貫した言葉遣いが重要です。「コンポーネント」、「サービス」、「API」、「境界」などに言い換えないでください。詳しい定義は LANGUAGE.md を参照してください。

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

主な原則（全項目は LANGUAGE.md を参照してください）：

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

このスキルは、プロジェクトのドメインモデルを_参考に_しています。.claude/CONTEXT.md のドメイン用語と、.claude/MEMORY.md にあるセッションをまたぐコンテキストは、適切な継ぎ目に名前を付けるためのものです。docs/architecture/ に記録された承認済みのアーキテクチャ上の決定は、このスキルで再検討すべきでない制約を示します。

プロセス

1. 調査する

まず、プロジェクトのドメイン用語集（.claude/CONTEXT.md）、セッションをまたぐメモリ（.claude/MEMORY.md）、および対象領域に関係する承認済みのアーキテクチャ上の決定を docs/architecture/（プロジェクトで引き続き使用している場合は docs/adr/）で確認してください。

次に、読み取り専用の調査サブエージェントを起動して、コードベースを調べてもらいます。固定的なヒューリスティックに従うのではなく、自然に調査し、摩擦を感じる箇所を記録してください。

• ある概念を理解するために、多数の小さなモジュールを行き来する必要があるのはどこですか？
• 浅いモジュール、つまりインターフェースが実装とほぼ同じくらい複雑なモジュールはどこですか？
• テスト容易性のためだけに純粋関数を切り出したものの、実際のバグは呼び出し方に潜んでいる箇所（局所性がない箇所）はどこですか？
• 密結合したモジュールが継ぎ目を越えて漏れ出しているのはどこですか？
• テストされていない部分や、現在のインターフェースを通じてテストしにくい部分はどこですか？

浅いと疑う対象には、削除テストを適用してください。それを削除すると複雑さが一か所に集約されますか、それとも単に別の場所へ移るだけですか？「集約される」という答えが、求めているシグナルです。

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

OS の一時ディレクトリに自己完結型の HTML ファイルを書き込み、リポジトリに何も残らないようにします。$TMPDIR から一時ディレクトリを解決し、設定されていない場合は /tmp（Windows では %TEMP%）を使います。<tmpdir>/architecture-review-<timestamp>.html に書き込み、実行のたびに新しいファイルを作成します。ユーザーが確認できるように開きます。Linux では xdg-open <path>、macOS では open <path>、Windows では start <path> を使い、絶対パスを伝えてください。

レポートのレイアウトとスタイルには CDN 経由の Tailwind を使い、グラフ、フロー、シーケンスによって構造を確実に伝えられる場合は、図に CDN 経由の Mermaid を使います。Mermaid と手作りの CSS／SVG ビジュアルを組み合わせます。関係がグラフ状（呼び出しグラフ、依存関係、シーケンス）なら Mermaid を使い、より編集的な表現（マス図、断面図、折りたたみアニメーション）なら手作りの div／SVG を使います。各候補に 変更前／変更後のビジュアルを付けます。視覚的な表現を重視してください。

各候補は、これまでと同じテンプレートをカードとして表示します。

• ファイル — 関係するファイル／モジュール
• 問題 — 現在のアーキテクチャがなぜ摩擦を生んでいるのか
• 解決策 — 何が変わるのかを平易な言葉で説明します
• メリット — 局所性とレバレッジの観点から説明し、テストがどう改善するかも示します
• 変更前／変更後の図 — 浅さと深まりを示す、左右に並んだカスタム図
• 推奨度 — Strong、Worth exploring、Speculative のいずれかをバッジとして表示します

レポートの最後に「最有力の推奨」セクションを設け、最初に取り組む候補とその理由を示します。

ドメイン用語には .claude/CONTEXT.md の語彙を、アーキテクチャ用語には LANGUAGE.md の語彙を使ってください。.claude/CONTEXT.md で「Order」と定義されている場合は、「Order 受付モジュール」と表現し、「FooBarHandler」や「Order サービス」とは呼びません。

判断の衝突：候補が承認済みの SPEC SDD またはアーキテクチャ上の決定に反する場合は、その判断を見直すほど実際の摩擦が大きい場合に限り、候補として提示します。カード内では、明確に示してください（例：警告の吹き出しで 「SPEC-20260908-order-intake に反しますが、…のため見直す価値があります」 と記載）。記録された決定が禁じている、理論上のリファクタリングをすべて列挙しないでください。

HTML の全体的なひな形、図のパターン、スタイルのガイダンスについては HTML-REPORT.md を参照してください。

インターフェースはまだ提案しないでください。ファイルを書き込んだ後、ポルトガル語でユーザーに次のように尋ねてください。

Relatorio salvo em [CAMINHO_ABSOLUTO].

Qual dessas oportunidades voce quer explorar primeiro?

➡️ Meu palpite: comecamos pelo [NOME_CANDIDATO_TOP1].

3. 詳細を詰める対話

ユーザーが候補を選んだら、詳細を詰める対話に移ります。制約、依存関係、深めるモジュールの形、境界の内側に置くもの、維持されるテストを一緒に検討し、設計の選択肢を順に確認します。

決定が固まるたびに、その場で次の変更を行います。

• .claude/CONTEXT.md にない概念名を、深めるモジュールの名前にする場合は、その用語を .claude/CONTEXT.md に追加します。/write-specs と同じ規律に従います。ファイルがなければ必要になった時点で作成します。
• 対話中に曖昧な用語を明確化した場合は、その場で .claude/CONTEXT.md を更新します。
• ユーザーが根拠を伴って候補を却下した場合は、plan サブエージェント（または /write-specs）が SPEC SDD テンプレートから作成する .specs/SPEC-{YYYYMMDD}-{slug}.md の SPEC SDD を提案します。ポルトガル語で次のように尋ねます。「将来の検討で同じ提案が繰り返されないよう、これを .specs/ の SPEC として記録しておきますか？」 将来の検討者が同じ提案を避けるために知っておく必要がある理由の場合に限り提案します。「今はやる価値がない」のような一時的な理由や、自明な理由の場合は提案しません。
• 深めるモジュールの別のインターフェースを検討する場合は、INTERFACE-DESIGN.md を参照してください。