reviewing-architecture-doc

reviewing-architecture-doc — SKILL.md

バリアント： 標準 · 使用する場面： 完成したシステム全体のアーキテクチャ文書（およびリンクされた ADR ファイル）を受け入れゲートとして評価する場合。エンジニアがシステムを理解し、機能の技術設計をその中に位置づけられるかを確認し、実行可能な指摘とともに VERDICT: approve|revise を出力します。グリーンフィールド、または変更（差分の範囲に限定）。

概要

このスキルは、アーキテクチャ文書を作成・評価する一対のスキルのうち、レビュー側を担います。完成したシステム全体のアーキテクチャ文書と、リンクされた ADR ファイルを持つレビュアーが読み込み、次の一つの問いに照らして評価します。新しいエンジニアが、著者に尋ねることなく、システムの構造と主要な決定の理由を理解でき、機能の技術設計をアーキテクチャ内に位置づけられるか。 固定のアーキテクチャ品質チェックリスト（10 項目）を適用します（これはアーキテクチャ文書の著者が作成時に用いる基準と同じです。authoring-architecture-doc の Step-7 を参照。作成基準とレビュー基準がずれないようにします）。その後、機械で解析できる単一の判定と、著者が一度の改訂で対応できる指摘を出力します。これは受け入れゲートであり、文書の作成、修正、書き換えは行いません。評価して指摘を返し、作成者が改訂します。

評価対象は 2 つの成果物です。アーキテクチャ文書と、リンクされた ADR ファイルです。 条件 4（ADR の仕組み、つまりインデックスとファイルの同期、ADR ごとの品質、書き換えの禁止）は、文書だけでは検証できません。レビュアーには、リンクされた ADR ファイル（または adr/ ディレクトリ）が必要です。渡されていない場合は、条件 4 を検証不能として指摘し、その旨を明記してください。内容を捏造してはいけません。

基準は著者と一元化されています。著者が用いる手法、つまり C4 のビュー選択、arc42 のセクション構成、ATAM のトレードオフ分析、4+1 ビュー、Mermaid の図形式は、成果に基づいてレビュアーが評価するための手段です（境界が示されているか、決定が関連づけられ追跡可能か、各 NFR の目標が実現されているか）。要求すべき条件ではありません。ただし、境界には注意してください。 ADR の仕組み（条件 4）、NFR の実現（条件 6）、システムレベルのオブザーバビリティに関する方針（条件 7）は、アーキテクチャ文書にとって実際に重要な条件です。これらは「後付け」の条件ではありません。手段であるのは手法（C4／arc42／ATAM／4+1／図の選択）であって、成果（リンクされた ADR、実現された目標、明示された運用性のシグナル）ではありません。

いつ有効化するか

• 完成したアーキテクチャドキュメントについて、エンジニアがその範囲内で構築を始める前（または機能の技術設計をその範囲内に位置付ける前）に、承認／修正の判断が必要な場合。
• 作成者が作成したアーキテクチャドキュメントの独立したレビュアー／ゲート担当者である場合。
• 以前の revise 判定後に改訂されたアーキテクチャドキュメントを再評価する場合。
• 承認済みアーキテクチャドキュメントと変更リクエストからなる amend を、差分の範囲に限定してレビューする場合（cond-10）。

次の場合は有効化しないでください：

• アーキテクチャドキュメントを作成または修復する場合 → authoring-architecture-doc を使用してください。このスキルではドキュメントを作成しません。
• 上流の PRD／プロダクト方針（何を／なぜ、NFR の目標）をレビューする場合 → PRD レビュースキルを使用してください。このゲートでは、その一段下の層として、システム全体がどのように構成されているかを判断します。
• 1 つの機能の技術設計（TDD — アーキテクチャ内で 1 つの機能をどのように構築するか）をレビューする場合 → さらに一段下のレイヤーを対象とする reviewing-technical-design を使用してください。
• api-spec または data-model 自体（ワイヤーコントラクト／永続化されるスキーマ）をレビューする場合 → これらはアーキテクチャドキュメントが参照する独立したドキュメントであり、それぞれに独自のゲートがあります。
• 汎用／アドホックなエンジニアリング設計ドキュメント、RFC、単独の ADR、仕様書、または計画（ドキュメントライブラリの architecture-doc 成果物として作成されたものではない場合）をレビューする場合 → これらの種類のドキュメントについて、コードベースに照らして設計上の主張を検証する design-review を使用してください。このゲートの対象は、template: architecture-doc の frontmatter によって正式に特定される、ドキュメントライブラリの architecture-doc 成果物です。frontmatter がない場合に限り、# Architecture: 見出しを代替のシグナルとして使用します（単に「Architecture」というタイトルを付けただけでスタンプのない汎用ドキュメントは、引き続き design-review の対象です。architecture-doc 成果物に含まれない単独の ADR も、引き続き design-review の対象です）。
• テンプレート／セクションへの準拠を確認する場合 → それはテンプレートに関する確認です。このスキルが判断するのは、すべての見出しが存在するかどうかではなく、基準に照らした品質です。

ワークフロー

ステップ 1：ADR ファイルを手元に置き、新鮮で独立した視点からアーキテクチャ全体を読む

作成者の説明に頼らず、システムに初めて触れるかのように、アーキテクチャドキュメントを最初から最後まで読んでください。システム内で構築するすべての人を見守るゲートキーパーとしての立場を取ります。指摘に重みがあるのは、ドキュメントが解決しておくべきことを読み手が再導出しないと、構造を把握できない、または機能を位置付けられないことを示す場合に限られます。リンクされた ADR ファイル（cond-4 で必要）に加えて、上流の PRD／プロダクト方針（cond-8 で照合）と、ドキュメントが参照する api-spec／data-model（cond-2 のレイヤー確認）も開いた状態にしておいてください。これは amend ですか？ 既存ドキュメントに対する変更リクエスト／差分を受け取った場合は、差分を対象とする手順を実行してください（cond-10 が有効であり、レビュー範囲を変更された判断／構造とその波及に限定します）。グリーンフィールドでの初回構築には変更リクエストがないため、cond-10 は該当しません。

ステップ 2：アーキテクチャ品質チェックリストを実行し、各条件を判断する

以下の各条件について、合格または不足を判断してください。条件が不合格となるのは、実際に特定できる欠陥がある場合に限ります。「自分なら別の構成にした」は不足にあたりません。不足ごとに、正確な箇所と欠けている内容を記録してください（ステップ 4 で実行可能な指摘にします）。条件は単一の基準です。独自の条件を追加しないでください。

以下のケイパビリティ境界チェック項目が適用されるのは、作成の呼び出し時に capability_record が注入され、レビューコンテキストとして利用できる場合のみです。存在しない場合は該当なしとして扱い、境界が定義されていないのにケイパビリティ境界マーカーがないことをドキュメントの減点対象にしないでください。

1. コンテキスト、境界、対象となる懸念。 新しい読者が、システムの責任範囲と責任範囲外を説明できます。境界（対象範囲／明示的な対象外＋担当者）が明確で、すべてのアクターと外部依存関係が明記され、コンテキスト図と説明文の内容が一致し、特定されたすべてのステークホルダーの懸念が何らかのセクション／ビューで扱われています。暗黙の境界、明記されていない外部依存関係、または扱うセクションのない明示的な懸念があれば、ギャップです。(縮小できないベースライン：境界と外部依存関係の集合は常に明記します。これらがないと、統合リスクが見えなくなります。)
2. 構造と抽象度。 主要なコンポーネントはそれぞれ一度だけ、単一の責務と種類を添えて明記されています（説明のないボックスはありません）。トポロジーでは、各エッジの方向とプロトコル／スタイルが示され、統合境界では契約の担当者が明記されています。ドキュメントはシステム全体の抽象度を保ちます。つまり、主要インターフェースとデータストアを構造的に示し、すべてのエンドポイント（api-spec）、すべてのテーブル（data-model）、または1つの機能の実装（TDD）までは記述しません。ゴッドコンポーネント、説明のないボックス、方向／プロトコルがないエッジ、またはエンドポイント／テーブル／機能の詳細への抽象度の逸脱があれば、ギャップです。(縮小できないベースライン：コンポーネントごとに1つの責務を持たせ、抽象度を保つこと。)
3. 図と説明文の同期。 図のすべてのボックス／矢印が説明文に記載され、その逆も成り立っています。図は単独で読んでも意味が通じ、負荷を左右する場合は実行時／デプロイメントのビューがあります。説明文で説明されていない図の要素（または図にない説明文中のコンポーネント）、あるいはデプロイメントビューのないマルチサービス／マルチ環境システムがあれば、ギャップです。(縮小可能：シンプルなシステムでは図はほとんど、またはまったく必要ありません。図がある場合は同期のルールが適用されます。)
4. ADR の仕組み（特徴を決める条件）。 重要な決定はすべて、独立したリンク付きの ADR ファイル（1 ファイルにつき1つの決定）に記録されており、ドキュメント内に埋め込まれていません。決定事項のインデックスと ADR ファイルは同期しており（双方向の有効なリンクがあり、置き換えられた項目にはその旨が記されています）、承認済み ADR は書き換えられていません（変更は新しい ADR で置き換えます）。リンク付き ADR ではなく決定を本文に貼り付けている、1つの ADR に2つの決定をまとめている、インデックスのリンクが切れている／欠けている、または承認済み ADR をその場で編集している（履歴が失われる）場合は、ギャップです。(縮小できないベースライン：承認済み ADR の書き換えは、規模に関係なく不備です。システムが簡素であれば ADR の数が少なくなるだけです。ADR ファイルが提出されていない場合は検証できません。問題として記録し、内容を捏造しないでください。)
5. 重要な決定の追跡と正当化。 重要な選択／決定（実行環境、データストア、メッセージング、ホスティング、信頼モデルなど、変更コストの高いもの）には、根拠（要件／NFR／ASR）と、負けたトレードオフを含む現実的な代替案（形だけの案ではないもの）が記されています。負荷を左右する選択に根拠がない場合や、検討した代替案がない場合（単に「X を選んだ」と断言している場合）は、ギャップです。「チームのデフォルト」は、そう明記されていれば許容されます。(縮小できないベースライン：トレードオフを検討する規律は、どの規模でも適用されます。)
6. NFR の実現とトレードオフ。 PRD に記載された NFR の目標にはすべて、それを実現する仕組みがあります（目標を言い換えただけではありません）。負荷を左右する目標は、測定可能です（応答指標を含む品質属性シナリオがあります）。品質属性同士が競合する場合は、そのトレードオフが明記され、解決されています。仕組みのない目標の言い換え、「高可用性」をうたっているのに議論されていない単一障害点がある場合、または明らかな緊張関係（レイテンシと一貫性、コストと可用性など）が一度も明記されていない場合は、ギャップです。(縮小可能：厳しい NFR のない簡素なシステムでは、軽い記述で構いません。目標の実現に役立たない仕組みは過剰設計です。)
7. システムに該当する横断的関心事への対応。 統合境界ごとに、レジリエンスの方針（タイムアウト／再試行／サーキットブレーカー／フォールバック／縮退）を示します。セキュリティ（信頼境界／認証・認可／シークレット／信頼できない入力）、機微データが流れる場合のプライバシー、およびシステムレベルの可観測性戦略（システムを運用可能にするゴールデンシグナル／ヘルス／SLO 監視の方針）にも対応します。外部依存関係に対する遅延／停止時の方針がない場合、外部公開システムに信頼境界がない場合、またはマルチサービスシステムに可観測性戦略がない場合は、ギャップです。(縮小可能：外部依存関係のない単一プロセスのツールでは、この大部分を正当に省略できます。存在する外部依存関係には障害時の方針を、外部に公開する境界にはセキュリティ方針を必ず設けます。)
8. 要件／ASR の網羅性。 アーキテクチャ上重要な要件にはすべて、それを実現する構造／決定が対応しています（未対応の ASR はありません）。また、主要な構造にはすべて根拠があります（孤立した構造はありません）。後続作業で利用できる状態であり、機能の技術設計を担当する人が著者に尋ねなくても、その機能のアーキテクチャ上の位置づけを決められます。実現する構造のない ASR、または要件に対応していないコンポーネント／サブシステムがあれば、ギャップです。(縮小可能：要件が1つのシステムでは、追跡は簡単です。)
9. 前提は明示され、根拠に基づいており、捏造されていないこと。実システムとの整合性。 真の未知事項は、確定事項のように取り繕わず、前提／未解決の質問として提示します。完全に見せるために、トポロジー、ベンチマーク、ベンダーの主張、根拠などを捏造しません。また、システムの現在の状態に関する主張は実際のコード／トポロジーで検証します（file:line を引用し、確認できないものには未検証と記します）。これは、以前 design-review が担っていた、出荷済みシステムとの整合性確認です。完全に見えるよう偽っている、限界／仕組みを捏造している、または既存の動作に関する主張がコードと矛盾している場合は、ギャップです。(グリーンフィールド条項 — 捏造しないことは縮小できないベースラインです。ただし、照合する既存のコード／システムがない場合（まったく新しいシステム、架空の例を示すドキュメントなど）、整合性確認は該当なしであり、決して阻害要因にはなりません。未検証と記し、誤った修正はしないでください。)
10. （改訂時のみ）変更範囲が適切に定められ、波及範囲が漏れなく処理され、バージョン管理されていること。 既存のアーキテクチャドキュメントに対する変更をレビューする場合、変更箇所について条件1〜9を満たします。決定の変更には、新しい、置き換え用の ADRを使い（承認済み ADR は書き換えず）、インデックスを同期させます。変更された構造は引き続き根拠と対応づけられています（または上流の PRD 改訂が必要であることを明記します）。下流に広く及ぶ波及範囲を処理し、変更の影響を受ける機能ごとの技術設計一式と、api-spec／data-model／deployment／runbook を明記します。ドキュメント自体のバージョンを上げ、変更履歴（誰が／いつ／何を／なぜ）を記載します。変更範囲が定まっていない、承認済み ADR が書き換えられている、インデックスが同期していない、波及範囲が明記されていない、または変更履歴がない場合は、ギャップです。(縮小可能：グリーンフィールドの初回構築では、この条件は該当しません。変更のないドキュメントを全面的に再レビューせず、初稿に変更履歴を求めないでください。)
11. ケイパビリティの網羅性（ケイパビリティの記録がない場合は該当なし）： すべての有効なケイパビリティが名前付きコンポーネントとして示されていること。depends_on の DAG が依存関係図に反映されていること。

比例性。 「把握でき、再導出せずに配置できる」ために必要な内容は、システムの規模に応じて変わります。小規模な製品では、不要なものを正当に省略できます。コンポーネントが 1 つならトポロジー図は不要、単一プロセスならデプロイメントビューは不要、外部依存がなければレジリエンスマトリクスは不要、厳格な NFR がなければ §6 は簡潔でよく、機微なデータがなければプライバシーの記述は不要、初稿なら変更履歴は不要です。評価するのは、文書の長さやテンプレートの各セクションが存在するかではなく、意思決定の完全性と表面積の最低要件です。適用されるすべての条件を満たす、小規模で完全なアーキテクチャは合格です。簡潔さを理由に不足をでっち上げないでください。

ステップ 3：判定を決める

• approve — 適用されるすべての条件を満たしています。新しいエンジニアがシステムを把握し、アーキテクチャを再導出せずに機能の設計をその中に位置づけられます。主要な意思決定には根拠があり、記録されています。文体上の改善点を思いついたとしても承認してください。基準は把握可能性と構築可能性であり、完璧さではありません。
• revise — 1 つ以上の条件に、具体的な不足があります（名前のない外部依存関係、説明のない図形、リンクされた ADR ではなく本文中に埋め込まれた意思決定、書き換えられた承認済み ADR、仕組みの説明がないまま再掲された NFR の目標、障害時の方針がない外部依存関係、孤立した構造、捏造された主張、スコープが定まっていない、または変更の波及で壊れている修正など）。

努力を示したり、あるとよいだけの要望を伝えたりするために revise にしないでください。条件を満たしているか、満たしていないかのどちらかです。

ステップ 4：判定と実行可能な指摘を出力する

判定は単独の行に出力してください。VERDICT: approve または VERDICT: revise という文字列を、その行だけに記載し、前後にコードフェンス、引用符、その他の語句を付けないでください（ここでのフェンスは説明用です）。

VERDICT: approve

続く行に指摘を列挙してください。revise の場合、すべての指摘に、満たしていない条件、正確な場所、修正方法を含め、作者が一度の作業で解決できるようにしてください。approve の場合、指摘は任意の非ブロッキングな注記です。修正が必要だと受け取られる内容にしないでください。

良い指摘は、不足と修正方法を明示します。

revise — ADR の仕組み（条件 4）、§7 と本文：「DynamoDB ではなく PostgreSQL を選んだ」という意思決定が、背景・代替案・結果をすべて含めて §5 にインラインで記載されており、リンクされた ADR として記録されていません。修正：独立した adr/0003-datastore.md（Nygard 形式）に移し、§7 の意思決定インデックスからリンクしてください。これにより、意思決定を独立して参照でき、インデックスを唯一の情報源として維持できます。

悪い指摘は曖昧で、具体的な行動につながりません。

意思決定のセクションをもう少し整理できるかもしれません。 (どの意思決定でしょうか？ 何が基準を満たしていないのでしょうか？ どう直せばよいのでしょうか？)

ルール

必ず守るルール（決して違反しないでください）：

• 判定行を正確に1行だけ出力してください。VERDICT: approve または VERDICT: revise のいずれかを、それだけを記した独立した行に出力してください。 下流のツールが解析します。
• 評価に徹し、執筆しないでください。 指摘事項を返してください。文書を書き直したり、修正したり、補完したりしないでください。修正は作成者が行います。
• 単一の評価基準を適用してください。 Step 2 の10項目、つまり作成者が authoring-architecture-doc の Step-7 で適用するのと同じ基準に照らして評価してください。条件を追加したり、独自に厳しい基準を適用したりしないでください。
• 手法ではなく成果を評価してください。 C4／arc42／ATAM／4+1 の枠組みや、図の種類の選択は作成者が用いる手法です。評価するのは、境界が明確に示されているか、決定が関連付けられ追跡可能か、各目標が実現されているかです。「C4を使っていない」「4+1のプロセスビューを描いていない」「ATAMを実施していない」と指摘してはいけません。（ADRの仕組み／NFRの実現／可観測性は cond-4／6／7 の実質的な条件です。手法だけが補助的なものです。）
• ADRの仕組みは重要な要件です（cond. 4）。 決定がリンクされたADRではなく本文に埋め込まれている場合や、承認済みADRが書き換えられている場合は、文体上の問題ではなく、実際の不備です（決定を参照できない／履歴が失われる）。確認にはリンク先のADRファイルが必要です。ファイルがない場合は確認不能と指摘し、事実を捏造してはいけません。
• システムに照らして主張を検証してください（cond. 9）。ただし、グリーンフィールドの例外があります。 システムの現状についての主張は、実際のコード／トポロジー（file:line）で確認するか、unverified としてください。不備を捏造してはいけません。検証対象となるコード／システムがない場合（新規作成または架空の文書）は、一貫性の評価は該当せず、阻止要因にはなりません。
• 誤って修正判定にしないでください。 適用されるすべての条件を満たす文書は、たとえ小規模システム向けの簡潔なものであっても承認してください。実際に存在し、内容が明確な不備がある場合に限り、修正判定にしてください。簡潔なアーキテクチャ文書では、デプロイメントビュー、メッセージング、独立した可観測性セクション、変更履歴を省略しても問題ありません。
• 誤って承認しないでください。 実際の不備があるのに、相手に配慮して承認してはいけません。阻止要因となる不備があれば、revise としてください。
• 文書に指定された上流文書に照らして評価してください。 文書の depends_on セットと、参照されている文書／ADRファイルを基準に評価してください。未作成の上流文書は、決して修正判定の理由にしてはいけません。参照すべき作成済みの上流文書を無視している場合は、妥当な指摘事項です。
• 修正の評価範囲は差分に限定してください。 既存文書に対する変更が提示された場合は、変更差分とその波及（cond-10）を評価してください。変更されていないアーキテクチャを最初から再評価したり、グリーンフィールドの初稿に変更履歴を求めたりしてはいけません。
• 修正判定の指摘はすべて、対応可能な内容にしてください。 不合格となった条件、該当箇所、具体的な修正方法を示してください。

望ましい事項（必要に応じて変更可能）：

• 指摘事項は重大度順に並べ、阻止要因となる不備を先に示してください。
• 各指摘事項に条件番号／名称を記載し、作成者が評価基準と照合できるようにしてください。
• 承認時の補足は少数にとどめ、阻止要因ではないことを明確にしてください。

注意点

• 理解しやすさではなく、網羅性を基準に承認すること。 すべてのセクションがあっても、システムを理解できるとは限りません（分解が曖昧、外部依存先に名前がない、決定事項が本文に埋もれているなど）。読者が「システムを理解し、機能をその中に位置付けられるか」を評価してください。「テンプレートが埋まっているか」ではありません。
• 決定事項が本文に埋め込まれていること。 詳細な「技術選定」セクションがある文書は、網羅的に見えます。しかし、重要な決定事項が、背景や影響をすべて記載した形で本文に貼り付けられ、独立したリンク付き ADR になっていない場合、条件 4 は満たされません（参照できず、後から置き換えられません）。これはアーキテクチャ文書に特有の見落としどころであり、一般的な design-review では見逃されます。
• 承認済み ADR の書き換え。 承認済み ADR を新しい ADR で置き換えずに直接編集すると、決定の履歴が失われます。新しい内容が「より優れている」場合でも、条件 4 の不備です。
• NFR の目標値を言い換えただけの記述。 冗長化やフェイルオーバーの仕組みがなく、PRD の「稼働率 99.9%」をそのまま転記しているのは、実現ではなく言い換えです（条件 6）。
• ADR の仕組み／NFR／可観測性を、持ち込んだ条件として扱うこと。 機能仕様書であれば、これらは新たな条件を持ち込むことになります。しかし、アーキテクチャ文書では審査基準です（条件 4／6／7）。審査を甘くしないでください。
• 架空の文書をコードと照合すること。 ドッグフーディング用／サンプルのアーキテクチャ文書が、実在しないシステムを説明している場合、条件 9 の整合性チェックは該当しません（グリーンフィールドの条項）。「検証できなかった」として不備を指摘するのは誤りです。
• 条件を作り出すこと（最も大きな逸脱）。 基準にない独自要件（「C4 モデルを使うこと／4+1 のプロセスビューを描くこと／ATAM を実施すること」など）を追加すると、審査基準が成果物の基準から逸脱します。手法は結果のみで評価してください。
• 体系的な過剰指摘（誤った修正要求）。 問題を見つけるよう求められたレビュアーは、過剰に修正を求めがちです。条件の不備となるのは、明示された実際の欠陥がある場合だけであり、異なる決定をしていたはずだというだけでは該当しません。
• 小規模なシステムに対する誤った修正要求。 小規模なシステムのアーキテクチャ文書は、適切に短いことがあります。不要なセクションを省略していても（デプロイメントビューがない、メッセージングを使わない、可観測性を分けていない、変更履歴がないなど）、不備ではありません。
• 判定トークンの揺れ。 「承認済み」、「LGTM」、「要修正」、または段落の途中に埋め込まれた判定は解析できません。独立した行に VERDICT: approve|revise をそのまま出力してください。

アンチパターン

• 形式だけの承認。 修正のやり取りを避けるために流し読みして承認すること。本文に埋め込まれた決定事項や、名前のない外部依存先をそのまま通すと、欠陥や構築途中での慌ただしい対応につながります。
• 些細な指摘による修正要求。 文言、図のスタイル、あると望ましい程度の要素を、不備として問題にすること。修正要求の対象は、理解や構築を実際に妨げる場合に限ります。
• 無断の書き換え。 「アーキテクチャを直すほうが簡単だった」――レビュー中に文書を作成すると、成果物の作成と評価の分離が崩れます。
• 条件の作り出し。 基準にない要件（特定のフレームワークや図の種類の指定など）を追加すること。このゲートが防ごうとする主な逸脱です。
• 変更箇所の再レビューで、文書全体を見直すこと。 小さな差分に対して、変更されていないアーキテクチャ全体を再評価すること。差分とその波及影響（条件 10）を、変更規模に応じてレビューしてください。
• 曖昧な判定。 「ほぼ承認ですが……」や、判定を 2 行出すこと。決定は 1 つだけ、トークンも 1 つだけにしてください。

出力

1 つのアーキテクチャ文書と、それにリンクされた ADR ファイルを対象とする、単一のレビュー結果です。

• 判定行は 1 行 — 独立した行に VERDICT: approve または VERDICT: revise をそのまま記載します。
• 指摘事項 — revise の場合、阻害要因となる不備ごとに、対応可能な指摘を 1 件ずつ記載します（満たしていない条件＋該当箇所＋具体的な修正内容）。approve の場合、阻害要因ではない所見は任意です。

抽象的な利用者は、成果物の作成→レビューのループを調整するものです。approve は、アーキテクチャに基づく構築を承認し、revise は、範囲を限定した修正作業のために指摘事項を作成者へ返します。媒体： 現時点で評価対象となる成果物は、テキスト形式の Markdown アーキテクチャ文書、Mermaid 図、およびリンクされた ADR ファイルです。審査基準は媒体に依存しません。

関連項目

• authoring-architecture-doc — ペアの作成側です。このスキルが評価するのと同じ10条件の基準を満たすアーキテクチャドキュメントを作成します。両者を組み合わせることで基準を一元化し、作成とレビューの間にずれが生じないようにします。
• reviewing-technical-design — 1つの機能の技術設計（このアーキテクチャ内での位置づけを示すもの）を対象とする、1段階下のゲートです。対象ドキュメントも基準も異なります。
• PRDレビュースキル — プロダクト要件（何を、なぜ作るか、NFRの目標）を対象とする、1層上のゲートです。対象ドキュメントも基準も異なります。
• design-reviewスキル — 一般的なエンジニアリング設計ドキュメント、RFC、単独のADR、仕様書、計画を対象とするゲートです（主張をコードベースと照合します）。このスキルは、ドキュメントライブラリのアーキテクチャドキュメント成果物と、それにリンクされたADRファイルを専門にレビューします。design-reviewはその成果物をゲートしません。
• 存在する場合のAPI仕様／データモデル — アーキテクチャが構造的に参照する契約です。条件2では、ドキュメントが適切な抽象度を保ち、それらを列挙せずに参照しているかを確認します。
• アーキテクチャドキュメント／ADRテンプレート／コンテンツテンプレートツール — セクションの構成を管理します。このスキルが評価するのは基準に照らした品質であり、構造への準拠ではありません。

段階的な情報開示

• references/architecture-quality-bar.md — 10項目のチェック条件を、条件ごとの合格／不足のシグナルと、実例を使った指摘例とともに詳述しています（境界と関心事の網羅性チェック、抽象度テスト、図の同期チェック、ADRメカニズムのシグナル［埋め込み済みの意思決定＋承認済みADRの書き換え＋インデックスの同期］、ドライバーと代替案のテスト、ターゲットごとの実現性と測定可能なシナリオのシグナル、横断的関心事／可観測性のシグナル、ASRの網羅性チェック、現実との照合＋グリーンフィールドのシグナル、差分範囲に限定した修正のシグナル）。境界的な条件について、より明確な合格／不足の判断が必要な場合に読み込みます。
• references/sources.md — レビューメソッドの調査資料の出典（C4／arc42／ISO 42010、ADRの実践、SEIの品質属性シナリオ＋ATAM、レジリエンスパターン、継続的なアーキテクチャドキュメント）。

本文の上限

• description は1,024文字以下（agentskills.ioの上限）。一覧では、descriptionとwhen_to_useの合計が1,536文字で切り詰められます。
• 本文は約500行／5,000トークン（目安。品質を優先し、700行／7,000トークンを継続的に超える場合は警告してください）で、すべてのターンでコンテキストに保持されます。
• 参照ファイルごとに、10,000トークン超で警告、25,000トークン超でエラー。参照ファイル全体では、25,000トークン超で警告、50,000トークン超でエラーです。