architecture-review

Architecture Review（アーキテクチャ設計の要約と網羅的改善提案）

コードベースを「まず設計として理解し」、その理解を基準に「あらゆる観点から改善点を洗い出して、 どう直すべきか・どの順で着手すべきか」を体系的に出すためのスキル。

ゴールは網羅性と実行可能性。抽象論で終わらせず、各指摘を file:line の根拠・深刻度・直し方・ 優先度まで落とす。推測で断定しない（特に「未使用」「重複」「壊れている」は機械的に裏を取る）。

いつ使うか

• 「設計/アーキテクチャをレビュー・評価して」「改善点を網羅的に出して」「技術的負債の棚卸し」
• 大きめのリファクタ前の方針出し、新規参画時のコードベース把握、設計レビュー会の準備
• 漠然と「整理して / きれいにして / どこを直すべき」と言われたとき(まず本スキルで観点を出す)

小さな単一バグ修正や、対象が1ファイルで明白な場合は不要。

進め方（4フェーズ）

Phase 0 — スコープと前提の確定

• 対象範囲（リポジトリ全体 / 特定パッケージ / 特定の関心事=性能・テスト等）を確認。曖昧なら全体。
• 規模を測る: 言語・LOC・ファイル数・パッケージ構成・ビルド/テスト/依存定義の場所を把握。
• ベンダー/生成物/node_modules/.venv 等は対象外として除外する(ノイズになる)。

Phase 1 — アーキテクチャを「設計として」要約する

改善提案の前に、必ず設計を構造化して理解する。最低限これらを押さえる:

• 目的とドメイン: 何を作るシステムか、主要ユースケース。
• 主要コンポーネント/パッケージと各責務（1行で言えるか＝凝集の指標）。
• 依存方向: 誰が誰を import するか。レイヤ（基盤→ドメイン→アプリ→UI）の向きは守られているか。 循環依存はないか。import グラフを実際に作って確認する（推測しない）。
• データ/制御フロー: 主要シナリオの処理順（入力→…→出力）。
• エントリポイントと実行トポロジ: CLI / サーバ / ジョブ / 常駐プロセス / サブプロセスの境界。
• 外部依存・I/O 境界: DB / 外部API / モデル / ファイル / ネットワーク。
• 横断的関心事: 設定、ロギング、エラー処理、並行性、認証の扱われ方。
• 明示/暗黙の設計判断: なぜこの構造か（docstring / README / コミット履歴から）。

大きいコードベースでは Phase 1 を並列探索でファンアウトする（サブシステム毎に1エージェント、 各自が構造化要約を返す）。references/methodology.md に並列調査と import グラフ作成の具体手順あり。

Phase 2 — 観点別に網羅監査する（本スキルの核心）

Phase 1 の理解を基準に、全観点をひと通り当てて改善点を洗い出す。各観点の問い・典型的な アンチパターン・直し方は references/viewpoints.md、各指摘に紐付ける名前付き原則(DRY/KISS/YAGNI/ SoC/SOLID 等)は references/principles.md を読むこと。観点(どこを見るか)×原則(なぜ問題か)の2軸で 網羅する。観点の柱:

1. モジュール境界と凝集 — 責務が名前で言えるか / god-module / 関心の混在
2. 結合と依存 — 依存方向・レイヤ違反・循環・漏れた抽象・過度な相互依存
3. 命名と発見可能性 — ファイル/フォルダ/シンボルが用途を表すか・一貫性・同名衝突
4. 重複と共通化(DRY) — 同型ロジックの分散・共通化の取りこぼし
5. 死にコード/陳腐化 — 未参照ファイル・関数・旧版・化石コメント
6. 抽象とAPI設計 — 公開面・インターフェース・設定の置き場・拡張点
7. エラー処理と回復性 — 失敗モード・伝播・フォールバック・握り潰し
8. テストと検証可能性 — カバレッジ・テスト容易性(seam)・特性化テストの有無
9. 性能と資源 — ホットパス・I/O・モデル/初期化コスト・並行度・メモリ/VRAM
10. 並行性と状態 — 共有可変状態・競合・プロセス/スレッド境界・冪等性
11. セキュリティと秘匿 — 入力検証・秘密情報の扱い・認可・パストラバーサル等
12. 可観測性 — ログ・トレース・進捗・障害の切り分けやすさ
13. ビルド/パッケージング/依存/設定 — 依存定義・env・成果物・再現性
14. ドキュメントとオンボーディング — README/設計図が実態と一致しているか

各指摘は次の形に必ず落とす（網羅性の担保＋実行可能性）:

• 観点 / 原則 / タイトル / 場所(file:line) / 問題 / 影響 / 直し方 / 深刻度(critical|high|medium|low) / 労力(S|M|L)
• 原則: その指摘が違反している名前付き原則を1〜3個必ず付ける（例: DRY, SSOT / SRP, SoC / YAGNI / DIP / Least Astonishment / Fail Fast）。カタログとIDは references/principles.md。 原則名で語ることで「なぜ直すべきか」が普遍的根拠を持ち、レビューが一貫・教育的になる。 観点=「どこを見るか」、原則=「なぜ問題か」の直交2軸で網羅する。

「未使用・重複・壊れ」は機械的に検証してから書く（import グラフ、grep、ビルド/型/リンタ）。 裏が取れないものは「(推測)」と明示。

直し方は「AI が実行できる修正仕様」にする（最重要）

散文の助言ではなく、別の AI エージェント（or 自分）がそのまま着手できる粒度で書く。各指摘の 直し方 は:

• 正確な場所: ファイルパス + 行範囲 かつ 一意に特定できるアンカー文字列（行は動くのでアンカー併記）。
• before → after: 変更後の姿を最小スニペットで示す（曖昧な説明より差分が伝わる）。
• 波及(refs): その変更で更新が要る他箇所（import / エントリ定義 / 設定 / ドキュメント / 動的参照）を列挙。
• 順序(deps): 先に済ませるべき指摘ID（特にリネームは全域波及）。
• 検証: 変更後に走らせるコマンドと成功条件（例: 「import 解決 OK / リンタ通過 / 旧名 grep 0件」）。
• レシピ参照: 変更タイプに対応する references/fix-recipes.md の R番号（R1 リネーム, R2 共通化, R3 死にコード, R4 god-module分割, R5 依存是正, R6 エラー処理, R7 設定集約, R8 テスト導入）を挙げ、固有値だけ埋める。

高 deps の修正（リネーム/移動など全域波及）は中央で一括・段階検証、挙動を変える整理はテスト先行を明記する。

Phase 3 — 統合・優先順位付け・ロードマップ

• 重複指摘を統合し、深刻度×労力で並べる（高価値・低労力＝先行、リスク高×大改修＝段階化）。
• 依存順を考慮（命名はimport全域に波及するので一括/中央実行、挙動を変える整理はテスト先行）。
• すぐ着手/次スプリント/中長期の3層程度のロードマップにする。
• テストが無いコードベースでは「挙動を変える改善は特性化テスト先行」を明記する。
• 結果は references/output-schema.md 準拠の構造化 JSON を正本として生成し、自己点検を通してから Markdown を描画する（次の「出力」節）。

出力（構造化が正本）

正本は単一の構造化 JSON（スキーマは references/output-schema.md）。これを architecture-review.json （または指定先）に書き出し、同じ JSON から人間向け Markdown を描画して併せて提示する。 構造化することで別の修正エージェントがプログラムで読んで適用でき、優先度ソート・フィルタ・差分追跡も機械化できる。

JSON のトップレベル: meta / architecture / findings[] / principle_coverage[] / roadmap / strengths[] / assumptions[]。

• findings[] の各要素は前節の「実行可能修正仕様」を構造化したもの: id, title, viewpoints[], principles[], severity, effort, confidence, location{files[],anchor,lines}, problem, impact, fix{summary,recipe[],before,after,refs[],deps[],verify[]}, evidence。
• 語彙は固定: severity∈{critical,high,medium,low}, effort∈{S,M,L}, confidence∈{verified,likely,speculative}。
• ID は安定(F01…)。deps/roadmap/principle_coverage.finding_ids は ID 参照で結合。
• principle_coverage[] は principles.md の主要原則を網羅し violated=false も明示（原則軸の漏れ点検）。
• 出力前に references/output-schema.md 末尾の自己点検（ID一意・参照先実在・語彙準拠・着手対象の fix 充足）を必ず通す。

Markdown 描画順（JSON と相互参照できるよう各行に finding.id を付ける）:

1. アーキテクチャ要約（architecture: 目的/コンポーネント責務/依存方向(ASCII or Mermaid)/フロー/エントリ/外部依存/設計判断）
2. 観点別 改善提案（findings を severity 降順の表: 深刻度|観点|違反原則|id|指摘|場所|直し方|労力）
3. 原則別サマリ（principle_coverage: 各原則の違反あり(ID)/なし）
4. 優先ロードマップ（roadmap: now/next/later、各項目に finding.id と根拠）
5. 良い点 / 前提（strengths, assumptions）

原則（なぜそうするか）

• 設計を先に理解する: 改善は「あるべき構造」との差分。Phase 1 を飛ばすと表面的な指摘になる。
• 根拠で語る: file:line・grep結果・グラフ・ビルド出力。レビューの価値は具体性と検証可能性。
• 推測を断定しない: 「未使用/重複/壊れ」は静的解析やビルドで裏取り。誤検出はレビューの信頼を壊す。
• 網羅と優先の両立: 観点は全部当てる（網羅）が、出力は深刻度×労力で並べて実行可能にする。
• 大規模は並列化: サブシステム別のファンアウトで速く広く。所見は統合時に重複排除する。
• 過剰指摘を避ける: 「意図的な分割」を god-module と誤認しない等、設計意図(docstring/履歴)を尊重。

参考ファイル

• references/output-schema.md — 構造化出力(正本 JSON)のスキーマ・例・自己点検。Phase 3/出力時に必ず読む。
• references/viewpoints.md — 14観点の網羅チェックリスト（各観点の問い・アンチパターン・直し方）。Phase 2 で読む。
• references/principles.md — DRY/KISS/YAGNI/SoC/SOLID 等の原則カタログ。各指摘に違反原則を紐付けるため Phase 2 で読む。
• references/fix-recipes.md — 変更タイプ別(リネーム/共通化/死にコード/分割/依存是正/エラー処理/設定集約/テスト)の再現手順。Phase 2 の「直し方」を AI 実行可能にするため読む。
• references/methodology.md — 並列探索の組み方、import 到達可能性グラフの作り方、検証コマンド例。Phase 1/検証で読む。