reviewing-technical-design

reviewing-technical-design — SKILL.md

バリアント： standard · 使用する場面： 完成した技術設計書を受け入れゲートとして評価する場合 — エンジニアが設計を再導出せずに実装できるかを確認し、実行可能な指摘とともに VERDICT: approve|revise を出力します。グリーンフィールド、または修正（差分の範囲に限定）。

概要

このスキルは、技術設計の作成と評価を行うペアのうち、レビューを担います。既存システム内で1つの機能をどのように構築するかを示す、機能仕様書の下位に位置する文書である、完成した技術設計書（TDD）を持つレビュアーが読み込み、次の1つの問いに照らしてその文書を評価します。エンジニアは設計を再導出せずにこの機能を実装できるか、また、選ばれたアプローチは実際の代替案と比較して正当化されているか？ 固定の実装可能性チェックリスト（11項目）（TDD の作成者が目指す基準と同じです — authoring-technical-design の Step-5 — これにより、作成時とレビュー時の基準がずれません）を適用し、機械で解析可能な単一の判定と、作成者が1回の改訂で対応できる指摘を出力します。これは受け入れゲートです。設計の作成、修正、書き換えは行いません。評価して指摘を返し、作成者が改訂します。

基準は作成者と一元化されています。作成者の手法 — FMEA による故障モード分析、RTM トレースマトリクス、C4 の抽象度の捉え方、シーケンス図とフロー図の選択、擬似コードの形式 — は、レビュアーが成果に基づいて評価するための補助です（すべての決定が追跡可能か？障害が処理されているか？シグナルに名前が付いているか？）。要求すべき条件ではありません。ただし、境界には注意してください。 ロールアウト、オブザーバビリティ、テストは TDD の実質的かつ重要な条件（cond-7/8/9）です。機能仕様書に対するロールアウト要求のように、ここで「作り出された」条件ではありません。補助にとどまるのは手法（FMEA/RTM/C4/図の選択）であり、成果（名前付きシグナル、追跡された決定、ロールバックのトリガー）ではありません。

有効化する場面

• エンジニアが文書に基づいて実装する前に、完成した技術設計書について承認または修正の判断が必要な場合。
• 作成者が作成した TDD を独立したレビュアー／ゲートとして評価する場合。
• 以前の revise 判定を受けて改訂された TDD を再評価する場合。
• 修正（承認済みの TDD ＋変更要求）を差分の範囲に限定してレビューする場合（cond-11）。

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

• TDD の作成または修復 → authoring-technical-design を使用してください。このスキルは設計を作成しません。
• 上流の PRD または機能仕様書（何を／なぜ；各機能の振る舞い）のレビュー → PRD レビュー／機能仕様レビューのスキルを使用してください。このゲートが評価するのは、1つ下の階層にある機能の構築方法です。
• api-spec または data-model自体（ワイヤー契約／永続化されるスキーマ）のレビュー → これらは TDD が参照する独立した文書であり、それぞれに独自のゲートがあります。
• 汎用またはアドホックなエンジニアリング設計書、RFC、ADR、仕様書、計画書（ドキュメントライブラリの technical-design 成果物として作成されたものではない文書）のレビュー → これらすべての種類について、コードベースと照合しながら設計上の主張を検証する design-review を使用してください。このゲートの対象は、ドキュメントライブラリの技術設計成果物です。これは template: technical-design のフロントマターによって確実に識別します。フロントマターがない場合は、# Technical Design: という見出しを代替の手掛かりとしてのみ使用します（スタンプがなく、タイトルに「Technical Design」と記載されているだけの汎用文書は、引き続き design-review の対象です）。
• テンプレートやセクションへの準拠確認 → これはテンプレートに関する確認です。このスキルは、すべての見出しがあるかではなく、基準に照らした品質を評価します。

ワークフロー

Step 1: 新鮮で独立した視点で設計全体を読む

著者の説明に引きずられず、初めて読むつもりで TDD を最初から最後まで読みます。次のステップ（実装）へのゲートキーパーとして、設計で決着しているべき内容を改めて導き出さなければ、設計どおりに機能を構築できないことを示す場合に限り、指摘に重みがあります。上流の機能仕様と PRD（および TDD が参照するアーキテクチャドキュメント／API 仕様／データモデル）を手元に置いてください。Step 2 の最初の条件では設計と要件の双方向の整合性を確認し、cond-4 では参照先の契約が重複していないことを確認します。これは amend ですか？ 既存の TDD に対する変更依頼／差分を渡された場合は、差分に絞った手順を実行します（cond-11 が有効。変更された決定事項とその波及範囲にレビューを限定します）。グリーンフィールドでの初回構築では変更依頼がないため、cond-11 は該当しません。

Step 2: 実装可能性チェックリストを実行する — 各条件を判定する

以下の各条件について、合格またはギャップを判定します。条件が不合格となるのは、実際に存在し、具体的に特定できる不備がある場合だけです。「自分なら別の設計にした」という理由はギャップではありません。各ギャップについて、正確な箇所と不足している内容を記録します（Step 4 で実行可能な指摘にします）。条件が唯一の判定基準です。独自の基準を追加しないでください。

1. 要件トレースが完全かつ双方向であること。 機能が満たすべきすべての要件（PRD の目標／機能仕様の基準／制約）に、それを満たす設計要素があり、重要な設計判断のすべてが要件にさかのぼれることを確認します。両方向を確認してください。要件に結び付かない設計判断はスコープクリープ／過剰な作り込みであり、設計のない要件はカバレッジの欠落です。孤立した設計判断、未対応の要件、または明示されていない／再構成できないトレーサビリティがあれば、ギャップです。（縮退しない基本条件 — 規模にかかわらず、どの要件にも応えない設計判断は問題です。）
2. 単一の機能に範囲を絞り、適切な抽象度であること。 既存アーキテクチャ内の単一の機能／コンポーネントを設計します。システム全体の構造は再設計せず、参照します。TDD がアーキテクチャドキュメントを参照する代わりに、トポロジー／データストア／サービス境界を再決定している（アーキテクチャ作業の抽象度が不適切）場合は、ギャップです。（縮退しない基本条件。）
3. アプローチと分解が実装可能であること。 アプローチの概要を簡潔に示します。各コンポーネント／モジュールには、責務を一つだけ割り当て、連携相手を示し、実装できるだけの具体性を持たせます。主要な制御フローとデータフローを、互いに一致する図と番号付きの説明で示します。巨大な単一コンポーネント、機能名だけが付いた箱、図のないフロー、または説明文と矛盾する図があれば、ギャップです。（縮退：小規模な機能では、コンポーネントの数が少なく、フローも短くなります。）
4. 重複ではなく参照（SSOT）を行うこと。 api-spec／data-model／architecture-doc がすでに管理しているインターフェース／スキーマ／トポロジーは、そのドキュメントを参照し、差分だけを記載します。本文に重複して記載しません。管理元ドキュメントに記載されているエンドポイント一覧、テーブル DDL、サービスのトポロジーをTDDに貼り付けている場合は、将来の不整合を必然的に招くため、ギャップです。（縮退：管理対象の契約に触れない機能には参照対象がありません。これはギャップではありません。）
5. 実質的な代替案を1つ以上示し、選択基準を明記すること。 有能なエンジニアが実際に選択し得る、形だけではない代替案を少なくとも1つ示し、トレードオフを比較したうえで、選択を決めた判断基準を明記します。選択肢が1つだけの形式的な比較、藁人形のような代替案（「何もしない／すべて書き直す」）、または判断基準なしに「最善の案を選んだ」と断言している場合は、ギャップです。（縮退しない基本条件 — 規模にかかわらず、トレードオフを検討する原則は適用されます。）
6. 障害モードと横断的な堅牢性に対処すること。 重大な障害（不正な入力、依存先の障害／タイムアウト、部分的な障害）を列挙し、それぞれについて検知方法、対処／復旧方法、ユーザーから見える影響を示します。該当する場合は、並行処理／順序／冪等性に関する方針を明記し、機能に関係するセキュリティ／スケール／プライバシーの観点にも対処します。正常系だけを扱う設計、対処方法のない障害の記載、または機能に明らかに関係するセキュリティ／データ面の未対処があれば、ギャップです。（縮退：単純な機能は障害の範囲が狭く、セキュリティ／プライバシー／並行処理の観点がない場合もあります。項目が少ないのは問題ありません。障害に対処方法が伴うこと自体は縮退しない基本条件です。）
7. 可観測性に対処すること。 機能が出力／監視する稼働状況と障害のシグナル（成功／エラーメトリクス、主要なログ／トレース、主要な障害モードに対するアラート）を明記します。これらのシグナルはロールバックのトリガーにもなります。本番環境に影響する機能で「ログは後で追加する」としている場合や、ロールバック（条件9）のトリガーを裏付けるシグナルがない場合は、ギャップです。（縮退：単純な内部ヘルパーでは簡潔にできます。軽量で構いませんが、必要な場面で欠けているのは問題です。）
8. テストに対処すること。 検証方法をテスト可能な形で明記します。機能に応じたユニット／統合／E2E の各レベル、条件6の障害ケース、および機能が公開する契約がある場合は契約への準拠を含めます。受け入れ基準を繰り返すのではなく、機能仕様の受け入れ基準を参照します。「テストします」だけの記述、障害ケースを省いたテスト戦略、または公開する契約に対する準拠チェックがない場合は、ギャップです。（縮退：単純な機能はユニットテストのみでも構いません。公開する契約がなければ、準拠チェックも不要です。）
9. ロールアウト／移行／ロールバックに対処すること。 段階的な展開／フィーチャーフラグ／カナリアリリースなど、展開方法を示します。データ／契約に変更がある場合は、移行方法と後方互換性に関する方針を示します。条件7のシグナルに結び付いた測定可能なトリガーを含むロールバック計画を示します（「問題がありそうならロールバックする」では不十分です）。リスクのある変更で一斉切り替えを前提としている場合、データ／契約の変更に移行方法がない場合、または測定可能なトリガーのないロールバック計画は、ギャップです。（縮退：内部向けの追加機能で、展開が単純かつ移行が不要なら、簡潔で構いません。）
10. 前提を明示し、根拠に基づかせ、捏造しないこと。 実際に不明な点は、確定事項のように取り繕わず、前提／未解決の質問として示します。設計には、この機能固有の事情と実際の周辺システムを反映させます。完全に見せるために、アプローチ／制限／インターフェースを作り上げてはいけません。設計が誤った完全性を装っている場合や、上流の情報または調査に根拠がないと思われる制限／インターフェース／アプローチを断言している場合は、ギャップです。（縮退しない基本条件。）
11. （改訂時のみ）差分の範囲を明確にし、影響波及に漏れがなく、バージョンを更新すること。 既存のTDDに対する変更をレビューする場合、差分について条件1～10を満たすこと、変更した設計判断が要件に結び付いていること（または上流のPRD／機能仕様の改訂が必要であると明示していること）、SSOTへの影響波及に対処していること（契約を変更した場合、管理元のapi-spec／data-modelの改訂に加え、下流の実装／テスト計画／運用手順書の参照先更新も明記すること）、ドキュメント自体のバージョンを更新し、変更履歴（誰が／いつ／何を／なぜ）を記載すること、置き換えられた設計判断に印を付け、黙って削除しないことが必要です。差分の範囲が不明確な場合、トレースが途切れている場合、SSOTへの影響波及が明示されていない場合、変更履歴がない場合、または設計判断を黙って削除した場合は、ギャップです。（縮退：グリーンフィールドでの初回構築では、この条件は該当しません。変更のないTDDを最初からすべて再レビューしてはならず、初稿に変更履歴を求めてはなりません。） 比例性。 「実装者が設計を再導出せずに実装できること」の基準は、機能の規模に応じて変わります。小規模な機能であれば、不要な項目を省略しても問題ありません。たとえば、並行処理がなければ並行処理に関する方針は不要で、永続化するものがなければ移行は不要です。単純な内部ヘルパーなら軽量な可観測性で十分で、外部に公開する契約がなければ適合性テストは不要です。初稿であれば変更履歴も不要です。判断するのは、文量やテンプレートの各セクションが存在するかではなく、意思決定が十分に完結しているかです。該当するすべての条件を満たす、小規模で完全な設計は合格です。簡潔だからといって、不足を作り出してはいけません。

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

• approve — 該当するすべての条件を満たしています。エンジニアは設計を再導出せずに、設計どおりにこの機能を実装でき、選択したアプローチにも根拠があります。文体上の改善点を思いついたとしても承認してください。基準は完璧さではなく、実装可能性です。
• revise — 実装を妨げる、実際に特定できる不足が1つ以上あります（対応する参照先がない決定、範囲を誤った再設計、本文に埋め込まれた api-spec の契約、比較検討されていない単一の選択肢、対処方法のない障害、本番機能に対する可観測性の欠如、障害ケースを網羅していない戦略、測定可能な発動条件のないロールバック、範囲が定まっていない、または影響範囲の整合性が崩れている修正など）。

努力を示したり、あると望ましい項目を求めたりするために、修正を要求してはいけません。条件は満たされているか、満たされていないかのどちらかです。

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

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

VERDICT: approve

続く行に指摘を列挙します。revise の場合、各指摘はすべて実行可能なものでなければなりません。つまり、満たされていない条件、正確な場所、修正方法を示し、著者が一度の修正で解決できるようにしてください。approve の場合、指摘は省略可能な、承認を妨げない補足事項です。修正が必要だと受け取られるような書き方は避けてください。

適切な指摘では、不足点と修正方法を明確にします。

revise — 重複記載せず参照する（条件 4）、§5 インターフェース：api-spec にある GET /reports エンドポイント一覧（パラメーター、レスポンススキーマ）がすべて複製されています。修正方法：api-spec §Reports を参照し、この機能での差分（新しい format=csv パラメーター）のみを記載して、契約の唯一の情報源を維持してください。

悪い指摘は曖昧で、実行に移せません。

インターフェースのセクションは、もう少し整理できます。 (どの契約でしょうか。なぜ基準を満たさないのでしょうか。どう修正すればよいのでしょうか。)

ルール

厳守事項（絶対に違反しないこと）：

• 判定行を必ず1行だけ出力してください。VERDICT: approve または VERDICT: revise のいずれかを、その行にほかの文字を加えずに出力してください。 後続のツールがこれを解析します。
• 判定に徹し、作成はしないでください。 指摘事項を返してください。設計を書き換えたり、修正したり、内容を補ったりしないでください。修正は作成者が行います。
• 単一の評価基準を適用してください。 ステップ2の11項目の条件（作成者が authoring-technical-design のステップ5で用いるものと同じ基準）に照らして評価してください。条件を追加したり、独自のより厳しい基準を適用したりしないでください。
• 手法の使用ではなく、その成果を評価してください。 FMEA、RTMマトリクス、C4の抽象度に関する用語、シーケンス図とフロー図の選択、疑似コードの形式は、作成者が用いる手法です。判断の根拠が追跡されているか、障害に対処しているか、シグナルが明示されているかを評価してください。「FMEAを使っていない／RTMを作成していない／シーケンス図を使っていない」と指摘してはいけません。（ロールアウト、可観測性、テストの成果は、cond-7/8/9の実際の条件です。手法だけが補助にすぎません。）
• 誤って revise と判定しないでください。 適用されるすべての条件を満たす設計は、小規模機能の簡素な設計であっても承認してください。実在する、具体的な不足がある場合にのみ修正を求めてください。小規模機能であれば、移行、並行処理、独立した可観測性のセクション、変更履歴がなくても正当です。
• 誤って approve と判定しないでください。 相手に合わせるために、実際の不足を見過ごして承認してはいけません。ブロッキングとなる不足があれば revise としてください。
• 対処されていない障害は不足です（cond. 6）。 ビルダーに復旧方法を考えさせてはいけません。
• 参照して重複を避けることは重要です（cond. 4）。 別のドキュメントが管理する契約を本文に複製するのは、単なるスタイル上の問題ではなく、実際の不足（ドリフト）です。
• ドキュメントに与えられた上流資料に照らして評価してください。 TDDは、depends_on に指定された資料と、参照しているドキュメントに照らして評価してください。作成されていない上流資料は、決して修正を求める理由にはなりません。参照すべき作成済みの上流資料をTDDが無視している場合は、妥当な指摘となります。
• 修正は変更差分の範囲に限定してください。 既存のTDDに対する変更が提示された場合は、変更差分とその波及影響（cond-11）をレビューしてください。変更されていない設計全体を再レビューしたり、新規作成の初稿に変更履歴を求めたりしてはいけません。
• revise の指摘はすべて、実行可能な内容にしてください。 不合格となった条件、該当箇所、具体的な修正内容を示してください。

推奨事項（必要に応じて変更可能）：

• 指摘事項は重大度順に並べ、ブロッキングとなる不足を先に記載してください。
• 各指摘に条件番号または条件名を記載し、作成者が基準に照らして確認できるようにしてください。
• 承認時の注記は少数にとどめ、ブロッキングではないことを明確にしてください。

注意点

• 実装可能性ではなく、項目がそろっているかで承認する。 すべてのセクションがそろっていても、機能を実装できないことがあります（分解が曖昧、失敗への対処がない、インライン化された契約が陳腐化するなど）。「テンプレートが埋まっているか」ではなく、「設計を再導出せずに機能を実装できるか」で判断してください。
• 列挙されているだけで対処されていない失敗。 不正な入力、タイムアウト、部分的な失敗を「列挙」した設計は、徹底しているように見えます。しかし、それぞれについて検出と対処／復旧を明示していなければ、実装の詳細はまだ不足しています（条件 6）。
• 形だけの代替案を見過ごす。 「代替案：何もしない」は実際のトレードオフではありません。条件 5 で必要なのは、有能なエンジニアが選んだ可能性のある真の選択肢と、それを採用しなかった判断基準です。
• ロールアウト／オブザーバビリティ／テストを、勝手に追加した条件として扱う。 機能仕様書でロールアウトを求めるのは条件の創作ですが、TDDではこれらは基準です（条件 7／8／9）。機能仕様書レビュー担当者の姿勢を誤って持ち込んで、これらのレビューが不十分にならないようにしてください。
• 条件を創作する（逸脱の主因）。 基準にない独自の要件（「FMEA を使うこと／RTM マトリックスを作成すること／フローチャートではなくシーケンス図を使うこと」など）を追加すると、レビュー基準が成果物の基準から逸脱します。手法は、結果だけで評価してください。
• 体系的な過剰指摘（誤った修正判定）。 問題を探すよう求められたレビュー担当者は、過剰に修正を求めがちです。条件の不足といえるのは、明確に特定できる実際の欠陥がある場合だけであり、自分なら別の判断をしたというだけでは不足ではありません。
• 小規模な機能を誤って修正判定する。 小規模な機能の TDD が短いのは適切です。不要なセクションをまとめていること（移行なし、並行処理なし、独立したオブザーバビリティなし、変更履歴なし）は不足ではありません。
• 機能仕様書の判定や設計レビューと混同する。 TDD では、機能をどう構築するかを評価します。これは機能仕様書の振る舞いより一段下の層にあたり、コードベースに照らして記述内容を検証することで一般的な設計ドキュメント／RFC／ADR／仕様書／計画書を審査する design-review とは別のものです。このゲートは、ドキュメントライブラリにある技術設計成果物を専任でレビューします。
• 判定トークンの逸脱。 「Approved」「LGTM」「needs work」や、段落の途中に埋め込まれた判定は解析できません。VERDICT: approve|revise を、そのまま単独の行に出力してください。

アンチパターン

• 形だけの承認。 修正のやり取りを避けるためにざっと目を通して承認すること。インライン化された契約や対処されていない失敗を見過ごすと、欠陥や実装途中の混乱につながります。
• 細部へのこだわりによる修正判定。 文言、図のスタイル、あると望ましいだけの要素を不足として扱い、作業を止めること。修正を求めるのは、実装可能性を本当に妨げる問題がある場合だけです。
• 黙って書き換える。 「設計をそのまま直すほうが簡単だった」――レビュー中に執筆まで行うと、成果物の作成と評価の分離が崩れます。
• 条件の創作。 基準にない要件（特定の手法や図の種類を指定するなど）を追加すること。このゲートが防ぐべき、最も大きな逸脱です。
• 修正箇所を含む設計全体の再レビュー。 小さな変更に対し、変更されていない設計全体を再評価すること。変更箇所とその波及部分（条件 11）を、相応の範囲でレビューしてください。
• 曖昧な判定。 「おおむね承認ですが……」や判定を二つ出すこと。決定は一つ、トークンも一つだけにしてください。

出力

1 件の技術設計ドキュメントに対する、単一のレビュー結果：

• 判定行は 1 行 — VERDICT: approve または VERDICT: revise を、一字一句そのまま単独の行に記載します。
• 指摘事項 — revise の場合は、実装を妨げる不足ごとに、対応可能な指摘を 1 件記載します（満たしていない条件＋箇所＋具体的な修正方法）。approve の場合は、任意で、ブロッカーではない注記を記載できます。

抽象的な利用者とは、成果物の作成→レビューのループを統括するものです。approve は設計を実装に進め、revise は指摘事項を作成者に返し、範囲を限定した修正を行わせます。媒体： 現時点で評価対象となる成果物はテキスト形式の Markdownの TDD ですが、基準は媒体に依存しません。

関連

• authoring-technical-design — このペアの作成側です。このスキルが評価するのと同じ11項目の基準を満たす設計を作成します。両者を組み合わせることで、作成側とレビュー側の基準がずれないよう、基準を一元化できます。
• feature-spec-review スキル — 1つ上の階層にある、機能仕様（各機能の動作）のゲートです。対象となる文書も基準も異なります。
• design-review スキル — 汎用的なエンジニアリング設計文書、RFC、ADR、仕様書、計画のゲートです（主張をコードベースと照合します）。このスキルは、ドキュメントライブラリの technical-design 成果物を専門にレビューします。design-review はその成果物をゲートしません。
• 存在する場合の api-spec / data-model — TDD が参照する契約です。条件4では、ここで重複させずに参照されていることを確認します。
• technical-design template / content-template ツール — セクションの構成を担います。このスキルが評価するのは基準に対する品質であり、構成への適合性ではありません。

段階的な開示

• references/implementability-bar.md — 11項目のチェックリストを、各条件の合格／不足を示すシグナルと具体的な指摘例とともに詳しく説明しています（双方向トレーサビリティ、SSOT／参照と重複の確認、基準を伴う実質的な代替案のテスト、失敗時の対応をまとめた表、可観測性シグナルの分類、テスト／適合性シグナル、ロールアウト／測定可能なロールバックシグナル、変更差分に限定した修正シグナル）。境界的な条件について、合格か不足かをより明確に判断する必要がある場合に読み込んでください。
• references/sources.md — レビュー手法の調査に関する出典情報（設計文書／RFC の慣行、FMEA、RTM／トレーサビリティ、Single Source of Truth、可観測性、RFC／ADR の修正ライフサイクル）。

本文の上限

• description は1,024文字以下（agentskills.io の上限）。一覧表示では、description と when_to_use の合計が1,536文字で切り捨てられます。
• 本文は約500行／5,000トークン以下にします。毎回のターンでコンテキストに保持されます。
• 参照ファイルごとに、10kトークン超で警告、25kトークン超でエラーを出します。参照ファイルの合計は、25kトークン超で警告、50kトークン超でエラーを出します。