| name | review-spec |
| description | Notion の仕様ページをレビューし、セキュリティ・考慮漏れ・既存実装との整合性などの問題点をコメントとして報告するスキル。「仕様をレビューして」「スペックをチェックして」「review-spec」などの指示で呼び出される。 |
| allowed-tools | ["Read","Glob","Grep","AskUserQuestion","mcp__notion__notion-fetch","mcp__notion__notion-create-comment"] |
review-spec: 仕様レビュー & Notion コメント報告スキル
Notion の仕様ページを取得・読み込み、セキュリティ・整合性・考慮漏れを多角的にレビューし、問題点を Notion コメントとして報告する。仕様ページ自体は変更しない。コメントのみ追加する。
フェーズ概要
- 準備: CLAUDE.md とコードベースを読み込む
- 仕様取得: Notion ページを取得して仕様を全文把握する
- レビュー実施: 各観点で問題点を洗い出す
- 不明点の確認: 曖昧な点を AskUserQuestion で確認する
- Notion コメント投稿: 重大度別に問題点を報告する
フェーズ 1: 準備
- CLAUDE.md を読み込み、プロジェクトのアーキテクチャパターン・技術スタック・制約を把握する
- 引数 (
ARGUMENTS) から Notion URL を取得する
- 引数がない場合: AskUserQuestion で「レビューする Notion ページの URL を教えてください」と確認する
フェーズ 2: 仕様取得
mcp__notion__notion-fetch で Notion ページを取得し、仕様の全内容を把握する。
その後、仕様に登場する関連ファイル・API・スキーマ・型などを Glob/Grep/Read でコードベースから実際に読み込み、実装と仕様を照らし合わせる。
フェーズ 3: レビュー実施
以下の優先順位でレビューする。各問題点には必ず重大度を付ける。
重大度定義
| ラベル | 基準 |
|---|
| 🔴 Critical | セキュリティホール・データ破壊・サービス停止につながるもの。即時修正が必要。 |
| 🟠 Major | 正しく動作しない・重大なバグになるもの。リリース前に修正が必要。 |
| 🟡 Minor | 改善推奨・ベストプラクティス逸脱。対応は任意だが記録する。 |
① セキュリティ・認可 【最優先】
- 認証されていないユーザーがアクセスできるエンドポイントはないか？
- 他ユーザーのデータに不正アクセスできる設計 (IDOR) になっていないか？
- リクエストで受け取った
accId・playlistId などを、DB の所有確認なしに信頼していないか？
userId はリクエストボディから取らず、セッション or ジョブ DB から取得しているか？
- OWASP Top 10 のリスク:
- XSS・CSRF・SQL インジェクション・認可不備・機密データ露出・セキュリティ設定ミス
- サービス間通信に適切な認証 (WORKER_SECRET 等) があるか？
- シークレット (API キー・トークン) がレスポンスやログに漏れる設計になっていないか？
② 考慮漏れ・エッジケース 【高優先】
- API レート制限 (YouTube Data API quota 等) への対策はあるか？ 429 時の挙動は？
- べき等性: リトライ・再実行時に同じ操作が二重実行されないか？
- 並行実行・競合状態 (race condition): 複数の Worker/リクエストが同時に動いた場合の整合性は？
- 長時間処理: ブラウザを閉じた・セッションが切れた場合の挙動は？
- 境界値・空データ: 空リスト・null/undefined・ゼロ件の API レスポンスへの対処は？
- エラーの伝播: 途中失敗時にジョブ・DBの状態が中途半端にならないか？
- タイムアウト: 外部 API 呼び出し・DB クエリにタイムアウトの考慮はあるか？
③ 既存実装との整合性
- v2 リポジトリ層 (native fetch + Zod) / BetterAuth / Drizzle スキーマとの矛盾はないか？
- neverthrow の Result 型パターンとの整合性はあるか？
- 既存の API・型定義・関数シグネチャとの重複・矛盾はないか？
- Feature Flag 戦略との整合性はあるか？
④ UX・フロー
- エラー発生時のユーザーへのフィードバック (トースト・UI 表示) は仕様に含まれているか？
- ローディング状態・中間状態の扱いは考慮されているか？
フェーズ 4: 不明点の確認
仕様を読んで判断できない箇所があれば 必ず AskUserQuestion ツールで確認を取る。会話文での質問は禁止。
特に以下は判断できないまま進めない:
- セキュリティ上の設計意図が不明な箇所（「意図的な設計」か「仕様漏れ」かの判断）
- 既存コードとの差異が「破壊的変更」なのか「意図的な更新」なのかの判断
フェーズ 5: Notion コメント投稿
mcp__notion__notion-create-comment で仕様ページにコメントを追加する。
コメント形式
以下のフォーマットでコメントを作成すること。問題がない観点は「問題なし」と明記する。
## 仕様レビュー結果
### サマリー
- 🔴 Critical: {N} 件
- 🟠 Major: {N} 件
- 🟡 Minor: {N} 件
---
### 🔴 Critical
#### [C-1] {問題タイトル}
- **場所**: {仕様の該当セクション名}
- **問題**: {問題の詳細説明}
- **リスク**: {放置した場合に起こりうること}
- **改善案**: {具体的な修正案}
#### [C-2] ...
---
### 🟠 Major
#### [M-1] {問題タイトル}
- **場所**: ...
- **問題**: ...
- **リスク**: ...
- **改善案**: ...
---
### 🟡 Minor
#### [N-1] {問題タイトル}
- **場所**: ...
- **問題**: ...
- **改善案**: ...
---
問題なし ✅
- {問題がなかった観点のリスト}
---
*review-spec skill によるレビュー*
問題がゼロの場合
## 仕様レビュー結果 ✅
重大な問題は見つかりませんでした。
確認した観点:
- ✅ セキュリティ・認可
- ✅ 考慮漏れ・エッジケース
- ✅ 既存実装との整合性
- ✅ UX・フロー
---
*review-spec skill によるレビュー*
投稿後、Notion ページの URL とレビュー結果のサマリーをユーザーに表示して完了を伝える。
Important Notes
- 必ず AskUserQuestion ツールを使うこと — 会話文での質問は禁止
- 仕様ページの内容は変更しない — コメント追加のみ行う
- セキュリティ・認可の観点を最優先でチェックすること
- 問題がなければ「問題なし ✅」のコメントを投稿すること (無言で終わらない)
- コードベースを実際に読み込んで既存実装との差異を確認すること
- 判断できない箇所は推測で進めず、AskUserQuestion で確認を取ること
