create-spec: 機能仕様策定 & Notion ドキュメント化スキル

引数として渡された機能名・概要をもとに、ユーザーへのインタビューを通じて仕様を深堀りし、最終的に Notion にドキュメントとして保存する。

フェーズ概要

1. 準備: CLAUDE.md を読み込み、プロジェクトパターンを把握する
2. インタビュー: AskUserQuestion ツールで仕様を詰める (dig:dig スタイル)
3. 一貫性・セキュリティ検証: ユーザーの指示に疑いを持ち、矛盾・セキュリティリスクを指摘する
4. Notion 書き出し: 完成した仕様を Notion ページとして保存する

フェーズ 1: 準備

• CLAUDE.md を読み込み、既存のアーキテクチャパターン・技術スタックを把握する
• 引数 (ARGUMENTS) から機能名と概要を取得する
  • 引数がない場合は、最初の質問で「何の仕様を作りますか？」から始める

フェーズ 2: インタビュー (dig:dig スタイル)

AskUserQuestion ツールを使ってインタビューを繰り返す。必ず AskUserQuestion ツールを使うこと。会話文での質問は禁止。

ルール

• 質問数: 1 ラウンドにつき 2〜4 問 (曖昧さの度合いに応じて調整)
• 選択肢: 各質問に 2〜4 個の具体的な選択肢
• 各選択肢: 簡潔な Pros/Cons を含む
• オープンエンド禁止: 自由記述ではなく選択式。"Other" は自動追加されるので書かない
• CLAUDE.md のパターンに合わせる: 既存の技術スタック・アーキテクチャパターンを選択肢に反映する
• 不明な点・曖昧な点が解消されるまでインタビューを繰り返す

各ラウンド後の出力フォーマット

## Decisions

| 項目 | 選択 | 理由 | 備考 |
|------|------|------|------|
| ... | ... | ... | ... |

その後、未決事項・曖昧な点があれば次のラウンドへ進む。

インタビューで必ず確認すること

• 機能の目的・背景: なぜこの機能が必要か
• ユーザー体験: どんな操作フローか
• 技術的な実現方法: 既存パターン (v2 リポジトリ / BetterAuth / Drizzle など) との統合方法
• エラーハンドリング: 失敗時の挙動
• セキュリティ境界: 認証・認可が必要か

フェーズ 3: 一貫性・セキュリティ検証

インタビュー結果をまとめる前に、以下の観点で必ず検証する。ユーザーが指示した内容であっても疑いを持ち、問題があれば AskUserQuestion で確認を取ること。

整合性チェック

• 既存の v2 リポジトリ層 (native fetch + Zod) / BetterAuth / Drizzle スキーマとの整合性はあるか？
• 既存の API・型定義との矛盾はないか？
• Feature Flag 戦略と整合しているか？
• neverthrow の Result 型パターンで統一されているか？

セキュリティチェック

• 認証・認可は適切か？ (BetterAuth セッション / WORKER_SECRET など)
• ユーザーが他ユーザーのデータにアクセスできる設計になっていないか？
• 外部入力 (accId, playlistId 等) を信頼していないか？ — リクエストで受け取った値は DB で所有確認すること
• OWASP Top 10 (XSS・CSRF・SQL インジェクション・認可不備など) のリスクはないか？
• サービス間通信に適切な認証 (WORKER_SECRET 等) があるか？

問題が見つかればユーザーに提示し、仕様を修正してから次フェーズへ進む。

フェーズ 4: Notion ページ作成

作成前に Notion Markdown 仕様を取得すること

ReadMcpResourceTool("notion://docs/enhanced-markdown-spec")

Notion 固定設定

ページテンプレート (汎用)

以下のセクションを使用する。内容が不要なセクションは省略する。 mermaid 図・テーブル・コードブロックを積極的に活用して PlaylistActionJobQueue と同等の品質にすること。

markdown
1# 概要
2{機能の一文説明}
3
4**背景と目的**
5- 現状: {現在の課題・状況}
6- 目的: {この機能で達成したいこと}
7
8**技術スタック** (必要な場合)
9| レイヤー | 技術 | 役割 |
10|----------|------|------|
11| ... | ... | ... |
12
13---
14# アーキテクチャ (必要な場合)
15## 構成図
16{mermaid flowchart など}
17
18## シーケンス図 (必要な場合)
19{mermaid sequenceDiagram}
20
21---
22# セキュリティ・認可 (必要な場合)
23{認証・認可フロー。外部入力の検証ポイントも含む}
24
25---
26# 仕様
27{機能の詳細仕様。型定義・バリデーションルールなど}
28
29---
30# API 仕様 (必要な場合)
31{エンドポイント定義・リクエスト/レスポンス・エラーコード}
32
33---
34# DB スキーマ (必要な場合)
35{Drizzle スキーマ定義}
36
37---
38# ファイル構成 (必要な場合)
39{追加・変更するファイル一覧}

Notion ページ作成

mcp__notion__notion-create-pages({
  parent: { type: "data_source_id", data_source_id: "2fd066ac-825e-8057-b618-000b4c1f69a4" },
  pages: [{
    properties: {
      "名前": "<機能名>",
      "カテゴリ": "PlaylistWizard"
    },
    icon: "/icons/document_purple.svg",
    content: "<Notion Markdown 形式の仕様>"
  }]
})

作成完了後、Notion ページの URL をユーザーに表示して完了を伝える。

Important Notes

• 必ず AskUserQuestion ツールを使うこと — 会話文での質問は禁止
• ユーザーの指示でも整合性・セキュリティを疑うこと
• インタビューは不明点がすべて解消されるまで繰り返す
• Notion ページは PlaylistActionJobQueue と同等の品質 (mermaid 図・テーブル・コードブロック活用) を目指す
• セクションは汎用テンプレートから必要なものだけ使う (不要セクションは省略)