scan-architecture

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

コードベースに蓄積した摩擦を調べ、改善候補を深掘りしてビジュアルレポートにまとめ、ユーザーが選んだ候補を通常の仕様サイクルに進めます。目標はテスト容易性とナビゲーションのしやすさです。つまり、インターフェース自体がテスト対象となるほど、モジュールに十分な深さを持たせます。

用語は一貫して厳密に使います。module、interface、implementation、seam、adapter（性質として depth/locality/leverage）です。seam とは、振る舞いを観察でき、かつ置き換え可能なパブリックサーフェスです（test-first と design-solution が指す同じ seam です）。「component」「service」「layer」「boundary」といった用語に逸れないでください。名詞を正確に使うことで、実行ごとの調査結果を比較できるようになります。

1. 姿勢を把握する

調査は、何かを読む前にここから始めます。見積もらずに、実行してください。

cd <repo root> && python3 <skill-root>/scripts/posture.py --days 180

作業ディレクトリによって測定対象のリポジトリが決まります。対象リポジトリ内で実行し、スキル自体のフォルダーからは実行しないでください。

次の4項目を出力して記録します。ルールのうち機械化済みの数と総数、および文章のみの ID、変更の局所性（コミットあたりのファイル数とモジュール数の中央値、および複数のモジュールにまたがるコミットの割合）、モジュール間の同時変更ペア、変更回数が最も多いファイルです。チェックによって守られていないルールは願望にすぎません。この数値から、リポジトリがいくつ抱えているかが分かります。

記録は .skills/scan-architecture/posture.json に保存されます（ローカルのみで、コミットしません）。すでにファイルがある場合は、前回の調査からの差分を各数値に付けて表示します。この差分だけが、前回選んだ項目によって何かが動いたことを示す証拠です。

数値を把握した状態で、CONTEXT.md（ドメインが良好な seam を定義するもの）と docs/adr/（再検討しない判断を記録したもの）を読んでください。同時変更ペアと変更回数が最も多いファイルを手掛かりに、最初に開くモジュールを特定します。履歴を見て初めて分かる設計上の欠陥は、読むだけでは決して表面化しません。

完了条件： posture.json が書き込まれており、文章のみのルール ID を声に出して挙げられること。

2. 摩擦を探る

探索サブエージェントを割り当てて、コードベースを調べさせます。まず姿勢の把握で特定したモジュールから始め、その後は固定的なチェックリストに従わず、自然に探索を進めながら、作業が難しい箇所を記録します。

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

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

完了条件： 具体的なモジュールと、明示された摩擦の種類にそれぞれ結び付いた候補を3～7件、用意できていること。

3. レポートを提示する

必須サブスキル：マークアップを書く前に craft-page を使用します。実用性を重視したデザインにします。適切な文字サイズのスケールと選定した配色を使い、ヒーローは設けません。レポートは熟読ではなく、ざっと目を通すものです。信頼度バッジと変更前／変更後のスケッチがひと目でわかる必要があります。スケッチは主要な図です。ジョブ名を before/after structure とし、craft-page の図のレシピに従います（レシピに沿って作成するインライン SVG は手作業で作成します）。

自己完結型の HTML ファイル（インライン CSS／SVG のみ。外部スクリプト、スタイルシート、CDN は使用しません）を、OS の一時ディレクトリ（$TMPDIR。なければ /tmp、Windows では %TEMP%）に architecture-review-<timestamp>.html として書き込み、リポジトリには何も残らないようにします。ファイルを開き（open／xdg-open／start）、絶対パスをユーザーに伝えます。

必須 — レポートの冒頭には、候補を示す前に姿勢ストリップを置きます。ルールの mechanised/total と、文章のみの ID、3 つの局所性の数値、リポジトリ独自のチェックが保持している未解決の例外リストを記載します。以前の姿勢がある場合は、それぞれに差分も示します。この部分は後続のスキャンで比較されるため、文章ではなく数値を記載します。

姿勢ストリップは posture.json をフィールドごとに読み取って作成します。ページ上の数値はすべてこのファイルから転記し、セッション中の記憶から補ってはいけません。ファイルに実際の数値があるのに、ストリップに 0/0、first scan、またはダッシュを記載すると、姿勢を捏造したことになり、以降のすべてのスキャンの差分を損ないます。

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

• ファイル — 関連するモジュール（等幅フォントのリスト。レポートは一時的なものなので、ここではパスを記載してかまいません）
• 問題 — 何が問題で、どの摩擦の種類にあたるのかを 1 文で記述します
• 提案する方向性 — 何を深めるのかを、厳密な語彙を用いて 1 文で記述します
• 利点 — 各項目は 6 語以内の箇条書きとし、「品質」として記述します（「局所性：変更が 1 つのモジュールに収まる」「インターフェースが縮小し、テストが 1 つの境界を対象にできる」）
• 信頼度バッジ — Strong／Worth exploring／Speculative のいずれかを 1 つだけ使用します
• 変更前／変更後の構造スケッチ — before/after structure のレシピに従った左右並列の SVG。浅い構造と深い構造の塊、ファンアウトの縮小、境界線を示します。スケッチ自体で議論を伝えます。説明に段落が必要なら、描き直します。

最後に、最有力の推奨案を示すセクションを設けます。最初に取り組む候補、その理由を 1 文で述べ、次のスキャンまでに姿勢を動かすため、次にチェックへ追加する文章のみのルールを 1 つ示します。最後に、どの候補を進めたいかユーザーに尋ねます。

具体的なインターフェースはまだ提案しないでください。レポートでは設計ではなく方向性を示します。インターフェースの形は、ユーザーと一緒に進める判断の明確化ステップで決めます。

ADR との矛盾： 既存の ADR と矛盾する候補を含めるのは、根拠の信頼度バッジが Strong の場合に限ります。それ未満の候補は掲載せず、除外します。含める場合は ADR の参照先と、判断を再検討するに値する理由を記載します。ADR が禁じているリファクタをすべて列挙してはいけません。

完了条件： 姿勢ストリップにステップ 1 のすべての数値が記載され、レポートがユーザーのブラウザーで開かれており、進めたい候補をユーザーに尋ねていること。

4. 選んだ候補の形を決める

ユーザーが選択したら：

• 必須サブスキル：clarify-decisions を使用します。深めるモジュールの形を、制約、新しい境界の内側に置くもの、実在するアダプター、存続するテストの順に、一度に 1 つずつ質問しながら確認します。
• 必須サブスキル：副作用を伴う判断が確定したら define-domain を使用します。CONTEXT.md にない概念にちなんで新しいモジュールを命名した場合は、その用語を追加します。会話の途中で曖昧な用語を明確にした場合は、後回しにせずその時点で更新します。ユーザーが候補を中核的な理由で却下した場合は、今後のスキャンで再提案されないよう、1～3 文の ADR を作成することを提案します（その場限り、または自明な理由は除きます）。
• セレモニーの段階を声に出して伝えます。test-first に直行できるほど小さな変更なら 0、先に要件が必要なら 1 以上です。

完了条件： clarify-decisions に未検討の分岐が残っておらず、セレモニーの段階が 0 または 1 以上として声に出して伝えられていること。

5. 仕様サイクルに進めます

Tier 0（機械的な変更で、動作に影響しないもの）は、test-first／prove-claim の規律に従って直接進められます。Tier 1 以上のものには、次のスキルが必須です：frame-change — 整理した改善案を渡し、通常のサイクルに沿って要件定義まで進めてもらいます。アーキテクチャ作業であっても、仕様ゲートの免除はありません。

完了条件： 作業に担当フローが割り当てられていること — Tier 0 の規律のもとで進行中であるか、frame-change に引き渡されていること。