improve-codebase-architecture

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

呼び出し側が、本来ひとまとまりであるべき詳細を調整しなければならず、理解や変更が難しくなっているコードを探します。そうした詳細を隠し、動作をテストしやすくするモジュールを提案します。

ユーザーがすでに候補や具体的な変更対象を選んでいる場合は、その対象を調査して、すぐに掘り下げてください。候補のメニューを再提示したり、もう一度選択を求めたりしないでください。ユーザーがまだ役立つ変更を尋ねている場合は、名前の挙がったサブシステムによって調査範囲を限定してもかまいません。

このコマンドは、プロジェクトのドメインモデルを踏まえたものであり、共通の設計用語に基づいています。

• 利用可能な場合は、深いモジュールの原則、呼び出し側との契約、境界を設ける根拠について詳しく知るため、codebase-design スキルを参照してください。そのアーキテクチャ上の区別を、既存の製品用語やリポジトリ用語と併せて活用してください。インターフェースが何を隠し、呼び出し側が何を得るのかを評価してください。アダプターの数だけでは、境界を設ける根拠にも、設けない根拠にもなりません。
• プロジェクトの用語集は適切な境界に名前を付け、ADR は決定済みの事項を記録します。摩擦が十分に大きく、決定を再検討する価値がある場合（下記のADR との不整合を参照）を除き、そうした決定を覆す変更は提案しないでください。CONTEXT.md や docs/adr/ に決めつけず、既存のドキュメントの配置に従ってください。

利用可能なスキルカタログで名前を使って関連スキルを探し、指定された場所や読み込み方法を利用してください。利用できない場合は、インストール先を推測したり外部のガイダンスを取得したりせず、ここに記載された手順を続けてください。

プロセス

1. 調査する

モジュールを深くすることで、今後の変更が容易になります。そのため、頻繁に変更されるコードベースの部分を重視してください。コードを読む前に対象領域を選びます。

• ユーザーが方向性（モジュール、サブシステム、問題点）を指定している場合はそれに従い、以下の推定を省略してください。
• それ以外の場合は、最近のコミット履歴から、たとえば git log --since='6 months ago' --name-only --format='' | sort | uniq -c | sort -rn | head を使って、変更頻度の高いファイルを特定してください。繰り返し変更されている箇所は保守コストの発生を示すため、そこから調査を始めます。根拠や依頼された範囲から必要と判断できる場合に限り、その領域を広げてください。

対象領域に手を付ける前に、プロジェクトに既存のドメイン用語集と、関連する ADR を確認してください。

対象範囲を直接調査してください。委任が可能で、独立した調査によって根拠を補強したり、役立つ作業と並行して時間を短縮したりできる場合は、範囲を限定した読み取り専用の調査を委任してください。エージェントには、質問、対象モジュールやパス、既知の要件と制約、および期待する結果を伝えてください。期待する結果には、具体的なコード箇所や呼び出しの追跡、その箇所で示される保守コスト、妥当な改善案、不確かな点を含めます。委任できない場合や、委任の効果が小さい場合は、ローカルで調査を続けてください。

コードによる裏付けがある摩擦を探してください。

• 1つの概念を理解するために、多数の小さなモジュールを行き来する必要がある箇所はありませんか？
• インターフェースが実装とほぼ同じ複雑さを持つ、浅いモジュールはありませんか？
• テストしやすくするためだけに純粋関数が切り出され、その結果、テストで実行されない呼び出し側に本当のバグが隠れていませんか？
• 密結合したモジュールが境界を越えて依存を漏らしていませんか？
• テストされていない部分や、現在のインターフェースではテストしにくい部分はどこですか？

モジュールの削除を勧める前に、それによって不要な処理の転送がなくなるのか、それとも呼び出し側がその処理を自分で担うことになるのかを確認してください。委任による調査結果は、提示する前にコードで検証してください。対象領域で具体的なコストと有用な改善を説明できるか、まだ不足している事実を特定できた時点で調査を終えてください。価値ある候補が見つからないことも、妥当な結果です。

2. 調査結果を役立つ形式で提示する

指定された形式と、実行環境で実際に利用できる描画機能に従ってください。簡潔なレビューでは、ホストが描画に対応している場合、短い文章とインライン図を使用します。持ち運び可能なレポートや、別ファイルにすることで比較しやすくなる場合は、HTML を使用します。視覚的な描画が利用できない場合は、分析を中断せず、関係性を文章で説明し、その制約を明記してください。

所有関係、依存関係、呼び出し元の作業量、または提案する変更を明確にできる場合は、図を使用してください。構造上の違いが重要な場合は変更前後の図が役立ちますが、レポートを埋めるためだけに候補や図の種類をいくつも作らないでください。ホストが対応する Mermaid の描画機能、インライン SVG、またはシンプルな HTML/CSS を適切に使用してください。

各候補について、評価に必要な根拠を提示してください。

• 根拠：関連するファイル、シンボル、呼び出し元の追跡情報
• 問題：具体的な摩擦と、その結果
• 解決策：何を変更するのかを平易な英語で説明
• メリット：影響を受ける場合はテスト容易性も含め、呼び出し元とメンテナーにとっての具体的な利点
• トレードオフ：難しくなる点と、維持すべき契約
• 構造の比較：変更後に呼び出し元とメンテナーが把握すべきことを、図または簡潔な説明で示す
• 推奨の強さと不確実性：根拠が変更をどの程度裏付けているか、また未検証の点

発見が依頼された場合は、最も有力な候補を推奨してください。対象が選定されている場合は、根拠がその変更を裏付けているかを説明し、設計上の問いに進んでください。図だけでは契約やトレードオフを伝えきれない場合は、簡潔な説明文を添えてください。

ドメイン概念にはプロジェクトの用語集を使用し、「Order service」のような既定の名称はそのまま維持してください。役割の違いが重要な場合は、そうした名称が検討中のアーキテクチャ上の役割にどう対応するかを説明してください。

ADR との矛盾：候補が既存の ADR に反する場合、ADR の見直しを検討するほど実際の摩擦が大きい場合に限り、その候補を提示してください。レポートでは、矛盾の内容と、その決定を再検討する根拠を説明してください。ADR で禁止されている、理論上のリファクタリングをすべて列挙しないでください。

HTML の成果物を作成する場合に限り、HTML-REPORT.md を読んでください。実行環境で可能な場合は、描画されたレポートを確認し、描画上の問題があれば明記してください。ファイルを生成しただけでは、図が読みやすいことの証明にはなりません。

発見のみを依頼された場合は、調査結果を提示して終了してください。追加の調査が求められていて、実質的に異なる候補が複数残っている場合は、根拠を提示したうえで、どの候補を掘り下げるか尋ねてください。対象がすでに明確な場合は、選択の確認を挟まずに進めてください。

3. 選択した変更を調査する

選択した候補について、呼び出し元、制約、依存関係、既存のテストを確認し、根拠を明らかにします。確定済みの判断を再利用し、根拠が十分であれば、具体的なインターフェースまたは移行に関する推奨事項を直接提示します。未解決の重要な選択肢がある場合は、利用可能であれば grilling スキルを使用します。利用できない場合は、その選択肢について的を絞った質問をします。人間の判断が不要な場合は、聞き取りを必須にしないでください。

意味と記録の整合性を保つため、利用可能であれば domain-modeling スキルを使用します。既存のドキュメント規約と承認された作業モードに従います。ドキュメントの更新が許可されている場合にのみ書き込みを行い、読み取り専用または議論のみの作業では、提案する文面を会話内に留めてください。

• 新しいドメイン概念にちなんで、機能を拡張したモジュールに名前を付けますか？ 合意した定義を既存の用語集に記録するか、議論モードで用語の追加を提案してください。
• 用語に関する重要な曖昧さを解消しますか？ 意味が確定したら、定義を更新するか、その案を提示してください。些細な表現の違いについて、新たに記録する必要はありません。
• 今後のレビューで必要になる理由により、ユーザーが提案を却下しましたか？ 後のレビューで背景を知らずに同じ提案を繰り返さないよう、その理由をADRに記録するか確認してください。「今はそこまでする価値がない」といった一時的な理由や、コードまたはドキュメントから明らかな理由は除外してください。
• 機能を拡張したモジュールの代替インターフェースを検討しますか？ 利用可能であれば、codebase-design スキルが示す代替インターフェースの比較ガイダンスを使用してください。利用できない場合は、同じ呼び出し元のニーズ、保護対象の契約、移行上の制約に照らして、具体的なインターフェース案を比較してください。有用であれば、利用可能な並列エージェントを使用してください。

求められた調査結果または設計上の推奨事項、その根拠、維持される契約、そして必要な検証または判断を示して締めくくります。実装、コミット、外部への公開には、それらの作業に対する許可が必要です。候補を選んだだけでは、実施の許可にはなりません。