Prd Writer

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 [前置條件，含具體數值]When [觸發事件]Then ① [結果 1] ② [結果 2] ③ [結果 3] | • [邊界情境 1]• [邊界情境 2]• [邊界情境 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• 功能 B | • 進階功能 X• ML 模型 | | Phase 2 | • 功能 C• 功能 D | • 全平台擴展• 自動化決策 | | Phase 3 | • 進階功能 X• ML 模型 | • 跨平台聯防• 預測性分析 |

這張表格讓所有人一眼看到「什麼在哪一期做」，避免 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：釐清需求範圍

先問清楚：

• 這個產品/功能解決什麼問題？
• 目標用戶是誰？
• 有沒有競品或參考對象？
• 預計分幾期交付？
• 誰會讀這份文件？（工程師？設計師？高層？）

Step 2：建立文件骨架

先產出目錄結構，讓使用者確認涵蓋範圍是否正確。

Step 3：填充內容

按章節順序撰寫，每個功能點都確保包含：

• 功能描述（做什麼、為什麼）
• 規則/邏輯表格
• AC 驗收標準表格（Given/When/Then + Edge Case）
• Out of Scope

Step 4：補完 User Flow

為每個關鍵畫面建立狀態表（6 種狀態 × 3 個維度）。

Step 5：路線圖與複雜度

用「技術複雜度：低/中/高」標注，不使用工時數字。如果是分期產品，建立 In/Out of Scope 邊界表。

Step 6：驗證檢查

完成後做最後一輪檢查：

• [ ] 每個功能都有 AC 嗎？
• [ ] 每個 AC 的 Given 都有具體數值嗎？
• [ ] 每個功能都有 Out of Scope 嗎？
• [ ] 每個畫面都列舉了 6 種狀態嗎？
• [ ] 錯誤處理有具體的重試策略嗎？
• [ ] 沒有任何工時估算數字（人天）嗎？
• [ ] 分期邊界是否明確（In/Out of Scope 表格）？

---

語言與格式偏好

• 預設使用繁體中文撰寫，專有名詞保留英文
• 如果使用者要求雙語，中文為主、英文為輔（用 span class 或括號區分）
• 表格優先於長段落——工程師掃描表格比讀段落快 10 倍
• 重要數值使用粗體或色彩標記
• 每個 section 開頭用一句話解釋「這個章節解決什麼問題」

輸出格式

根據使用者需求，可輸出為：

• HTML：適合線上閱讀和分享，支援互動元素
• Word (.docx)：適合正式交付，使用 docx skill
• Markdown：適合版本控制和 Wiki

預設輸出 HTML（最佳閱讀體驗），但如果使用者提到「Word」、「文件」、「docx」則切換為 Word 格式。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: skinnerlee1225
• Source: skinnerlee1225/enterprise-prd-toolkit
• License: MIT
• Homepage: https://skinnerlee1225.github.io/enterprise-prd-toolkit/

Install and usage instructions live in the source repository linked above.