design-review

概要

design-review は、設計ドキュメント（仕様書、設計書、RFC、ADR、実装計画）に対して、承認前に批判的なレビューを行います。後になって（または本番環境で）明らかになりがちな、繰り返し見られる抜け漏れを洗い出します。たとえば、初期設定や所有者が不明確、誤解を招く名前、スケールへの考慮不足、明示されていない前提、コードと一致しない主張、障害時の処理の欠如、セキュリティ上の攻撃対象領域の未検証、不当な複雑さ、不完全さなどです。重要なのは、文章をそのまま信頼するのではなく、実際のコードベースに照らして主張を検証し、すべての指摘に根拠を示す file:line を引用する点です。指摘のレポートと判定を作成しますが、ドキュメントの編集も承認もしません。それは人間のレビュアーと作成者に委ねられます。設計を書いてから承認するまでのゲートとして使用してください。

有効にするタイミング

• ✅ 仕様書／設計書／RFC／ADR／実装計画を承認する前に、まず抜け漏れを見つけたい場合。
• ✅ 作成者が、設計を承認に向けて提示する前に批判的なレビューを受けたい場合。
• ✅ 自動化されたワークフローで、設計ドキュメントに対する一貫した承認前レビューの手順が必要な場合。

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

• 成果物が コード／差分 の場合 — コードレビューのスキル（requesting-code-review／code-review）を使います。このスキルは 設計文書 をレビューするもので、実装は対象ではありません。
• 文書を 作成している 場合 — 内容作成／テンプレートのスキルを使って下書きを作成します。design-review は既存の草稿のみをレビューします。
• 文書が doc-library の technical-design 成果物 の場合（ドキュメントライブラリの技術設計成果物。フロントマターの template: technical-design によって 正式に識別 します（フロントマターがない場合は # Technical Design: の見出しを代替シグナルとして使用します。スタンプのない、単に「Technical Design」というタイトルを付けた一般的な文書は、引き続きこちらの対象です））— 専用レビュアーの reviewing-technical-design を使います。このレビュアーは TDD 固有の実装可能性基準（要件のトレース、重複ではなく参照すること、可観測性、テスト、ロールアウト、差分スコープでの修正）を確認します。design-review は引き続き、一般的な設計文書、RFC、ADR、仕様、計画を対象とします。doc-library の TDD 成果物のみが対象外です。
• 文書が doc-library の architecture-doc 成果物 の場合（システム全体のアーキテクチャ文書と、リンクされた ADR ファイル。フロントマターの template: architecture-doc によって 正式に識別 します（フロントマターがない場合は # Architecture: の見出しを代替シグナルとして使用します。スタンプのない、単に「Architecture」というタイトルを付けた一般的な文書は、引き続きこちらの対象です））— 専用レビュアーの reviewing-architecture-doc を使います。このレビュアーはアーキテクチャ品質の基準（境界と関心事、構造と抽象度、図との同期、ADR の仕組み、NFR の実現、横断的関心事、ASR の網羅性、差分スコープでの修正）を確認します。境界（重要）： 対象外となるのは architecture-doc-library の成果物と、それにリンクされた ADR ファイルのみです。architecture-doc 成果物の一部ではない 単独のアドホックな ADR または RFC は、引き続き design-review の対象です。
• 文書が doc-library の data-model 成果物 の場合（永続化／ドメインモデル。エンティティ、キー、リレーションシップ、インデックス、正規化、ライフサイクル。フロントマターの template: data-model によって 正式に識別 します（フロントマターがない場合は # Data Model の見出しを代替シグナルとして使用します。スタンプのない、単に「Data Model」というタイトルを付けた一般的な文書は、引き続きこちらの対象です））— 専用レビュアーの reviewing-data-model を使います。このレビュアーは整合性とクエリ可能性の基準（型とキーが定義されたエンティティ、カーディナリティと参照整合性ルール、アクセスパターンに基づくインデックス、正規化とパラダイムの選択、ライフサイクル／移行、図と表の同期、API 仕様に対する一方向性、差分スコープでの修正）を確認します。モデルが参照する api-spec／feature-spec は、それぞれのレビュアーの対象です。対象外となるのは data-model 成果物のみです。
• 文書が doc-library の api-spec 成果物 の場合（エンジニアリング API のワイヤーコントラクト。操作、リクエスト／レスポンスのスキーマ、認証、エラーモデル、ページネーション、バージョニング、例。フロントマターの template: api-spec によって 正式に識別 します（フロントマターがない場合は # API Specification の見出しを代替シグナルとして使用します。スタンプのない、単に「API Specification」というタイトルを付けた一般的な文書は、引き続きこちらの対象です））— 専用レビュアーの reviewing-api-spec を使います。このレビュアーはコントラクトの完全性基準（すべての操作について両方向の型とステータスコードが定義されていること、エラーモデルが完全であること、共通型が data-model を参照していること、操作ごとの認可、ページネーションとタイブレーカー、スキーマと一致する例、API リファレンスに対する一方向性、差分スコープでの修正）を確認します。スタイルには依存しません（REST／GraphQL／gRPC）。参照先の data-model／feature-spec と、下流の api-reference は、それぞれのレビュアーの対象です。対象外となるのは api-spec 成果物のみです。
• テキストが 1 行のメモ、または評価対象となる設計を含まない非構造化の文章である場合。

ワークフロー

ステップ 1：入力を受け取る

• 必須： レビュー対象のドキュメントへのパス。
• 任意： コードベース内の明示的な参照先（設計が関わるディレクトリ／モジュール）。省略された場合は、ドキュメント内の参照（ファイルパス、コマンド／モジュール名、引用されているリンク）から検証対象のモジュールを推定します。
• 任意： 出力形式の希望 — インライン（デフォルト）またはドキュメントの隣に review.md を作成。

ステップ 2：ドキュメントをすべて読む

どの部分も評価する前に、ドキュメント全体を読みます。既存の動作に関する主張、名前が挙げられているコマンド／ファイル／動詞、入力、規模に関する前提、参照されているコードパスを確認します。これらはステップ 3～4 で役立ちます。

ステップ 3：カテゴリ別にギャップを探す

以下の評価基準に照らしてドキュメントを確認します。このリストは拡張可能です。新たなギャップの種類が見つかった場合はカテゴリを追加し、コアカテゴリは削除しないでください。

カテゴリ	確認すること
ブートストラップと所有者	設計が使用するすべての入力について、誰が／何が、どの順序で作成するか。セットアップの順序は記載されていますか？
名前の妥当性	各コマンド／ファイル／動詞／フィールドは、名前から想定される動作を、想定される順序で行いますか？誤解を招く名前はありませんか？
規模と制限	10 倍／1000 倍になった場合、どうなりますか？アイテム単位とコレクション全体の操作、並行処理、際限のない増加について確認します。
隠れた前提	単数か複数か、1 つか多数か、デフォルト、「明らかに」などの前提は、推測に任せず明示されていますか？
リリース済みコードとの整合性	既存の動作、パス、インターフェースに関する記述は、コードの実際の動作と一致していますか？（ステップ 4 で検証）
冪等性／失敗／再実行	再実行、一部失敗、クラッシュ、再試行時にどうなりますか？操作を安全に繰り返せますか？
セキュリティの範囲	新たな認可／認証、シークレットの取り扱い、外部呼び出し、破壊的な操作、信頼できない入力はありますか？
必要性とより簡単な代替案	そもそもこれを構築する必要がありますか？設計で見落とされている、実質的にもっと簡単な方法はありますか？
完全性と明確さ	課題／目標／対象外／代替案／リスクは記載されていますか？初めて読む人にも理解できますか？詳細の粒度は適切ですか？

計画の観点 — レビュー対象のドキュメントが実装計画／プロジェクト計画の場合は、追加で以下を確認します（上記 9 カテゴリも引き続き適用されます）。

計画の確認項目	確認すること
タスクの粒度	各リーフタスクは、テスト可能な完了確認が 1 つある単一の関心事であり、アトミックですか？関心事をまとめたタスク（「〜して、〜する」）や、完了確認が明記されていないタスクを指摘します。
依存関係の順序／DAG	depends_on／ブロッキングエッジは有効な DAG（循環なし）を形成し、実行順序はそれに従っていますか？
付随する仕様に対する網羅性	仕様のスコープ項目すべてが 1 つ以上のタスクに対応し、スコープ外の作業を実装するタスクはありませんか？
完了条件のテスト可能性	各フェーズ／タスクの「完了」は、主観的な記述ではなく、テスト可能な単一の記述（コマンド／観察結果）ですか？

ステップ 4：コードと照合して主張を検証する（必須）

既存の動作、パス、インターフェースについて述べる指摘を行う場合は、参照されているモジュールを読み取る／grep して確認し、file:line 形式で引用します。これが、根拠のあるレビューと推測との違いです。

• 不整合を指摘する場合は、実際のコードを引用するか示す必要があります（path:line）。
• 疑わしいものの確認できないギャップには、明示的に unverified と付けます。事実として断定してはいけません（これは「捏造しない」ことを徹底するためです）。
• グリーンフィールド： ドキュメントが新しい動作を説明しており、確認できる既存コードがない場合、整合性カテゴリは N/A です。検証対象のコードが存在しないこと自体は、決してブロッカーではありません。
• 作業範囲を限定する： 検証するのはドキュメントが参照するモジュールだけです。ツリー全体を走査しないでください。

ステップ 5：指摘事項をまとめる

各指摘事項：

- [severity] <category> — <location in the doc>
  Gap: <what is missing/wrong/unstated>
  Fix: <concrete suggested resolution>
  Evidence: <path:line> | unverified

重大度： blocker（承認前に必ず解決 — 設計またはその前提を破綻させる誤りや欠落） · important（解決すべき — 致命的ではない実際のギャップ） · minor（修正すると望ましい）。

ステップ 6：判定

最後に 1 行で、ready-for-approval（ブロッカーなし）または has-blockers（最初にブロッカー、次に重要事項、最後に軽微な事項を列挙）を記載します。この判定は人間への推奨であり、承認ではありません。

ステップ 7（任意）：大規模またはリスクの高いドキュメントの独立レビュー

大規模または重要度の高いドキュメントでは、同じ評価基準を与えた予備知識のない新しいレビュアー（サブエージェント）にレビューを依頼し、その指摘を統合します（重複は除外）。サブエージェントへの依頼が利用できない場合は、代替として 2 回目のインラインレビューを行い、その旨を記載します。これは新たな視点を得る価値を反映したもので、任意であり必須ではありません。

ステップ 8：出力

• デフォルトはインライン： 指摘事項と判定を依頼者に返します。
• 希望がある場合： ドキュメントと同じ場所に review.md を作成します。
• ドキュメントを編集しないでください。承認もしないでください。 推奨を提示し、著者が修正し、人間が判断します。

ルール

厳守するルール（決して違反しないこと）：

• 主張する前に検証する（捏造しない）。 既存の挙動に関する主張は、コードを確認し file:line の引用を付けるか、unverified と明記します。ギャップを決してでっち上げないでください。
• レビューのみ。 ドキュメントを編集したり、承認または却下したりしないでください。出力するのは指摘事項と判定の推奨であり、判断は人間が行い、修正は著者が担当します。
• 新規開発をギャップと見なさない。 検証するコードが存在しないこと自体は、決してブロッカーではありません。
• 検証の範囲は、ドキュメントが参照するモジュールに限定します。リポジトリ全体をスキャンしないでください。
• 重大度を正直に評価する。 blocker は、承認前に本当に修正が必要なものに限ります。重大度を誇張しないでください。

推奨事項（上書き可能）：

• カテゴリの評価基準は拡張可能です。繰り返し発生する新たなギャップの種類が見つかったら、カテゴリを追加してください。
• ブロッカーを最初に提示し、レポートを見やすく保ちます。軽微な指摘が多い場合はまとめてください。
• 漠然としたコメントより、指摘ごとに具体的な修正案を 1 つ示すことを優先します。

注意点

• 本文の説明を鵜呑みにする。 仕様書では、コードに存在しない挙動を自信たっぷりに説明していることがあります。価値のすべてはステップ 4、つまりコードとの照合にあります。それを省略したレビューは、単なる意見です。
• 新規開発を誤って問題視する。 新しく作られたシステムのドキュメントには、照合するコードが存在しません。「X を検証できなかった」ことを問題として指摘するのは誤りです。一貫性の評価を該当なしとしてください。
• リポジトリ全体のスキャン。 コードベース全体を使って検証しようとすると、時間がかかり、ノイズも増えます。参照されているモジュールに範囲を限定してください。
• 過剰な指摘。 あらゆる細かな点をブロッカーとして列挙すると、本当に重要な問題が埋もれます。重大度を適切に扱うことで、判定の意味を保てます。
• 詳細さを完全性と取り違える。 詳細が多いことは、設計が完全であることと同じではありません。逆に、簡潔でも完全なら問題ありません。単語数ではなく、決定事項が示されているかを評価してください。

アンチパターン

• 確認せずに「コードと一致しない可能性があります」と言う。 捏造したギャップや、未検証のギャップを事実として述べることは禁止です。検証するか、unverified と明記してください。
• 「ついでにドキュメントを修正しておきます。」 ドキュメントの編集は対象外です。レビューのみ行います。
• 「問題なさそうです。」 評価基準を適用したり主張を検証したりせず、ざっと目を通して承認するのは、形だけの確認です。
• 「承認しておきます。」 結果を決めることは禁止です。このスキルが提示するのは推奨であり、承認するのは人間です。
• 「念のためリポジトリ全体を grep します。」 範囲を限定しない検証です。参照されているモジュール内に留めてください。

出力

指摘レポート（デフォルトはインライン、review.md は任意）：ステップ 5 の形式で重大度順に 0 件以上の指摘を記載し、その後に 1 行の ready-for-approval | has-blockers 判定を記載します。この成果物は、承認ゲートでドキュメントの著者と承認者である人間が確認する推奨事項であり、決して承認ではなく、編集済みのドキュメントでもありません。

関連項目

• requesting-code-review / code-review — コード／差分を対象とする類似の機能です。design-review は、コードが存在する前に実行する、設計ドキュメント向けの機能です。
• コンテンツ／テンプレートのスキル — このスキルがレビューするドキュメントを作成します（作成とレビューは別の作業です）。
• reviewing-technical-design — doc-library の technical-design 成果物（TDD）専用のレビュアーです。この成果物はこのスキルの対象外です。template: technical-design ドキュメントはそちらに振り分けてください。design-review は汎用的な設計ドキュメント、RFC、ADR、仕様書、計画書を引き続き扱います。
• reviewing-architecture-doc — doc-library の architecture-doc 成果物（システム全体のアーキテクチャドキュメントと、それにリンクされた ADR ファイル）専用のレビュアーです。この成果物もこのスキルの対象外です。template: architecture-doc ドキュメントはそちらに振り分けてください。architecture-doc 成果物の一部ではない、単独のアドホックな ADR／RFC は引き続き design-review で扱います。
• reviewing-data-model — doc-library の data-model 成果物（永続化／ドメインモデル）専用のレビュアーです。この成果物もこのスキルの対象外です。template: data-model ドキュメントはそちらに振り分けてください。design-review は汎用的な設計ドキュメント、RFC、ADR、仕様書、計画書を引き続き扱います。
• reviewing-api-spec — doc-library の api-spec 成果物（エンジニアリング向け API ワイヤーコントラクト）専用のレビュアーです。この成果物もこのスキルの対象外です。template: api-spec ドキュメントはそちらに振り分けてください。design-review は汎用的な設計ドキュメント、RFC、ADR、仕様書、計画書を引き続き扱います。
• 仕様 → 計画 → 実装という規律に沿って、仕様および計画の承認前ゲートとして機能します。

段階的な情報開示

• references/sources.md — 評価基準の調査根拠です。各カテゴリの出典を監査する場合にのみ読み込んでください。

このスキルには scripts/ や assets/ は含まれていません。Read / Grep / Glob と（任意の）サブエージェントのディスパッチで動作します。

本文の上限

• description は 1,024 文字以下（agentskills.io の上限）。一覧表示では description と when_to_use の合計が 1,536 文字で切り詰められます。
• 本文は約 500 行／5,000 トークン以下です。

変更履歴

• 2.4.0 (2026-06-15) — 対象範囲の切り分け：doc-library の api-spec 成果物は、専用レビュアー reviewing-api-spec に振り分けられるようになりました。参照先の data-model／feature-spec と、後続の api-reference は、それぞれ専用のレビュアーが引き続き扱います。追加のみの変更です。9 つのギャップカテゴリと計画の観点に変更はありません。（作成のみを対象とした切り分けの 4 件目かつ最後の変更です。doc-library のすべての種類に、専用のレビュー側の対応スキルが用意されました。）
• 2.3.0 (2026-06-15) — 対象範囲の切り分け：doc-library の data-model 成果物は、専用レビュアー reviewing-data-model に振り分けられるようになりました。参照先の api-spec／feature-spec は、それぞれ専用のレビュアーが引き続き扱います。追加のみの変更です。9 つのギャップカテゴリと計画の観点に変更はありません。
• 2.2.0 (2026-06-14) — 対象範囲の切り分け：doc-library の architecture-doc 成果物と、リンクされた ADR ファイルは、専用レビュアー reviewing-architecture-doc に振り分けられるようになりました。単独のアドホックな ADR／RFC は引き続きここで扱います。追加のみの変更です。9 つのギャップカテゴリと計画の観点に変更はありません。
• 2.1.0 (2026-06-14) — 対象範囲の切り分け：doc-library の technical-design 成果物は、専用レビュアー reviewing-technical-design に振り分けられるようになりました。design-review は汎用的な設計ドキュメント、RFC、ADR、仕様書、計画書を引き続き扱います。追加のみの変更です。9 つのギャップカテゴリと計画の観点に変更はありません。
• 2.0.0 (2026-06-01) — 初回のレビュー済みリリース。