web-to-prd

Web-to-PRD スキル

稼働中のウェブアプリをスキャンし、すべての機能を抽出します。エピック、ストーリー、タスクを含む構造化された PRD にまとめ、すべて Notion に登録します。

使用する場面

• 競合製品をリバースエンジニアリングする
• 引き継ぐ既存アプリのドキュメントを作成する
• 稼働中の製品（自社または他社のもの）から PRD を作成する
• すでに構築されているものを確認し、一から機能バックログを作成する

このスキルでできること

1. 前提条件を確認します — Playwright MCP と Notion MCP が接続されていることを確認します
2. ウェブアプリをクロールします — ページを順番に移動し、UI 要素を読み取ります
3. 機能を抽出します — 見つかった内容を機能領域ごとに分類します
4. PM 成果物を生成します — 優先度と依存関係を含む PRD、エピック、ストーリー、タスクを作成します
5. Notion にエクスポートします — 相互にリンクされたデータベースを作成し、すべての情報を登録します

前提条件

このスキルには 2 つの MCP サーバーが必要です。コマンドの実行開始前に両方を確認します。

1. Playwright MCP（ブラウザー制御）

Claude は Playwright を使って実際のブラウザーを開き、ページを移動し、コンテンツを読み取ります。

ブラウザーモード

モード	インストールコマンド	動作
永続プロファイル（デフォルト）	セットアップ方法は以下を参照	~/.playwright-profile に軽量プロファイルを作成します。一度ログインすれば、その状態が記憶されます。Chrome は開いたままになります。拡張機能による肥大化もありません。
CDP（高度な設定）	--cdp-endpoint='http://localhost:9222'	起動中の Chrome に接続します。ログイン状態を利用できますが、すべての拡張機能も読み込むため、動作が遅くなる場合があります。
Chrome プロファイル（高負荷）	--user-data-dir="[Chrome path]" --browser=chrome	実際の Chrome プロファイルを使用します。ログイン状態を利用できますが、すべての拡張機能を読み込むため、タイムアウトが発生することがよくあります。推奨しません。
クリーンセッション	追加フラグなし	毎回新しいブラウザーを起動します。保存済みの状態はありません。公開サイト専用です。

デフォルトのセットアップ：永続プロファイル（コマンドが自動でインストール）

/spartan:web-to-prd コマンドがインストールを処理します。軽量な専用プロファイル ~/.playwright-profile を使用するため、拡張機能がなく、余計な肥大化もなく、起動が速くなります。

コマンドが内部で行う処理：

claude mcp remove playwright 2>/dev/null || true
claude mcp add playwright -- npx @playwright/mcp@latest --user-data-dir="$HOME/.playwright-profile" --browser=chrome

ログインが必要なサイトでの初回実行： Playwright はクリーンなプロファイルで Chrome を開きます。ユーザーが手動でログインすると、Cookie が ~/.playwright-profile に保存されます。次回からはログイン済みの状態で実行されます。

実際の Chrome プロファイルを使わない理由： 実際の Chrome プロファイルでは、すべての拡張機能（AdBlock、LastPass、パスワードマネージャーなど）が読み込まれます。これらは遅延の原因となり、リクエストをブロックし、Playwright のタイムアウトやハングを頻繁に引き起こします。専用プロファイルのほうが高速で、信頼性も高くなります。

Chrome は開いたままにできます。 専用プロファイルを使用するため、競合しません。

モードの切り替え

モードを変更するには、いったん削除してから再追加します。

claude mcp remove playwright
claude mcp add playwright -- npx @playwright/mcp@latest [flags]

Playwright MCP の全フラグ

フラグ	動作
--cdp-endpoint="http://localhost:9222"	CDP 経由で起動中の Chrome に接続します
--user-data-dir="/path"	永続ブラウザープロファイルを使用します（Cookie を保持）
--storage-state="/path/to/state.json"	ファイルから保存済み Cookie を読み込みます
--isolated	永続データのない新しいセッションを使用します
--browser=chrome	Chromium の代わりに実際の Chrome を使用します
--headless	ブラウザーウィンドウを表示しません

すべてのフラグは、PLAYWRIGHT_MCP_ をプレフィックスにした環境変数としても使用できます（例：PLAYWRIGHT_MCP_CDP_ENDPOINT）。

Playwright MCP がインストールされていることを確認する方法：

claude mcp list | grep -i playwright

利用できる機能： browser_navigate、browser_click、browser_snapshot、browser_type、browser_tab_list など。

2. Notion MCP（エクスポート先）

Claude は Notion MCP を使って、ワークスペースにデータベース、ページ、ビューを作成します。

インストール方法： Notion MCP は Claude.ai のインテグレーションとして利用できます。以下から有効にしてください。

• Claude Code の設定 > MCP servers
• または Claude Desktop > Settings > Integrations > Notion

確認方法：

claude mcp list | grep -i notion

利用できる機能： notion-create-database、notion-create-pages、notion-create-view、notion-search、notion-update-page。

任意：Firecrawl MCP（高速なクロール）

ユーザーが Firecrawl を利用できる場合は、初回のクロールに Playwright ではなく Firecrawl を使用してください。より高速ですが、費用がかかります。

claude mcp add firecrawl -- npx firecrawl-mcp

Firecrawl は任意です。Playwright だけですべて対応できます。

---

前提条件の確認ロジック

この確認を最初に実行してください。

重要：claude mcp add/remove を実行しても、セッション中にツールが使えるようにはなりません。 MCP ツールは Claude Code の起動時にのみ読み込まれます。実行中のセッションでは、MCP サーバーをインストールまたは再設定しようとしないでください。機能せず、時間の無駄になります。

CHECK 1: Playwright MCP
  A) Try calling any Playwright tool (e.g., browser_snapshot or browser_navigate)

  If tool works → check the config:
     Read .claude.json for playwright args
     If --user-data-dir points to ~/.playwright-profile → good, proceed
     If --user-data-dir points to real Chrome profile → warn user (extensions cause timeouts)
     If no --user-data-dir (clean mode) → OK for public sites
     If --cdp-endpoint → good, proceed

  If tool NOT found → Playwright MCP is not loaded. Show this message and STOP:

     "Playwright MCP is not available. I need it to open a browser.

     Run this in your terminal (outside Claude Code):
       claude mcp add playwright -- npx @playwright/mcp@latest --user-data-dir=$HOME/.playwright-profile --browser=chrome

     Then restart Claude Code and run /spartan:web-to-prd again."

  NEVER run `claude mcp add` or `claude mcp remove` yourself during the session.
  It changes the config file but won't load the tools until restart.

CHECK 2: Notion MCP (OPTIONAL — not a blocker)
  Try calling notion-search with a simple query
  If found → great, will export to Notion at the end
  If not found → note it, will save PRD locally instead. Continue with crawl.

Playwright OK → proceed to crawl

Notion は任意です。 PRD は常にローカルに保存されます。Notion へのエクスポートは最後に行う追加手順です。

---

クロール戦略

ステップ 0：古いロックファイルを削除する（実行のたびに最初に行う）

以前のブラウザーセッションで残った古いロックファイルが原因で、「Opening in existing browser session」エラーが発生することがあります。削除するのはロックファイルのみです。プロセスは絶対に終了させないでください。

rm -f "$HOME/.playwright-profile/SingletonLock" \
      "$HOME/.playwright-profile/SingletonCookie" \
      "$HOME/.playwright-profile/SingletonSocket" 2>/dev/null
echo "Browser cleanup done"

警告： pkill -f "playwright-profile" は実行しないでください。Playwright MCP サーバーのプロセスも終了し、セッション中にすべてのブラウザーツールが切断されます。

クリーンアップ後も navigate が失敗する場合は、2 秒後に一度再試行してください。それでも失敗する場合は、ユーザーに Claude Code を再起動してもらってください。

ステップ 1：最初にログインする（クロール前に必須）

アクセスを確認せずにクロールを開始しないでください。ログインはステップ 1 であり、後回しにしてはいけません。

1. 対象の URL に移動します
2. スナップショットを取得し、ログインを示す要素（フォームフィールド、「Sign in」のテキスト、/login URL）がないか確認します
3. ログインページの場合：
   • 停止します。ユーザーに「ログインページを検出しました。ブラウザーウィンドウでログインしてください。完了したら教えてください。」と伝えます
   • ユーザーの確認を待ちます
   • スナップショットを取得して確認します。まだログインページの場合は、もう一度依頼します。ダッシュボードが表示された場合は続行します
   • ログインするまで繰り返します。 ログインページからクロールを開始しないでください
4. すでにログイン済みの場合（または公開サイトの場合）：
   • 表示されているセクションをユーザーに示します
   • 「これで完全にアクセスできているように見えますか？見落としているセクションはありますか？」と尋ねます
   • クロールを開始する前に確認を待ちます

クロール中にセッションの有効期限が切れた場合： クロール中にログインページへリダイレクトされたら、停止し、ブラウザーで再ログインするようユーザーに伝えます。確認を待ってから、中断した箇所から続行します。

セキュリティルール：

• パスワードの入力に browser_type を使用しないでください。ユーザー自身がブラウザーに直接入力します
• チャットで認証情報を尋ねないでください
• ログインページのスクリーンショットを撮らないでください
• SSO/OAuth のポップアップは通常どおり機能します。ユーザーの操作完了を待ってください

Cookie： 永続プロファイル（~/.playwright-profile）では、ログイン情報が保存されます。同じサイトで次回実行するときは、すでにログイン済みの状態になります。

ステップ 2：2 パスでクロールする

パス 1 — すべてのページをマッピングする（幅優先）： すべてのナビゲーションリンクを開き、スクリーンショットを撮ってページの種類を記録し、戻ります。サイトマップを完成させます。この段階では機能を深く調べないでください。セクション間を移動するときはホームに戻ります。サイトマップをユーザーに提示し、漏れがないか尋ねます。

パス 2 — 詳細に調査する（すべての機能を徹底的に確認）： サイトマップにある各ページを順に確認します。各ページで、試せるものがなくなるまで、すべてのインタラクティブ要素を試します。ボタンをクリックする → モーダルが開く？ → モーダルには何がある？ → フォームがある？ → どのフィールドがある？ → 送信ボタンがある？ → 送信後に何が起きる？ → 行き止まり、またはすでに調査したページにたどり着くまで、すべての経路をたどります。このページでの操作をすべて試し終えてから、次のページに進みます。目標は、タブ、モーダル、サブページ、条件付き UI の奥に隠れた、2〜3 階層下の機能を見つけることです。

スクリーンショット（必須）

すべてのページと重要な UI 状態のスクリーンショットを撮ってください。.planning/web-to-prd/screenshots/ に 01-homepage.png、02-dashboard.png、07-create-modal.png のような名前で保存します。各 Epic にスクリーンショットへの参照を含めてください。ログインページのスクリーンショットは絶対に撮らないでください。

SPA（シングルページアプリ）の場合

SPA には従来のページ URL がありません。次の方法を使用してください。

1. ルート URL から開始します
2. ナビゲーション／サイドバーを確認して、すべてのセクションを把握します
3. 各セクションをクリックし、コンテンツの読み込みを待ちます
4. ナビゲーションのたびにスナップショットを取得します
5. URL のハッシュまたはパスの変化によって、訪問済みの状態を追跡します

クロール深度の上限

アプリの規模	最大ページ数	推定時間
小規模（10 ページ未満）	全ページ	2-5 分
中規模（10～50 ページ）	全ページ	5-15 分
大規模（50 ページ以上）	最初の 50 ページ。その後、ユーザーに確認	15 分以上

10 ページごとに進捗を表示します：

「10/~25 ページをスキャンしました。機能領域がこれまでに 3 つ見つかりました。続けますか？」

カバレッジ確認（PRD の生成前に必須）

クロール後、カバレッジレポートを表示します。訪問したページ数、撮影したスクリーンショット数、クリックしたボタン数、見つかったモーダル数、見つかったフォーム数、確認したタブ数、テストしたフィルター数を記載します。ナビゲーションのセクションをすべて列挙し、確認したものとスキップしたものを示します。

次の場合は不合格です： 未確認のナビゲーションセクションがある、ページ数よりスクリーンショットが少ない、ボタンがあるページでモーダルが 0 件（クリックしていないことを意味します）、操作が 1 回だけのセクションがある（確認しただけで試していません）。

PRD の生成に進む前に、カバレッジの確認をユーザーに依頼します。

---

機能の抽出

各ページから抽出する内容

訪問したすべてのページについて、以下を記録します：

page:
  url: "/dashboard"
  title: "Dashboard"
  type: dashboard | list | detail | form | settings | landing | auth | empty
  features:
    - name: "Revenue Chart"
      type: data-display | form | action | navigation | filter | notification
      description: "Line chart showing monthly revenue with date range picker"
      ui_elements:
        - chart (line, with tooltips)
        - date range picker
        - export button
      interactions:
        - hover shows tooltip with exact value
        - date range filters the data
        - export downloads CSV
    - name: "Quick Actions Bar"
      type: action
      description: "Row of shortcut buttons: New Invoice, New Client, Reports"
      interactions:
        - each button navigates to respective page

機能のグループ化ルール

クロール後、機能を機能領域（これらがエピックになります）にグループ化します：

1. ナビゲーションセクション別 — サイドバーやナビゲーションバーのセクションは、自然なグループ分けになります
2. ユーザーの目標別 — ユーザーは何をしようとしていますか？
3. データドメイン別 — 同じデータを扱う機能はまとめます

グループ化の例：

Epic: User Management
  - User list with search/filter
  - User profile page
  - User invite flow
  - Role assignment
  - User deactivation

Epic: Billing & Payments
  - Invoice list
  - Create invoice form
  - Payment tracking
  - Subscription management
  - Billing settings

優先度の割り当て

可視性と複雑さに基づいて優先度を割り当てます：

優先度	基準
P0 - 必須	中核となるユーザーフロー。これがないとアプリは機能しません
P1 - 望ましい	重要ですが、なくてもアプリは使用できます
P2 - あると便利	機能強化、仕上げ、エッジケースへの対応
P3 - 将来対応	高度な機能。あると便利ですが、今は必要ありません

ヒューリスティクス：

• メインナビゲーション項目 → P0 または P1
• 設定／構成ページ → P1 または P2
• 空の状態、オンボーディング → P2
• ソーシャル機能、共有 → P2 または P3

依存関係のマッピング

機能間の依存関係をマッピングします：

Epic: Authentication (must build first)
  → Epic: User Management (needs auth)
    → Epic: Team Management (needs users)
      → Epic: Permissions (needs teams)

Epic: Product Catalog (independent)
  → Epic: Shopping Cart (needs products)
    → Epic: Checkout (needs cart)
      → Epic: Order Management (needs checkout)

依存関係のルール：

• CRUD 操作：作成の後に読み取り／一覧表示、更新、削除の順に行います
• 認証は常に最初です
• データの表示はデータ入力に依存します
• 設定は、設定対象となる機能に依存します

---

PRD の生成

構成

8 つのセクションからなる PRD を生成します。各エピックはミニ PRDです。開発者がエピックを 1 つ読むだけで、何を構築すればよいか正確にわかるようにします。

1. TL;DR              — 2 sentences, what this app does
2. Goals              — Business goals, user goals, non-goals
3. User Stories        — Grouped by persona/role
4. Epics (mini-PRDs)  — THE MAIN SECTION. Each epic has full detail (see below)
5. User Flows         — End-to-end flows connecting stories across epics
6. Narrative          — 200-word story from user's POV
7. Build Roadmap      — Phased plan with dependency graph
8. Open Questions     — Things that need human input

セクション 4（エピック）が中核です。 エピックは構築の優先度順に並べます（エピック 1 を最初に構築します）。

各エピックは、6 つのセクションからなる完全な PRD です：

Epic N: [Name]
├── 1. TL;DR — what this epic solves, who it's for
├── 2. Goals — business goals, user goals, non-goals
├── 3. User Stories — As a [user], I want...
├── 4. Functional Requirements — every feature with screenshots, UI detail, priority
├── 5. User Experience — entry point, flow (step by step), edge cases, design notes
└── 6. Narrative — 100-word user story for this epic

どのエピックも、いずれかのセクションを省略できません。 すべてのエピックに 6 つのセクションを含めます。これにより PRD を実行可能なものにできます。開発者はエピックのページを 1 つ読むだけで、何を構築すればよいか正確にわかります。

スクリーンショットはセクション 4 に埋め込み、表示する機能のすぐ隣に配置します。末尾にまとめたり、リンクとして掲載したりせず、コンテンツ内に直接配置します。

できる限り詳しく記述します。 すべてのボタン、フォームフィールド、テーブルの列、フィルターの選択肢を説明します。

すべての機能を試します。 すべてのメニューをクリックし、すべてのモーダルを開き、すべてのフィルターをテストします。機能が漏れると、役に立たない PRD になります。

例を含む完全なテンプレートについては、コマンドファイル（web-to-prd.md）を参照してください。

---

Notion へのエクスポート

データベースの構成

親ページを作成し、エピックごとにサブページを 1 つ作成します：

Parent page: "[App Name] — PRD"
├── PRD overview (sections 1-3, 5-8)
├── Epic 1: [Name] (full page with screenshots, features, acceptance criteria)
├── Epic 2: [Name] (full page with screenshots, features, acceptance criteria)
├── ...
└── Optional: Epics overview database (for filtering/sorting, links to pages)

各エピックは、完全な Notion ページです。 Description フィールドを持つデータベースの行ではありません。以下を含めます：

• PRD のセクション 4 の形式に沿った完全な内容
• ページ内に直接埋め込んだスクリーンショット（リンクではなく、表示されるもの）
• すべての機能の詳細：ユーザーストーリー、UI の説明、手順、受け入れ基準

スクリーンショットは Notion にアップロードする必要があります。 ローカルに保存するだけでは不十分です。説明する機能のすぐ隣に配置します。

エクスポート手順

1. 保存先を確認します：

   "Notion のどこにバックログを作成しますか？ A) ワークスペースのルートに新しいページを作成する B) 既存のページの下に追加する（検索します） C) PRD をローカルで生成するだけにして、Notion には送信しない"

2. PRD の内容を含む親ページを作成します

3. すべてのエピックを含むエピックデータベースを作成します

4. エピックにリンクしたストーリーデータベースを作成します

5. ストーリーにリンクしたタスクデータベースを作成します

6. ビューを作成します：

   • ストーリー用のカンバンビュー（ステータス別）
   • エピック用のタイムラインビュー（フェーズ別）
   • タスク用のテーブルビュー（デフォルト）

Notion MCP が利用できない場合

すべてローカルに保存します：

.planning/web-to-prd/
├── prd.md                    # Full PRD document
├── epics.md                  # All epics with stories
├── dependency-graph.md       # Visual dependency map
└── screenshots/              # Page screenshots (if taken)

ユーザーは後から手動で Notion にインポートできます。

---

ルール

1. 必ず最初に前提条件を確認します。 両方の MCP サーバーが利用できることを確認するまでは、クロールを開始しないでください。
2. クロールの前にログインします。 ログインページや一般公開のみのビューから PRD を生成しないでください。アプリにログイン機能がある場合は、最初にログインしてください。開始前にアプリの全体が表示されていることを確認してください。
3. アクセスレベルを確認します。 ログイン後、表示されているセクションをユーザーに示し、表示されていないものがないか確認してください。制限されたビューから作成した PRD は役に立ちません。
4. セッションの期限切れに対処します。 クロールの途中でログインページにリダイレクトされた場合は、作業を停止して、ユーザーに再ログインを依頼してください。ログインページからクロールしないでください。
5. クロール中は進捗を表示します。 10 ページごと、または主要セクションごとに、ユーザーに進捗を知らせてください。
6. 確認できない機能を推測しないでください。 UI に表示されている内容だけを記録してください。仮定は明確に示してください。
7. 破壊的な操作をクリックする前に確認します。 クロール中に「Delete」または「Remove」ボタンが表示されても、クリックしないでください。
8. エラーには適切に対処します。 ページの読み込みに失敗した場合はその旨を記録して、次に進んでください。クロール全体を停止しないでください。
9. レート制限を守ります。 ブロックを避けるため、ページ遷移の間に 1〜2 秒の遅延を入れてください。
10. スクリーンショットは必須です。 すべてのページでスクリーンショットを撮り、![name](path) 構文を使って Markdown の PRD に埋め込んでください。
11. ログインはユーザーが行います。 本番環境の認証情報を保存したり、ユーザーに尋ねたりしないでください。手動ログインにはヘッド付きモードを使用してください。
12. ローカル保存はいつでも利用できます。 Notion へのエクスポートに失敗しても、PRD はローカルに保存されます。
13. 1 回の実行につき 1 つのアプリに限定します。 1 回のセッションで複数のドメインをクロールしないでください。
14. --user-data-dir を実際の Chrome プロファイルディレクトリに指定してはいけません（例：Mac では ~/Library/Application Support/Google/Chrome、Linux では ~/.config/google-chrome）。Chrome プロファイルが破損したり、保存済みのログイン情報が削除されたり、ユーザーのブラウザーが動作しなくなったりするおそれがあります。必ず ~/.playwright-profile のような別のディレクトリを使用してください。