improve-architecture

アーキテクチャを改善する

コードベースに蓄積した摩擦を調査し、深掘りの候補をビジュアルレポートとして提示します。ユーザーが選んだ候補を通常の仕様サイクルへ進めます。目的はテスト容易性とナビゲーション性です。モジュールを十分に深くし、そのインターフェース自体をテスト対象にします。

用語は全体を通して厳密に使用します。module、interface、implementation、seam、adapter（および品質としての depth/locality/leverage）です。seam とは、動作を観測でき、かつ置き換え可能な公開サーフェスです（tdd と write-design が指す同じ seam です）。「component」「service」「layer」「boundary」へ逸脱しないでください。名詞を正確にすることで、調査を重ねても所見を比較できます。

1. 摩擦を調査する

まず CONTEXT.md（適切な seam に関するドメイン用語）と docs/adr/（再検討しない決定）を読みます。次に、explore サブエージェントを起動して、決まったチェックリストに沿うのではなく、自然な形でコードベースを調べてもらいます。作業がつらい箇所を記録してください。

• 浅いモジュール — インターフェースが、その背後にある実装とほぼ同じくらい複雑
• 局所性の低さ — ある概念に関する変更が、多数のファイルに波及する
• seam の欠如または弱さ — 置き換えが必要でも不可能な箇所、または仮想的な adapter が1つしかない seam
• インターフェースを通じたテストの欠如 — 内部に踏み込まなければテストできないコード

疑わしい箇所には削除テストを適用します。このモジュールが消えたら、呼び出し側は動作を再構築するためにどれほど多くのことを知る必要があるでしょうか。「ほぼすべて」であれば、そのモジュールは浅いということです。削除しても複雑さが失われず、集中するだけだからです。その複雑さが集中する箇所が候補です。

完了条件： 具体的なモジュールと名前付きの摩擦の種類に結び付いた候補が3～7件あること。

2. レポートを提示する

必須のサブスキル：マークアップを書く前に design-page を使用します。実用本位のデザインにします。明確な文字サイズの段階と選定した配色を用い、ヒーロー要素は設けません。レポートは熟読ではなく走り読みされます。確信度バッジと変更前／変更後のスケッチが一目で分かるようにしてください。

外部スクリプト、スタイルシート、CDN を使わず、インライン CSS/SVG のみを使った自己完結型 HTML ファイルを OS の一時ディレクトリ（$TMPDIR。設定されていない場合は /tmp、Windows では %TEMP%）に architecture-review-<timestamp>.html として作成します。リポジトリには何も保存しません。ファイルを開き（open / xdg-open / start）、絶対パスをユーザーに伝えます。

候補ごとにカードを1つ作成します。

• ファイル — 関連するモジュール（等幅フォントのリスト。レポートは一時的なものなので、ここではパスを記載して構いません）
• 問題 — 何が問題で、どの種類の摩擦なのかを述べる1文
• 提案する方向性 — 厳密な用語を使い、何を深めるのかを述べる1文
• 利点 — 6語以内の箇条書き。品質として名前を付けます（「locality: 変更が1つのモジュールに収まる」「interface が縮小し、1つの seam をテストできる」）
• 確信度バッジ — Strong / Worth exploring / Speculative のいずれかを正確に1つ
• 変更前／変更後の構造スケッチ — 横並びの図（手作りの div/SVG）を使います。浅い構造と深い構造の規模を示す図、波及範囲が縮小する図、seam の線などを描きます。スケッチ自体で論点が伝わるようにしてください。説明に段落が必要なら、描き直します。

最後に最優先の推奨セクションを設け、まずどの候補に取り組むべきか、理由を1文で述べます。その後、どの候補を進めたいかユーザーに尋ねます。

具体的な interface はまだ提案しないでください。 レポートで示すのは方向性であり、設計ではありません。interface の形は、ユーザーを交えた検討の段階で決めます。

ADR との矛盾： 既存の ADR に反する候補は、根拠の確信度バッジが Strong の場合に限り含めます。それより低い場合は掲載せず、候補から外します。含める場合は、ADR への参照と、決定を再検討するに値する理由を記載します。ADR が禁じるすべてのリファクタを列挙しないでください。

完了条件： レポートがユーザーのブラウザーで開かれており、どの候補を進めたいかユーザーに尋ねていること。

3. 選んだ候補を具体化する

ユーザーが候補を選んだら：

• 必須サブスキル：grilling を使用し、具体化したモジュールの構造を一度に1つの質問で確認します。制約、新しい境界の背後にあるもの、実際に存在するアダプター、引き続き有効なテストを確認します。
• 必須サブスキル：判断が固まるたびに、影響する内容に対して domain-modeling を使用します。CONTEXT.md にない概念にちなんで新しいモジュールを命名した場合は、その用語を追加します。会話の途中で曖昧な用語が明確になった場合は、後回しにせずその場で更新します。ユーザーが重要な理由から候補を却下した場合は、今後の調査で再提案されないよう、1～3文のADRを提示します（場当たり的な理由や自明な理由は除きます）。
• セレモニーの段階を声に出して伝えます。tdd に直接進めるほど小さな変更なら0、先に要件の確認が必要なら1以上です。

完了条件： grilling で未検討の分岐がなく、セレモニーの段階を0または1以上として声に出して伝えていること。

4. 仕様サイクルに渡す

段階0（機械的で、動作に変更がないもの）は、tdd／verify の規律に従って直接進められます。段階1以上の場合は、必須サブスキルとして brainstorm を使用します。具体化した改善案を渡し、通常のサイクルに従って要件まで進めます。アーキテクチャの作業も仕様ゲートの例外にはなりません。

完了条件： 作業の担当フローが決まっていること。段階0の規律のもとで進行中であるか、brainstorm に引き渡されていること。