pm-spec-quality-audit

仕様品質監査スキル

このスキルがデフォルトの動作から変える点

デフォルトでは、Claude は仕様書の構成を称賛し、表現を整える提案をします。「記述どおりに構築できるか」「チームによって解釈が分かれないか」「対象外の範囲がひそかに抜け落ちていないか」「『検証済み』という主張に根拠があるか」は、ほとんど確認しません。この監査では、次の4点を徹底します。各指摘で違反している原則を明示すること、各要件について「意図を確認せずに、QA が合否判定を作成できるか」を検証すること、記載されている内容だけでなく、欠けているもの（スコープの除外事項、DCA、境界ケース）も確認すること、そして構築への悪影響に基づく重大度と、具体的な書き換え案を添えて指摘することです。

このスキルは評価を行うスキルです。仕様書、PRD、要件文書のレビュー時に自動実行され、pm-product-spec が生成した文書の検証ステップとしても実行されます。

スコープの厳守。 直接呼び出された場合（ユーザーがこの監査を指定した場合）、レビュー対象はこの懸念事項のみです。関連する他の監査を持ち込まないでください。他の観点と併せて実行するのは、docs/orchestration-policy.md に従って pm-product-review オーケストレーターまたは生成スキルがこの監査を呼び出す場合に限られます。その場合、この監査は**成果物固有の観点 — 提供対象（仕様書／PRD）**に位置づけられます。明示されたスコープが常に優先されます。

---

フレームワーク — 確認事項と違反例

1. 問題との結び付きと追跡可能性

仕様書は、問題または機会と、それが今重要である理由から始めます。たとえ全員が「すでに知っている」としても同様です。すべての要件は、ユーザーまたはビジネスの成果に結び付いています。要件と意図を一貫して関連付けた仕様書は、長期プロジェクトが実装の寄せ集めへと逸れていくのを防ぎます。

次の場合に指摘します： 文書が解決策から始まっている、明示された問題や目標に寄与しない要件がある、「なぜ」が作成者の頭の中にしかない。

• ❌ 仕様書の冒頭：「ダッシュボードに招待枠を3つ備えた紹介ウィジェットを作る。」
• ✅ 仕様書の冒頭：「今年、顧客獲得単価が40％上昇した一方、紹介経由のユーザーは2倍の定着率を示しています。目標：新規登録の15％以上を生み出す紹介の仕組み。」

2. 適切なレイヤー — 要件、機能仕様、技術仕様

3層の階層は次のとおりです。ビジネス／ユーザー要件（ユーザーが体験すること — PRD）、機能仕様（プロダクトの動作。UI がなくても定義できます）、技術仕様（コードで実現する方法 — エンジニアリングの領域）。レイヤーが混在すると、よくある2つの問題が起きます。要件の域を出ない曖昧な仕様書と、PM がアーキテクチャにまで踏み込むことです。

次の場合に指摘します： 機能仕様でフレームワーク、データモデル、アーキテクチャを指定している、「仕様書」に成果への希望しかなく、動作の定義がない、PRD の目標と実装の詳細が同じセクションに混在している。

• ❌ 「価格計算機能は、Redis キャッシュを備えた Node マイクロサービスとして実装すること。」（PM の機能仕様に記載）
• ✅ 「価格計算では、基本価格、割引ルール、任意のプロモーションコードを受け取り、検証済みの最終価格を返すこと。計算用の UI がない場合も同様とする。」

3. すべての要件のテスト可能性

QA、または誰であっても、作成者に確認することなく、要件に基づいて合否判定を作成できる状態が、要件の完了です。主観的な形容詞は、典型的な違反です。テスト可能性は、機能（操作→応答）、ユーザビリティ（タスクの完了）、パフォーマンス（負荷、エラー率）、アクセシビリティ（コントラスト、キーボード、スクリーンリーダー）など、あらゆる種類の要件に当てはまります。

次の場合に指摘します： 「速い」「直感的」「使いやすい」「シームレス」といった表現に定義済みの尺度がない、成功基準に数値、単位、条件がない、要件が満たされたかどうかを判断する方法がない。

• ❌ 「ページは速く読み込まれること。」
• ✅ 「標準的なモバイルネットワーク環境で、ページが3秒以内に読み込まれること。」

4. 完全なフローを記述し、成功ケースだけにしない

要件では、結果だけでなく、例外ケース、エラー、中断や再開・部分的な状態も含めたワークフロー全体を記述する必要があります。「ユーザーはアカウントを作成できます」では、重要な実装上の判断がすべて隠れてしまいます。

次の場合は指摘してください： 成功パスしか指定されていない場合、エラー、中断、再訪ユーザーの動作が定義されていない場合、複数ステップのフローが結果を示す一文だけで書かれている場合。

• ❌ 「ユーザーはドキュメントを作成できます。」
• ✅ 「［ドキュメントを作成］をクリックすると、下書きが作成されます。ユーザーは編集できますが、名前とフォルダーを指定するまでは保存されません。フローの途中でユーザーが離脱した場合、下書きは30日間保持されます。」

5. スコープを明確にする — 対象外も明記する

スコープでは、対象だけでなく対象外も明記する必要があります。明示されていない対象外には、認識のずれやスコープの拡大が潜んでいます。ユースケースでは、含まれる機能だけでなく、対象外の機能も記載してください。

次の場合は指摘してください： 対象外がどこにも記載されていない場合、「スコープ」が境界のない機能リストになっている場合、ステークホルダーが期待している内容を仕様書が暗黙のうちにカバーしていない場合。

• ❌ スコープ：「チェックアウトフローを再設計。」（ゲストチェックアウトは含まれるのか？返金は？モバイルアプリとの同等性は？）
• ✅ 「対象：ウェブのチェックアウト、ゲストチェックアウト。対象外（今回のリリース）：モバイルアプリのチェックアウト、返金フローの変更、ロイヤルティポイントの利用。」

6. 依存関係、制約、前提（DCA）

最も抜け落ちやすく、実際にデリバリーが破綻する原因となるセクションです。依存関係には担当者と内部・外部の区分が必要です。制約には、柔軟に調整できる要素（期間、コスト、スコープ）のうちどれかを明記する必要があります。3つすべてを固定するのは、失敗を招く計画です。前提は曖昧な思い込みではなく、検証状況と軽減策を伴う、検証可能な文として記述する必要があります。

次の場合は指摘してください： DCAセクションがない場合、依存関係に担当者が設定されていない場合（「法務部門の承認が必要」—誰が、いつまでに？）、期間、コスト、スコープのすべてが固定扱いになっている場合、前提が事実のように書かれている場合（「ユーザーはオンボーディングを直感的に理解できる」）。

• ❌ 前提：「ユーザーは新しいフローを好むでしょう。」
• ✅ 前提：「新規ユーザーの80％が2分以内にオンボーディングを完了する — 3月15日までにユーザビリティテストで検証（担当：UX）。否定された場合：2段階の入力方式に戻す。」

7. 検証の証拠 — レビューは検証ではない

レビューでは内部品質（明確性、一貫性、実現可能性）を確認します（エンジニアリング／UX／ビジネス担当者と実施）。検証では、実際のユーザーにとってソリューションが機能するかを確認します（プロトタイプテスト、ユーザーセッションなど）。得られた知見が仕様書に反映されるよう、検証は仕様書の確定前に実施します。検証済みとする仕様書には、調査結果と、変更された要件との対応関係を示す証拠が必要です。

次の場合は指摘してください： 方法、参加者数、関連する調査結果が記載されていないのに「ユーザーによる検証済み」と書かれている場合、ユーザー検証がチェック項目として開発後に予定されている場合、否定された前提が仕様書に反映されていない場合、仕様書の確定前に依存関係の担当者によるレビューが行われていない場合。

• ❌ 「このフローは検証済みです。」（誰が？何に照らして？）
• ✅ 「5人の参加者によるプロトタイプテスト（3月3日）：5人中3人が［ゲストとして続行］を見落としたため、要件4.2を更新し、ゲストチェックアウトを主要なアクションに変更。」

8. 対象読者への適合と全体像の提示

1 チームの担当範囲だけに絞った仕様書では、単独では機能しても、統合時に問題が起きる機能が生まれます。まず全体像を示し、その後にチームごとの詳細を記載してください。形式は読み手に合わせます。フロントエンドには注釈付きのデザインファイル、バックエンドにはワークフローやデータフローの図、ビジネス関係者には高レベルの成果を示します。社内文書には専有情報を含めてもかまいませんが、社外向け文書には安全に約束できる内容のみを記載します。

次の場合に指摘してください： 仕様書にシステムの背景がなく、1 チームの作業だけを扱っている場合、バックエンドの動作が UI モックアップのみで仕様化されている場合、ビジネス関係者に API レベルの詳細を提示している場合（またはエンジニアにビジョンの説明しか提示していない場合）、1 つの文書で社内向けと社外向けの両方に対応しようとして無理が生じている場合。

• ❌ 新しい決済 UI は記載しているものの、依存する order-service とメール領収書の変更には触れていないチェックアウト仕様書。
• ✅ まず全体のフローを説明し、その後チームごとのセクションを記載します。フロントエンドには注釈付きの Figma、決済バックエンドにはデータフロー図を用意します。

トレードオフに関する注記： 網羅性と焦点のバランスが重要です。実装の細部で膨らんだ仕様書は、内容が薄い仕様書と同じように問題です。指摘すべきなのは、説明の不足ではなく、未決定の事項です。設計文書や技術文書に属する詳細を削除することは改善であり、欠落ではありません。また、安定性と柔軟性のバランスも重要です。PRD は柔軟性を保つ一方、仕様書は開発開始後に安定させる必要があります。仕様書ほど正確でないという理由だけで、PRD を指摘しないでください。

---

重大度の評価

各指摘は、ビルドへの損害、つまり文書を現状のままにした場合にチームが何を作ってしまうかに基づいて評価してください。

重大度	意味
Critical	チームが誤ったもの、または互いに異なるものを作ってしまいます（テスト不可能な中核要件、定義されていない主要フロー、意見が分かれている領域の未記載のスコープ境界、問題が定義されていないソリューション）。
Major	デリバリーに支障が生じる、または方向性がずれていきます（DCA の欠落、外部依存関係のオーナーが不明、正常系のみのフロー、主要な意思決定を左右する未検証の前提、1 チームだけに視野が偏っていること）。
Minor	文書への信頼を損なう整備上の問題です（用語の不統一、二次要件の受け入れ基準の欠落、古いセクション）。
Cosmetic	表現の調整です。こうした指摘でレポートを水増ししないでください。

重複する領域：成功指標自体が妥当かどうか（見栄えだけの指標、操作可能な指標、反証不可能な指標）は pm-okr-metric-validity-audit の対象です。この監査では指標が存在し、具体的かを確認し、もう一方ではその指標が目指す価値のあるものかを確認します。スコープに含めた項目の優先順位付けの妥当性は pm-prioritization-rigor-audit の対象です。前提を検証する方法を深く評価する作業、つまり最もリスクの高い前提を適切な忠実度の手法と信頼できる証拠で検証したかどうかは、pm-assumption-rigor-audit の対象です。

---

出力形式

## Spec Quality Audit — [Document]
Context: [doc type (PRD/functional/technical) · audience · development stage, if known]

### Critical
- [Issue] — what's wrong → concrete rewrite or addition. (Principle)
### Major
- …
### Minor
- …
### Working well ✓
- …

**Top 3 priorities:** the highest build-damage fixes, with suggested rewrites.

最後に、優先度順の主要な問題を必ず記載してください。箇条書きを並べるだけでは誰も対応できません。

---

適切な監査を行う方法

1. まず背景を把握する — これはどの文書ですか（PRD、機能仕様書、技術仕様書）？別の層の役割ではなく、その文書が属する層の役割に照らして監査してください。ライフサイクルのどの段階ですか（レビュー用のドラフトか、承認済みで開発中か。承認後の変更にはより多くのコストがかかります）？
2. 欠陥だけでなく欠落も確認する — 最も深刻な仕様書の欠陥は、セクションの欠落（スコープの除外事項、DCA、エラーフロー）です。記載済みの内容を読み返すだけでは見つかりません。チェックリストに沿って確認してください。
3. 実質的なコストがあるものだけ指摘する — 小規模で元に戻せる機能の簡潔な仕様書に、コンプライアンスのセクションは必要ありません。リスクとプロジェクトの規模に応じて厳密さを調整してください。
4. 列挙ではなく優先順位付けをする — ビルドに損害を与える指摘が 3 件ある方が、細かな指摘が 15 件あるより有用です。
5. 修正内容を具体的にする — 要件を書き直し、不足しているオーナーを示し、除外事項の一文を作成してください。「もっとテストしやすくする」とだけ書いてはいけません。

よくあるやるべきこと／避けるべきこと

❌ 避けること	✅ やること
構成や洗練された表現を褒める	要件を一つずつ検証します。その要件に基づいて、QA が合否を判定するチェック項目を作成できますか？
書かれている内容だけをレビューする	チェックリストを使って、不足しているもの（除外事項、DCA、エラーフロー）を確認します
「ユーザーで検証済み」という言葉をそのまま受け入れる	方法、参加者、調査結果によってどの要件が変更されたかを尋ねます
レビューと検証を同じ工程として扱う	レビュー＝内部品質の確認、検証＝仕様の確定前に収集する実際のユーザーの証拠
「速い／シームレス／直感的」を要件として受け入れる	数値、単位、条件を使って書き直します
仕様の精度が不足しているという理由で PRD を指摘する	各ドキュメントを、それぞれのレイヤーの役割に照らして監査します
あらゆる箇所で詳細を増やすよう求める	不足している意思決定を指摘し、技術／デザインドキュメントに記載すべき実装上のノイズは削除します
成功指標の妥当性を再監査する	pm-okr-metric-validity-audit に委ね、ここでは記載の有無と具体性を確認します
優先順位のない問題の羅列を提示する	ビルドへの影響度で重大度を評価し、書き直し案を添えた優先課題トップ 3 を提示します

---

参考レッスン（Uxcel）

• 仕様のレビューと検証
• プロダクト仕様を理解する
• プロダクト仕様の種類
• プロダクト仕様書とプロダクト要件定義書の違い
• 依存関係、制約、前提条件