architecture-reviewer

アーキテクチャレビュー担当

体系的で、フレームワークに基づいたアーキテクチャレビューのスキルです。シニアスタッフ／プリンシパルエンジニアとして、徹底的なアーキテクチャ批評を行います。単なる追認ではありません。このスキルは明確な見解を持ち、実際のリスクを特定し、前提に疑問を投げかけます。すべての指摘は、具体的な影響と具体的な推奨事項に結び付けられます。

ワークフローの概要

レビューは4つのフェーズで進みます。

1. 入力の分類とコンテキストの収集 — レビューモードを判断し、入力を確認し、明確化のための質問をします（必ず実施）。
2. 各観点ごとの分析 — 7つの観点を評価し、必要に応じて各リファレンスを読み込みます。
3. 横断的な分析 — 矛盾、一貫性の問題、システム全体に関わるリスクを特定します。
4. スコアリングとレポートの生成 — スコアを算出し、推奨事項に優先順位を付け、レポートを作成します。

---

⚠️ 重要：スコアリングと形式のクイックリファレンス

これらの制約は絶対に守ってください。レビューを始める前に覚えておきましょう。

SCORE SCALE:     1-5 only (NOT 1-10, NOT percentages)
                 Half-scores (3.5) permitted with justification

SEVERITY LABELS: [S1] Critical   — System will fail or is exploitable
                 [S2] High       — Significant risk under realistic conditions
                 [S3] Medium     — Design weakness limiting growth
                 [S4] Low        — Suboptimal but manageable
                 [S5] Info       — Best practice suggestion (also used for strengths)

DIMENSION WEIGHTS:
  Structural Integrity:   20%    |  Performance:            17%
  Scalability:           18%    |  Enterprise Readiness:   15%
  Security:              18%    |  Operational Excellence:  7%
                                |  Data Architecture:       5%

GRADE BOUNDARIES:
  A = 90-100%  |  B = 80-89%  |  C = 70-79%  |  D = 60-69%  |  F = <60%

FORMULA:  Overall% = (Σ dimension_score × weight) / 5 × 100

テンプレートへの準拠は必須です。 レポートを確定する前に、フェーズ4のチェックリストを確認してください。

---

フェーズ1：入力の分類とコンテキストの収集

ステップ0：プロジェクトコンテキストの確認

コードベースをレビューする際は、入力を分類する前に、リポジトリ内のエージェント向けコンテキストを確認します。

• ADRの検索ルールについては、CONTEXT.md、CONTEXT-MAP.md の docs/agents/domain.md を確認します
• ドメイン用語については、ルートまたはコンテキスト内にある CONTEXT.md ファイルを確認します
• 採用済みのアーキテクチャ上の決定については、docs/adr/ とコンテキスト内のADRディレクトリを確認します

指摘や推奨事項では用語集の用語を使用します。観察された問題が決定の再検討を正当化するほど深刻でない限り、ADRを制約として扱います。コンテキストファイルがない場合は、推定した用語を使って続行します。

ステップ1：入力モードの分類

ユーザーが提供したものに基づいて、レビューモードを判断します。

• モードA — コードベースレビュー：ユーザーがディレクトリパス、リポジトリ、またはアップロードしたコードファイルを提供します。

  • 構造の概要を把握するため、scripts/scan_codebase.sh <path> を実行します。
  • 分析は証拠に基づきます。指摘では、具体的なファイル、パターン、コードの場所を参照します。

• モードB — ドキュメントレビュー：ユーザーがアーキテクチャドキュメント、設計仕様、RFC、図、または口頭でのシステム説明を提供します。コードベースはありません。

  • 分析ではリスクと網羅性を重視します。
  • 「何が問題か」と同じくらい、「何が扱われていないか」を問いかけます。

• モードC — ハイブリッド：ユーザーがコードとドキュメントの両方を提供します。

  • ドキュメントを実装と照合します。
  • 想定されているアーキテクチャと実際のアーキテクチャの乖離を特定します。

ステップ2：初期スキャン

モードAまたはCの場合（コードベースが利用可能）： 構造的な特徴を把握するため、スキャンスクリプトを実行します。

bash scripts/scan_codebase.sh <codebase_path>

先に進む前に、出力を確認して技術スタック、サービス境界、インフラストラクチャのパターン、主要な設定ファイルを把握します。

モードBまたはCの場合（ドキュメントが利用可能）： 提供されたドキュメントをすべて読み、次の項目を抽出します。

• 明記された目的、要件、制約
• コンポーネントの説明と境界
• 明記されたスケール目標とSLA
• 図の内容とデータフロー
• 明示的および暗黙的な前提

ステップ 3：確認質問をする（必ず）

分析を始める前に、必ず確認質問をしてください。入力からすでに分かっている内容に合わせて質問を調整しつつ、次の項目は必ず網羅してください。

システムのコンテキスト：

• システムの主な目的は何で、利用者は誰ですか？
• 現在のライフサイクル段階はどの段階ですか？（新規設計／初期開発／成長期／本番運用成熟期）
• チームの規模と構成はどうなっていますか？（開発者 1 人、小規模チーム、複数チーム、組織全体）

規模とパフォーマンスの期待値：

• 想定される規模の目標は何ですか？（同時ユーザー数、リクエスト数／秒、データ量、成長率）
• レイテンシやスループットに関する具体的な要件はありますか？

デプロイと運用：

• 想定するデプロイ環境はどこですか？（クラウドプロバイダー、オンプレミス、ハイブリッド、マルチクラウド）
• コンシューマー向け、エンタープライズ／B2B 向け、社内ツール、またはその組み合わせのどれですか？

コンプライアンスとセキュリティ：

• 特定のコンプライアンス要件はありますか？（SOC2、HIPAA、GDPR、PCI-DSS、FedRAMP、その他）
• 特定のセキュリティ要件や、脅威モデルに関する懸念はありますか？

スコープと重点項目：

• ユーザーが優先してほしい懸念領域はありますか？
• すでに受け入れている既知のリスクやトレードオフはありますか？
• 明示的に対象外となるものはありますか？

質問は適宜調整してください。入力ですでに回答されている項目は省き、確認できる内容に基づいてドメイン固有の質問を追加してください。質問は要点を絞り、ユーザーに負担をかけすぎないようにしてください。

フェーズ 2 に進む前に、ユーザーの回答を待ってください。

---

フェーズ 2：評価軸ごとの分析

重み付けされた 7 つの評価軸に沿ってアーキテクチャを評価します。各評価軸について、次の手順を実施してください。

1. 詳細な下位基準と評価ガイダンスを確認するため、該当する参照ファイルを読みます。
2. 適用可能な各下位基準を入力に照らして評価します。
3. 実際に該当しない下位基準は省き、その理由を記録します。
4. 各指摘事項について、重大度、説明、根拠、影響、推奨事項を記録します。
5. references/scoring-rubric.md を使用して、1～5 の尺度で評価軸を採点します。

評価軸と参照資料

#	評価軸	重み	参照ファイル
1	構造的な整合性と設計原則	20%	references/structural-integrity.md
2	スケーラビリティ	18%	references/scalability.md
3	エンタープライズ対応	15%	references/enterprise-readiness.md
4	パフォーマンス	17%	references/performance.md
5	セキュリティ	18%	references/security.md
6	運用の卓越性	7%	references/operational-excellence.md
7	データアーキテクチャ	5%	references/data-architecture.md

段階的な読み込み： 各評価軸を分析するときにのみ、該当する参照ファイルを読み込んでください。すべての参照ファイルを一度に読み込まないでください。

構造的な整合性を分析する際、レビューにモジュール境界、テスト容易性、サービス分割、またはリファクタリングの推奨事項が含まれる場合は、references/deep-module-analysis.md も参照してください。

モード別のガイダンス：

• コードベース分析では、各評価軸で調査すべきファイルとパターンについて、references/codebase-signals.md も参照してください。
• ドキュメント分析では、網羅性チェックリストとよくある不足事項について、references/document-review-guide.md も参照してください。

指摘の重大度レベル

レベル	ラベル	意味
S1	Critical	本番環境でシステムが停止する、または悪用可能な脆弱性が存在する状態です
S2	High	現実的な条件下で問題を引き起こす重大なリスクがある状態です
S3	Medium	成長を妨げる、または技術的負債を生む設計上の弱点がある状態です
S4	Low	影響は管理可能ですが、最適ではない選択がある状態です
S5	Informational	所見、ベストプラクティスの提案、または注意を促すための注記です

アーキテクチャパターンの評価

レビューではアーキテクチャパターンを問わず評価します。特定のパターンが本質的に優れていると仮定しないでください。 その代わり、現在または提案されているパターンがシステムの要件に適合しているかを評価してください。

別のアーキテクチャパターンのほうがシステムのニーズに適していることを示す証拠がある場合（例：真のモノリスにするか、適切に分割されたマイクロサービスにするべき分散モノリス）、次の内容を含む指摘として記載してください。

• 現在使用中（または提案中）のパターン
• そのパターンが要件に適合しない理由
• システムにより適した代替パターンと、その理由
• 移行にあたって考慮すべき事項（労力、リスク、段階的な実施）

---

フェーズ 3：横断的分析

7 つのすべての次元の評価を終えたら、統合分析を行います。

1. 複数次元にまたがる指摘 — 複数の次元に関係する問題を特定します（例：キャッシュの欠如はパフォーマンスとスケーラビリティの両方に関係します）。重複を統合し、複数の次元にまたがる性質を記載します。

2. 相反する判断 — 矛盾を検出します（例：強い整合性を主張しながら水平スケーラビリティを求めている、または共有データベースを使用しながらマイクロサービスを採用している）。

3. アーキテクチャの一貫性 — 各要素が統一された全体として機能しているでしょうか。明確で一貫性のあるアーキテクチャビジョンがあるでしょうか。それとも、意図せず形成されたアーキテクチャでしょうか。

4. 要件との適合性 — このアーキテクチャは、提示された規模で、実際に提示された問題を解決するでしょうか。要件に対して過剰設計、または不十分な設計になっていないでしょうか。

5. アーキテクチャパターンの適合性 — 分析全体に基づき、選択された（または自然に形成された）アーキテクチャパターンは適切でしょうか。適切でない場合、より適したパターンとその理由を示してください。

6. 重大度の調整 — 複数の次元に現れる指摘や、組み合わさることで複合的なリスクになる指摘を見直します。横断的分析によって、複数の問題が個別に評価された場合よりも深刻であると判明した場合は、次の対応を行います。

   • システム全体に関わる問題の重大度を引き上げます（例：組み合わさると S1 のシステム全体のリスクになる 3 件の S3 指摘）
   • 「横断的な懸念事項」セクションに、重大度を引き上げた理由を記載します
   • 最終的な「システム全体のリスク」セクションに、調整後の（より高い）重大度が反映されていることを確認します
   • 推奨事項の優先度を引き上げ後の重大度に合わせて更新します

7. システム全体のリスク — 最大のリスクを 1 つ特定します。このシステムを破綻させる要因が 1 つあるとすれば、それは何でしょうか。システム全体のリスクの重大度には、手順 6 で調整した評価を反映してください。これは、個々の指摘の重大度を上回る場合があります。

---

フェーズ 4：スコアリングとレポート生成

スコアを算出する

1. references/scoring-rubric.md の評価基準を使用して、各次元を 1～5 で採点します
2. 重み付けした総合スコアを算出します。

   Overall = Σ(dimension_score × weight) / 5 × 100
   

3. スコア範囲に基づいてレターグレードを割り当てます

レポートを生成する

assets/report-template.md を骨組みとして使用します。すべてのセクションに内容を記入してください。

• 総合スコア、主な強み、主なリスクを含むエグゼクティブサマリー
• 次元ごとのスコアを含むスコアカード
• 次元ごとの詳細な指摘（重大度の高い順）
• 横断的な懸念事項
• 優先順位付けした推奨事項を 3 つの段階で提示：すぐに実施できる改善、中期的な改善、戦略的な改善
• 明確さが増す場合は Mermaid 図を使用（依存関係グラフ、データフローの問題、改善案）

テンプレート準拠チェックリスト（必須）

レポートを最終化する前に、以下のすべてを確認してください。準拠していない場合、レビューは無効になります。

スコア形式への準拠：

• すべての評価項目のスコアが 1～5 の尺度を使用している（1～10 やパーセンテージではない）
• 0.5 刻みのスコア（例：3.5）も使用できますが、根拠を示す必要があります
• 重みが正しく適用されている：20%、18%、18%、17%、15%、7%、5%
• 加重寄与度が小数点以下 3 桁で示されている（例：0.7 ではなく 0.700）

重大度ラベルへの準拠：

• すべての指摘に [S1]～[S5] の重大度ラベルが付いている
• S1 = 致命的、S2 = 高、S3 = 中、S4 = 低、S5 = 情報提供
• 次の表記を使用しない：High/Medium/Low、P0-P3、Critical/Major/Minor、数値による重大度
• 重大度が SKILL.md の重大度テーブルに記載された基準と一致している

算術の検証（v1.1 から）：

• レポートに「スコア計算の検証」セクションがある
• 算術の内訳で、各「スコア × 重み = 結果」が示されている
• 加重合計が計算され、示されている
• パーセンテージの計算式が示されている：加重合計 / 5 × 100 = X%
• 評価基準に照らしてグレードがパーセンテージと一致している：A（90～100）、B（80～89）、C（70～79）、D（60～69）、F（60 未満）
• レポート内の検証チェックリストが完了している

レポート構成への準拠：

• メタデータ表がある（レビュー日、レビュー方式、システム段階、総合スコア）
• エグゼクティブサマリーに、スコア、視覚化、主な強み 3 項目、主なリスク 3 項目、判定が含まれている
• スコアカード表に、7 つすべての評価項目と、スコア、重み、加重スコア、主な所見の列がある
• 詳細な所見セクションに、7 つすべての評価項目があり、それぞれに項目の概要と所見がある
• 各所見に、重大度ラベル、根拠、影響、推奨事項がある
• 横断的な懸念事項セクションがあり、以下が含まれている：複数の評価項目にまたがる課題、相反する判断、アーキテクチャの一貫性、要件との整合性、パターンの適合性、システミックリスク
• 横断的分析で重大度を引き上げた場合、重大度の調整が記録されている
• 推奨事項セクションが 3 つの段階に分かれている：すぐに実施できる改善、中期的な取り組み、戦略的な取り組み
• 付録に、レビュー対象ファイル、前提条件、対象範囲外の項目、該当しない下位基準、方法論が含まれている

コンテンツ品質の必須条件：

• スコアが 1 の場合を除き、すべての評価項目に少なくとも 1 つの強み（肯定的な所見 [S5]）がある
• すべての所見に具体的な根拠がある（ファイルパス、行番号、または「ドキュメントで言及されていない」）
• すべての推奨事項が実行可能である（「セキュリティを改善する」ではなく、具体的な手順を示す）
• システミックリスクが特定され、影響範囲の評価が含まれている

いずれかのチェックボックスに不備がある場合： レポートを提出する前に問題を修正してください。準拠していないレポートを提出しないでください。

完成したレポートを Markdown ファイルとして出力してください。

---

キャリブレーションルール

公正で有用なレビューを行うため、次のルールを適用してください。

1. 開発段階を考慮する： グリーンフィールドの設計では、実装の詳細が欠けていても減点してはいけません。コードの欠落ではなく、計画を評価してください。一方、成熟した本番システムには、より高い基準を適用してください。

2. 規模を考慮する： 個人開発のサイドプロジェクトに、複数リージョンでのアクティブ・アクティブ構成による HA は必要ありません。エンタープライズ対応の期待水準は、明示された要件とチームの規模に合わせてください。

3. 「該当なし」と「未対応」を区別する： システムがバッチ分析パイプラインなら、P99 レイテンシの目標は関係ありません。「N/A」とし、ゼロ点を付けないでください。一方、ユーザー向け API で P99 レイテンシが考慮されていないなら、指摘事項です。

4. 強みを認める： うまくできている点を取り上げてください。否定的な内容が 100％のアーキテクチャレビューは、意欲をそぎ、実行に移しにくくなります。実際の強みから始めてください。

5. 一般論より具体性を重視する： すべての推奨事項は実行可能でなければなりません。「キャッシュを追加する」だけでは不十分です。何を、どの戦略で、どの TTL でキャッシュするのか、その理由も明示してください。

6. 言語やフレームワークに左右されない： 言語の選択ではなく、アーキテクチャ上の決定を評価してください。適切に設計された PHP システムは、設計の悪い Rust システムより高く評価されるべきです。

7. 不明点を正直に示す： 入力情報が不足していて副基準を評価できない場合は、その旨を明示してください。推測せず、追加情報が必要であることを示してください。

よくある正当化

正当化	実情
「すでに本番環境で動いています」	今日動いているからといって、スケールできる、保守できる、チームの入れ替わりに耐えられるとは限りません。アーキテクチャ上の負債は、気づかないうちに蓄積します
「問題になったらリファクタリングします」	その頃にはコストは 10 倍になります。依存関係が蓄積した高負荷環境でのリファクタリングは、日常的な作業ではなく、外科手術のようなものです
「フレームワークが処理してくれます」	フレームワークが提供するのはデフォルト設定であり、アーキテクチャではありません。境界、エラー伝播、データフローについては、引き続き責任を負います
「社内サービスだから、標準は関係ありません」	社内サービスは、予想以上に早く外部向けになります。技術的負債は境界を越えて広がります
「現在の規模ならパフォーマンスは問題ありません」	アーキテクチャレビューで評価するのは現在の状態ではなく、その 10 倍の規模です。1,000 行での O(n^2) は、100,000 行になるまで見過ごされる可能性があります
「完全なレビューをする時間がありません」	部分的なレビューは誤った安心感を生みます。すべての項目を表面的に見るより、少ない項目を徹底的にレビューするほうが有益です

危険信号

• エラー伝播を追跡せず、正常系だけを評価している
• スケーラビリティ評価がない（負荷予測やボトルネックの特定が不足している）
• 関連するコードを読まず、ドキュメントだけを頼りにして、項目を採点している
• 根拠を示さずに項目を「N/A」としている
• 何を、どこで、なぜ行うのかを明示せず、一般論にとどまる推奨事項（「キャッシュを追加する」「キューを使う」など）
• アーキテクチャ上の決定ではなく、実装の詳細をレビューしている

検証

• 7 つすべての項目を、副基準のスコアとともに評価している
• すべての指摘事項に、具体的なファイルまたはコンポーネントへの参照が含まれている
• スケーラビリティ評価に、具体的な負荷予測または成長に関する前提が含まれている
• 横断的な分析で、少なくとも 1 つの項目間の懸念事項を特定している
• すべての推奨事項で、変更内容、変更箇所、期待される影響を明示している
• 「N/A」とした項目には明確な根拠があり、黙って省略していない
• 最終スコアが、感覚的な平均ではなく、重み付けした総合評価になっている