/prd-writer

name: prd-writer
description: |
  輕量版 PRD 撰寫工具 — 適合個人專案、單一功能、無合規/金流/風控需求、單團隊開發，
  快速產出可直接交付工程的「施工藍圖」等級文件。
  當使用者說「幫我寫 PRD」、「產品需求文件」、「寫 spec」、「功能規格」、「write a PRD」、
  「product requirements」、「feature spec」、「產品設計文件」、「需求規格書」時，
  一定要使用這個 skill。即使使用者只是說「幫我整理這個功能的規格」、「把這個想法寫成文件」、
  「我要交一份產品文件給工程團隊」、「寫個規格讓工程師可以直接開工」，也應優先觸發此 skill。
  也適用於使用者要求「補 AC」、「加驗收標準」、「補 Out of Scope」、「補畫面狀態」等
  針對既有 PRD 的強化需求。這個 skill 確保每份 PRD 都包含驗收標準、複雜度標注、
  畫面狀態規格、Out of Scope 邊界，讓工程師能直接開發、QA 能直接寫測試。

  ⚠️ 版本選擇（重要）：本 skill 是「輕量版」，另有「企業版（enterprise-prd-writer）」
  涵蓋權限矩陣、NFR、依賴、合規、Rollout/Rollback、UAT 等。當使用者說「幫我寫 PRD」
  但未指明版本時，先問要用「輕量版（本 skill）」還是「企業版」再開始。判斷提示：
  個人專案 / 單一功能 / 無合規需求 → 輕量版；多團隊 / 金流 / 風控 / 合規 / 需上線維運全鏈路 → 企業版。
  使用者已明確指定版本時直接照做，不必再問。

PRD Writer（輕量版）— 施工藍圖等級的產品需求文件

設計理念

一份好的 PRD 不是「思考文件」，而是「施工藍圖」。判斷標準很簡單：

• 工程師看完能直接開發，不需要回頭問 PM「這個情況怎麼處理？」
• QA 看完能直接寫測試案例，不需要猜測邊界條件
• UAT 時不會出現「我以為是這樣」的分歧

這個 skill 的存在就是為了確保每份 PRD 都達到這個標準。

文件結構

PRD 應包含以下層次，根據產品複雜度可以增減，但核心四件事（AC、複雜度、畫面狀態、Out of Scope）不可省略：

1. 產品概述與目標
2. 功能規格（每個功能點）
   ├── 功能描述
   ├── 規則/邏輯
   ├── 驗收標準（AC）          ← 必要
   └── Out of Scope             ← 必要
3. User Flow / 畫面規格
   ├── 每個畫面的狀態列舉       ← 必要
   ├── 頁面跳轉條件
   └── API 呼叫時機
4. 風險與對策
5. MVP 路線圖
   └── 複雜度標注（非工時估算） ← 必要
6. 成功指標（KPIs）

---

核心標準一：驗收標準（Acceptance Criteria）

每個功能點都必須附上驗收標準。這是 PRD 從「想法」變成「可執行規格」的關鍵。

格式

使用 **Given / When / Then** 三段式，每條 AC 搭配 **Edge Case** 說明：

| 規則 | Given / When / Then | Edge Case | |------|---------------------|-----------| | [規則名稱] | **Given** [前置條件，含具體數值]<br>**When** [觸發事件]<br>**Then** ① [結果 1] ② [結果 2] ③ [結果 3] | • [邊界情境 1]<br>• [邊界情境 2]<br>• [邊界情境 3] |

撰寫原則

寫 AC 的時候，腦中要想著三個人：

1. **工程師**：他需要知道確切的觸發條件和預期行為。「帳戶淨值 ≤ $95,000」比「虧損太多」有用一千倍。 2. **QA**：她需要知道邊界條件。週末跳空怎麼辦？多筆訂單同時觸發呢？這些如果不寫，測試的時候才發現就來不及了。 3. **客服**：他需要知道系統會做什麼，這樣才能回答用戶的問題。「訂單被拒絕，返回 NEWS_WINDOW 錯誤碼」比「系統會處理」清楚太多。

具體要求

• **Given** 中必須包含具體數值或狀態（不是「某個帳戶」，而是「$100,000 帳戶」或「帳戶狀態 = Active」）
• **When** 必須是可觀測的事件（不是「用戶做了什麼不好的事」，而是「即時淨值 ≤ $95,000」）
• **Then** 使用編號列出所有系統行為，順序即執行順序
• **Edge Case** 列出至少 2-3 個邊界情境，特別是：
• 兩個規則同時觸發時的優先級
• 時區/日期邊界的處理
• 資料不完整或異常時的降級行為

範例

| 日虧損 -5% | **Given** 當日開盤淨值 = $100,000
             **When** 即時淨值（含未實現損益）≤ $95,000
             **Then** ① 所有持倉立即市價平倉
                     ② 當日禁止新開倉
                     ③ 挑戰狀態 → Failed
                     ④ 發送失敗通知 Email + Dashboard 彈窗 |
             • 跨日隔夜持倉的跳空缺口：以新日開盤淨值重新計算基準
             • 多筆訂單同時觸發：平倉順序以 ticket ID 遞增為準
             • 週末跳空低於 -5%：以週一開盤第一個 tick 觸發 |

---

核心標準二：複雜度標注（取代工時估算）

規則

PRD 正文中**絕對不要寫工時估算**（「3-5 人天」、「0.5 人天」這類數字）。原因：

• 工時估算是工程師的職責。PM 在 PRD 裡寫了數字，工程師會覺得被預設了結論，容易產生摩擦。
• 不同團隊、不同技術棧，同樣的功能開發時間可以差 3-5 倍。PRD 裡的數字很快就會過時。
• 更好的做法是標注「技術複雜度」，讓工程師在 Sprint Planning 時自行估算。

格式

使用三級制：

| 等級 | 含義 | 何時使用 | |------|------|---------| | **低** | 邏輯單純、無外部依賴、可獨立完成 | CRUD 操作、簡單 UI 調整、參數配置 | | **中** | 涉及多個模組協作或中等演算法 | API 整合、狀態機、基礎數據分析 | | **高** | 需要新架構、ML 模型、或跨系統協調 | 即時計算引擎、機器學習、分散式系統 |

在文件中的呈現

在路線圖或分期策略中這樣使用：

MVP：基礎相關性矩陣 hardcode。技術複雜度：低。
Phase 2：30 日滾動矩陣 + 行為偵測。技術複雜度：中。
Phase 3：即時淨曝險計算 + ML 模型。技術複雜度：高。

不要寫成：~~「開發成本 3-5 人天」~~

---

核心標準三：畫面狀態規格

每個 User Flow 畫面都需要一張完整的狀態表。這是前端工程師和 QA 最依賴的東西——如果只寫了「正常狀態」的行為，上線後第一天就會收到「頁面一片空白」的 bug report。

必須列舉的狀態

每個畫面至少涵蓋以下 6 種狀態：

| 狀態 | 說明 | 為什麼重要 | |------|------|-----------| | **空白狀態** | 沒有任何數據時的顯示 | 新用戶第一次進來就會看到這個 | | **載入中** | 數據正在獲取 | 沒有這個，用戶會以為頁面壞了 | | **正常** | 有數據、一切正常的主要狀態 | 這是大家通常唯一會寫的狀態 | | **成功** | 操作完成的反饋 | 用戶需要確認「我的動作生效了」 | | **失敗/錯誤** | 操作失敗或系統異常 | 沒有錯誤處理 = 用戶失去信任 | | **邊界狀態** | 產品特有的特殊狀態 | 例如「凍結」、「待審核」、「超時」 |

每個狀態需要三個維度

| 欄位 | 內容 | 範例 | |------|------|------| | **規格** | 這個狀態下畫面長什麼樣 | 「骨架屏 + P&L 佔位動畫」 | | **觸發 / 跳轉條件** | 什麼情況進入這個狀態、離開時去哪裡 | 「WS 斷線或 REST 5xx 時觸發」 | | **API 呼叫** | 這個狀態對應哪些 API 請求 | 「GET /challenge/{id}/status」 |

範例表格

| 狀態 | 規格 | 觸發 / 跳轉 | API 呼叫 |
|------|------|-------------|----------|
| 空白狀態 | 引導卡片 + 下載連結 | 帳戶 Active 且 trade_count = 0 | GET /status → trades: [] |
| 載入中 | 骨架屏（Skeleton） | 頁面初始化 / WS 重連 | WS 訂閱即時數據 |
| 正常 | 即時 P&L + Drawdown 儀表板 | trade_count ≥ 1 | WS 推送（每 tick） |
| 成功 | 進度 100%，「目標已達成！」 | equity ≥ target | WS event: target_met |
| 失敗 | 紅色覆蓋 → 跳轉失敗頁 | drawdown 觸發 | WS event: failed |
| 錯誤 | Toast + 指數退避重試 | WS 斷線 / 5xx | 1s→2s→4s→8s→16s→30s |

錯誤處理特別注意

錯誤處理需要具體到重試策略：

• **指數退避**：寫出具體的重試間隔（1s → 2s → 4s → 8s → 16s → 30s）
• **降級策略**：哪些 API 是關鍵路徑（失敗就阻塞頁面）、哪些不是（失敗就降級為純文字）
• **最大重試次數**或**超時時間**

---

核心標準四：Out of Scope

每個功能區塊的末尾都需要明確的 Out of Scope 說明。這不是「偷懶不做」，而是主動管理期望——讓所有利害關係人都清楚「這個版本不做什麼」。

為什麼這很重要

沒有 Out of Scope 的 PRD，工程師會自行腦補邊界，設計師會自行延伸功能，利害關係人會在 UAT 時問「我以為這個會有？」。寫了 Out of Scope，所有歧義在開發前就解決了。

格式

在每個功能區塊的 AC 表格之後，加上一行 Out of Scope 摘要：

**Out of Scope（[功能名]）：**
① [不做的事 1]
② [不做的事 2]
③ [不做的事 3]

分期產品的 In/Out of Scope 表格

如果產品有多期開發（MVP → Phase 2 → Phase 3），用表格明確標示每期的邊界：

| 階段 | 包含（In Scope） | 不包含（Out of Scope） | |------|-----------------|----------------------| | **MVP** | • 功能 A<br>• 功能 B | • 進階功能 X<br>• ML 模型 | | **Phase 2** | • 功能 C<br>• 功能 D | • 全平台擴展<br>• 自動化決策 | | **Phase 3** | • 進階功能 X<br>• ML 模型 | • 跨平台聯防<br>• 預測性分析 |

這張表格讓所有人一眼看到「什麼在哪一期做」，避免 Phase 2 的功能被拉進 MVP。

---

後台安全控制（基礎版）

**觸發條件：** 只要 PRD 涉及**後台 / admin panel / 有登入的管理介面**，就必須檢查以下清單。純前台展示、無登入的功能可標 `N/A（無後台）`。

每項給定明確規格，不要只寫「要做好安全」。附上建議預設值，可直接用或改。

| 控制 | 必須定義 | 建議預設值 | |---|---|---| | **IP 白名單** | 後台只允許哪些網段登入（公司/VPN） | 僅限公司固定 IP + VPN 網段，其餘一律擋 | | **地理封鎖** | 是否封鎖非營運國家的登入來源 | 封鎖營運國以外的登入，例外走申請 | | **2FA / GA 綁定** | 是否強制、用哪種、何時綁定 | 全後台帳號強制 TOTP（Google Authenticator），首次登入強制綁定 | | **登入錯誤凍結** | 連續失敗幾次、凍結多久、是否告警 | 連續 5 次失敗 → 凍結 30 分鐘 + 通知本人與安全團隊 | | **Session 政策** | 逾時、閒置登出、同帳號多裝置 | 閒置 15 分鐘登出、絕對逾時 8 小時、同帳號新登入踢舊 session | | **高風險操作二次驗證** | 哪些操作要再驗一次 | 提領、改參數、改權限等操作需再輸入一次 OTP | | **稽核紀錄** | 記什麼、留多久、能否竄改 | 記錄操作者/時間/內容/來源 IP，寫入不可竄改 log，留存符合當地金融法規 |

> 這是**基礎版**。若涉及金流/風控/合規的正式後台，改用企業版 enterprise-prd-writer， > 它額外涵蓋 Maker-Checker 四眼原則、覆核門檻與定期權限盤點。

---

撰寫流程

當使用者要求撰寫 PRD 時，按以下順序進行：

Step 1：釐清需求範圍

先問清楚：

• 這個產品/功能解決什麼問題？
• 目標用戶是誰？
• 有沒有競品或參考對象？
• 預計分幾期交付？
• 誰會讀這份