arch-review

設計・アーキテクチャの「質」をレビューしてください。あなたはレビュー本体を行わず、**レンズに割って並列に走らせ、返ってきた結果を統合する**役です。1体に全観点を見せると、一番見つけたい急所（詳細がドメインに癒着し、差し替え時に広く壊れる箇所）を探す注意がほかの観点に取られ、見落としが減りません。レンズごとに並列に走らせ、判定・severity・改善案はレンズ側に決め切らせ、あなたには手順どおりの決定・統合・起票だけを残します。 ## Phase 1: 対象・判定範囲と「新規開発かどうか」を決める **禁止事項: ユーザーにファイル選択を求めてはならない。** まず引数を、**`--full` の有無**と、**それ以外（パス・スコープ名）**に分ける。 ### 対象を決める パス・スコープ名が無い場合、または "diff" の場合（1つ目は未コミットの変更、2つ目は未追跡の新規ファイル）： ```bash git diff HEAD --name-only --diff-filter=ACMR git ls-files --others --exclude-standard ``` 2つの結果がどちらも0件、または該当ファイルが `app/`・`infra/`・`docs/design/` のいずれにも属さない（アーキテクチャに無関係な変更しか無い）場合は「アーキテクチャに関わる変更が見つかりませんでした」と出力して終了する。 該当ファイルがあれば、結合・重複除去し、変更が属する**アーキテクチャ単位**（機能・モジュール・レイヤー）を推定する。設計ハブ `docs/design-hub.md` から辿れる関連設計書と、`app/`・`infra/` 上の該当コード構造を対象にする。 引数がパス・スコープ名の場合： - 設計書パス → その設計が描く構造を対象にする。実装が存在すれば該当コードの構造も併せて対象にする。 - ソースディレクトリ → ディレクトリ構成・import の依存方向・境界の実体を対象にする。対応する設計書があれば設計意図も対象にする。 対象が設計書のみ（実装前）・コードのみ・両方、のいずれでも成立させる。**どちらを見るかを全レンズ共通の情報として渡す。** ### 判定範囲を決める レビュー対象全体で、判定範囲を **差分** か **全文** に1つ決める。アーキテクチャはファイルをまたいで見るので、ファイルごとには分けない。 | 条件 | 判定範囲 | | ------------------------------------------------------------------------------------ | -------- | | 引数に `--full` がある | 全文 | | パス・スコープ名が無い | 差分 | | `git diff HEAD -- <パス>` に出力がある、またはパスの配下に未追跡の新規ファイルがある | 差分 | | どれでもない（パスを指定したが変更が無い） | 全文 | 差分なら、レビュー対象に属する変更ファイルの一覧（以下「差分のファイル一覧」）を決め、Phase 3 の手順1で引用と突き合わせるため、ここで各ファイルの `git diff HEAD -U0 -- <パス>` を1回だけ取っておく（未追跡の新規ファイルは全行が追加行）。 ### 新規開発かどうかを決める 対象が**新規開発（0 からの立ち上げ）**か**既存改修**かを1回だけ判定する。手がかりは `docs/project-context/project-claude.md`「現在のプロジェクトのフェーズ・状況」で、立ち上げ段階と書いていれば新規開発、それ以外（運用中など）は既存改修とする。同節が無い・読み取れないときは、対象ディレクトリ（引数がパス・スコープ名なら対象そのもの、引数が空なら Phase 1「対象を決める」で特定したアーキテクチャ単位）に実装コミットが1件も無ければ新規開発、あれば既存改修とする。各レンズがそれぞれ決めると、レンズごとに判定がずれるため、ここで決めた値をそのまま全レンズへ渡す。値が判定できなければ「新規開発かどうか」を渡さず、レンズ側の未判定処理（architecture-reviewer-agent「エラーハンドリング」）に委ねる。 ## Phase 2: レンズを並列起動する `architecture-reviewer-agent` を、**レンズごとに1回ずつ、1メッセージ内でまとめて** Task 起動する。逐次に投げると、待ち時間がレンズの数だけ積み重なる。 起動の前に `.claude/agents/architecture-reviewer-agent/architecture-reviewer-agent.md` の「レンズ一覧と担当観点（正典）」を Read し、そこにあるレンズ名をそのまま渡す。各起動には次を渡す: - **レンズ名**：レンズ一覧のうち1つ - **レビュー対象**：Phase 1 で決めた対象（設計書パス／ソースディレクトリ／対象ファイル一覧と、設計書のみ・コードのみ・両方のいずれか） - **新規開発かどうか**：Phase 1 で決めた値 - **判定範囲**：Phase 1 で決めた値（差分／全文）。差分なら差分のファイル一覧を添える。差分の中身はプロンプトに書き写さない——各レンズが `git diff HEAD -- <パス>` で自分で取る。書き写すと、その分がレンズの数だけ出力トークンになる **レンズの一覧と担当観点は `architecture-reviewer-agent` の定義が正典です。** ここに書き写しません——2箇所に持つと、割り方を変えたときに片方が古いまま残ります。 ## Phase 3: 統合してレポートを出す 各レンズのレポートを1つに統合する。判断は手順4の食い違いの裁定だけにし、次の手順で行う: 1. **引用の無い指摘を落とす**。判定範囲が差分なら、引用のどれもが Phase 1 で取った差分の追加行（`+`）・削除行（`-`）に無い指摘も落とす（2箇所を引用する指摘は、少なくとも一方が差分の行にあれば残す。範囲の制限をレンズの自己申告に頼らないため） 2. **同じ観点で引用が重なる指摘だけを1件にまとめる**（観点が違う指摘はまとめない） 3. **severity を変えない**（レンズの判定を尊重する） 4. **改善案が食い違ったら裁定する**：同じ箇所に別々のレンズが逆向きの改善案を出したら、ポリシーの条文（該当が無ければ `docs/policy/refined-engineer-judgment-principles.md`）を引用して一方を採り、捨てた改善案と根拠を添える。迷ったら AI が決める。例：「差し替えて壊す」が同じ Repository について「境界を足せ」、「投資の較正」が「実装が1つしかない投機的な境界を削れ」と出した場合（`architecture-reviewer-agent`「『差し替えて壊す』と『投資の較正』は対象が逆」を参照すれば通常は起きないが、起きたときの手順として残す） - 例外：どちらを採っても要件・プロダクトの方針が変わるとき、またはどちらかが取り消せない操作・外部に出る操作になるときだけは裁定しない。その食い違い1件を、`.claude/skills/quick-issue/SKILL.md` の書式でラベル `issue:needs-human-decision` を付けて `gh issue create` で起票し、ほかの指摘の処理は続ける。本文には、食い違った各指摘の観点名と引用を書き写す。同じワークフローの前回のレビューでこの手順により起票した Issue と同じ指摘なら、起票せず、既存の Issue 番号のまま起票済みとして扱う（手順7で引く対象にも含める）。同じ指摘かどうかは ai-review-gate-policy の「再レビューで同じ指摘が出たら、既存の Issue 番号で数える」で決める 5. **「次のステップ」の優先度は severity から機械的に決める**（Critical→高・High→中・Medium→低） 6. **観点一覧の行名で穴を照合する**：`references/review-criteria.md` の観点一覧の全行を、どれかのレンズの「判定した観点」と突き合わせる。判定済みとみなすのは、各レンズの「判定した観点」に名前が挙がっている観点だけ。無ければ「未判定」として観点名をそのまま報告する（**これはレビュー対象の欠陥ではなく、レンズの割り方の穴**。黙って埋めない） 7. **合否を判定する**：[ai-review-gate-policy](../../../docs/policy/ai-review-gate-policy.md) の合格条件（残してよい例外以外の Critical が0件）で決める。全観点を通じた Critical の合計から、手順4で `issue:needs-human-decision` として起票した食い違いに含まれる Critical の指摘数を引き（起票した食い違いの件数ではない）、残りが0件なら ✅ 合格、1件以上なら 🚫 要修正とする。起票した Issue 番号は「Issue にして残す Critical」に書く 出力は `references/report-format.md` の書式に従う。 ## レビュー結果の起票 統合後のレポートを出力したら、続けて `gh issue create` で GitHub Issue を起票してください。**ユーザーへの確認は行いません**（CLAUDE.md の boy-scout ルール）。指摘が1件も無ければ起票しません。Phase 3 手順4で `issue:needs-human-decision` として既に起票した指摘は、ここで重ねて起票しない。 | 起票対象 | 粒度 | タイトル | なぜ | | -------------- | ------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | [Critical] | 1件ごとに1 Issue | `[Critical] アーキテクチャ: <問題の概要>` | 差し替え時に広く壊れる急所は、境界の引き直しごとに着手・クローズされる。束ねると一部だけ直った状態が残る | | High ＋ Medium | 全件まとめて1 Issue | `[High・Medium] アーキテクチャレビュー指摘まとめ` | 1件ずつ判断するほど重くない。件数分に割ると Critical の Issue が埋もれる | タイトルの先頭ラベルは省略しないでください——本文を開かないと指摘の重さが分からない状態を避けるためです。タイトルの先頭には段番号を付けてください（例：`1. [Critical] …`）。振り方は Issueの階層ガイド（`docs/reference/issue-hierarchy.md`）の「段番号（着手順）」に従います。 本文の書き方・ラベル・起票前セルフチェックは `.claude/skills/quick-issue/SKILL.md` が正典です。Read して従ってください。 Issue 本文の「現状」には、レビュー結果の**箇所・理由・改善案**を書き写してください（レビュー結果を読み返さずに着手できるように）。 引数: $ARGUMENTS