review-spec: 仕様レビュー & Notion コメント報告スキル

Notion の仕様ページを取得・読み込み、セキュリティ・整合性・考慮漏れを多角的にレビューし、問題点を Notion コメントとして報告する。仕様ページ自体は変更しない。コメントのみ追加する。

フェーズ概要

1. 準備: CLAUDE.md とコードベースを読み込む
2. 仕様取得: Notion ページを取得して仕様を全文把握する
3. レビュー実施: 各観点で問題点を洗い出す
4. 不明点の確認: 曖昧な点を AskUserQuestion で確認する
5. 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 で確認を取ること