web-to-prd

Web-to-PRD 技能

扫描在线 Web 应用。提取所有功能。将其整理为包含 Epic、用户故事和任务的结构化 PRD。将所有内容推送到 Notion。

使用场景

• 逆向分析竞品
• 为你接手的现有应用编写文档
• 根据在线产品（自己的或他人的）创建 PRD
• 从头构建功能待办列表，了解现有产品的功能

此技能的功能

1. 检查前置条件 — 确认 Playwright MCP 和 Notion MCP 已连接
2. 爬取 Web 应用 — 逐页浏览并读取 UI 元素
3. 提取功能 — 将发现的内容归入不同功能领域
4. 生成 PM 文档 — 生成 PRD、Epic、用户故事和任务，并标注优先级和依赖关系
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	使用真实的 Chrome，而非 Chromium
--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 服务
• 或 Claude Desktop > 设置 > 集成 > 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。速度更快，但需要付费。

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：两轮抓取

第一轮——映射所有页面（广度优先）： 访问每个导航链接，截取屏幕截图，记录页面类型，然后返回。构建完整的网站地图。此时先不要深入探索功能。在各个版块之间返回首页。向用户展示网站地图，并询问是否有遗漏。

第二轮——深入探索（穷尽所有功能）： 逐一检查网站地图中的每个页面。在每个页面上，尝试每个交互元素，直到没有未尝试的元素为止。点击按钮 → 打开了模态框？→ 模态框里有什么？→ 有表单吗？→ 有哪些字段？→ 有提交按钮吗？→ 提交后会发生什么？→ 沿每条路径继续探索，直到遇到死路或已探索过的页面。只有穷尽当前页面的所有交互后，才进入下一页。目标是发现隐藏在标签页、模态框、子页面或条件式 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 前必须执行）

爬取完成后，显示覆盖情况报告：访问的页面数、截取的屏幕截图数、点击的按钮数、找到的模态框数、找到的表单数、探索的选项卡数、测试的筛选器数。列出所有导航分区，并标记哪些已探索、哪些已跳过。

**以下情况视为未通过：**有任何导航分区未探索；屏幕截图少于页面数；某个有按钮的页面未找到模态框（说明你没有点击按钮）；某个分区只有 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

功能分组规则

爬取完成后，将功能分组为功能领域（这些将成为 Epic）：

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。每个 Epic 都是一份迷你 PRD——开发者阅读一个 Epic，就能确切知道要构建什么。

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 节（Epic）是核心。 Epic 按构建优先级排序（Epic 1 = 优先构建）。

每个 Epic 都是一份包含 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

**任何 Epic 都不能跳过任何章节。**每个 Epic 都必须包含全部 6 个章节。这样 PRD 才能付诸实施——开发者阅读一个 Epic 页面，就能确切知道要构建什么。

屏幕截图应嵌入第 4 节中，放在其展示的功能旁边。不要放在末尾，也不要作为链接——应与内容内嵌。

**尽可能详细。**描述每个按钮、每个表单字段、每个表格列、每个筛选选项。

**尝试每一项功能。**点击每个菜单，打开每个模态框，测试每个筛选器。遗漏功能会让 PRD 毫无用处。

完整模板及示例请参阅命令文件（web-to-prd.md）。

---

Notion 导出

数据库结构

创建一个父页面，并为每个 Epic 创建一个子页面：

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)

每个 Epic 都是一篇完整的 Notion 页面，而不是带有 Description 字段的数据库行。页面中应包含：

• PRD 第 4 节格式的完整内容
• 直接嵌入页面中的屏幕截图（可直接查看，而非链接）
• 每项功能的所有详细信息：用户故事、UI 描述、分步说明、验收标准

屏幕截图必须上传到 Notion，不能只保存在本地。请将其放在对应功能旁边。

导出步骤

1. 询问保存位置：

   “我应该在 Notion 的哪个位置创建待办事项？ A) 在工作区根目录新建页面 B) 添加到现有页面下（我会搜索该页面） C) 仅在本地生成 PRD，不推送到 Notion”

2. 创建父页面并添加 PRD 内容

3. 创建 Epics 数据库，包含所有 Epic

4. 创建 Stories 数据库，并关联到 Epics

5. 创建 Tasks 数据库，并关联到 Stories

6. 创建视图：

   • Stories 的看板视图（按 Status 分组）
   • Epics 的时间线视图（按 Phase 分组）
   • Tasks 的表格视图（默认）

如果 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. **登录由用户负责。**切勿存储或索取生产环境凭据。手动登录时使用 headed 模式。
12. **始终可以在本地保存。**即使 Notion 导出失败，PRD 也会保存在本地。
13. **每次运行只处理一个应用。**不要在同一会话中爬取多个域名。
14. 绝不要将 --user-data-dir 指向真实的 Chrome 配置目录（例如 Mac 上的 ~/Library/Application Support/Google/Chrome，或 Linux 上的 ~/.config/google-chrome）。这可能会损坏 Chrome 配置文件、删除已保存的登录信息，并导致用户的浏览器无法正常使用。务必使用单独的目录，例如 ~/.playwright-profile。