Bug Report 撰寫 SOP — 8 個欄位讓開發 30 秒看懂、不被退回
被開發退回「無法重現」、「不是 bug」、「資訊不足」三次以上的 bug，那是你 report 寫得爛，不是開發不配合。一份好的 bug report 讓開發 30 秒讀懂 + 5 分鐘重現。
一份 bug report 該有的 8 個欄位
| 欄位 | 必填 | 用途 |
|---|---|---|
| Title | ✓ | 一句話總結 |
| Steps to Reproduce | ✓ | 編號重現步驟 |
| Expected Result | ✓ | 應該怎樣 |
| Actual Result | ✓ | 實際怎樣 |
| Environment | ✓ | OS / Browser / Version / Build |
| Severity / Priority | ✓ | 影響範圍與優先級 |
| Attachments | ✓ | Screenshot / Video / Log / HAR |
| Related | — | 相關 PR / 之前的 bug / spec |
8 個寫好 → 開發 30 秒看完知道要做什麼。少一個就會被退回問。
Title 怎麼寫
公式：[模組] <行為>，<前提下> 應該 <預期> 但 <實際>
爛例子： - 「登入有問題」 - 「按鈕沒反應」 - 「畫面跑掉」
好例子： - 「[Login] 使用者連續輸錯密碼 5 次後，第 6 次仍能正常嘗試（應被鎖定 15 分鐘）」 - 「[Checkout] iOS Safari 17 上，按『確認結帳』按鈕第二次點擊才有反應」 - 「[Profile] 上傳超過 5MB 的頭像時，前端無錯誤提示但後端 500」
寫到能在 stand-up 上唸出來別人就懂，title 就合格。
Steps to Reproduce — 重點中的重點
寫死，不要寫泛指。
爛例子：
1. 進入購物車
2. 加入一些商品
3. 結帳
好例子：
1. 用瀏覽器開 https://staging.example.com
2. 用以下帳號登入：
- email: [email protected]
- password: Test@123456
3. 進入「商品列表」/products/
4. 將「商品 A (id: sku-001)」加入購物車 × 2
5. 將「商品 B (id: sku-099)」加入購物車 × 1
6. 點右上「購物車（3）」
7. 點「前往結帳」
8. 選「信用卡」付款
9. 輸入測試卡號 4111 1111 1111 1111 / 12/30 / 123
10. 點「確認付款」
標準：把這份 steps 交給一個沒接觸過產品的人，他能跑出同樣結果。
Steps 常見錯誤
- 跳步驟 — 「然後就 fail 了」中間少了 3 步
- 沒寫 test data — 「輸入 email」沒寫哪個 email
- 預設知識 — 「用 admin 進入後台」沒寫怎麼進
- 多個 bug 寫一個 report — 「另外順便提一下…」開新的
- 寫概念而非操作 — 「驗證搜尋功能」要寫具體點什麼、輸入什麼
Expected vs Actual — 一定要分開
爛例子：
結帳後沒有顯示成功頁面，反而跳出錯誤。
好例子：
Expected:
- 點「確認付款」後 → 跳轉到 /order/<id>/success
- 頁面顯示「訂單建立成功」+ 訂單編號
- 寄送確認 email 到 [email protected]
Actual:
- 點「確認付款」後 → 停留在原頁面
- 跳出紅色錯誤訊息：「系統忙碌中，請稍後再試」
- 後端 log 顯示 500 InternalServerError
- 未收到確認 email
寫法：每個 expected 對應一個 actual，數量盡量一致。
Environment — 越詳細越好
開發測自己機器跑不出來，就是因為環境不同。至少要的：
- OS: macOS 14.3 / Windows 11 22H2 / iOS 17.4
- Browser: Chrome 124.0.6367.78 / Safari 17.4
- App version: v2.4.1 (build 2024-06-09)
- Backend: staging-api-v3 (commit a1b2c3d)
- Network: WiFi / 4G / VPN
- Account: [email protected] (paid plan / 台灣 / 已驗證)
- 時間: 2026-06-09 14:32 UTC+8
Mobile bug 特別要附： - 裝置型號（iPhone 13 Pro / Pixel 8） - 螢幕方向（直 / 橫） - 是否有 dark mode - 是否啟用 VPN
Severity vs Priority
很多人搞混。
| 欄位 | 定義 | 例子 |
|---|---|---|
| Severity | 對使用者的傷害 | 資料遺失（critical）、UI 跑版（low） |
| Priority | 修復急迫度 | 影響營收（P0）、極少觸發（P3） |
重要區別： - Severity critical 不一定 P0：例如「會掉資料但只有 1% 流量觸發，且有 workaround」可能 P1 - Severity low 也可能 P0：例如「首頁 logo 變形」但是公司 brand 大事
我的建議分類
Severity:
S1 Critical - 系統當機、資料遺失、安全漏洞
S2 High - 主要功能無法使用
S3 Medium - 次要功能異常、有 workaround
S4 Low - UI 小瑕疵、文案錯字
Priority:
P0 Now - 阻擋發版、需馬上修
P1 This sprint
P2 Next sprint
P3 Backlog - 修不修都行
Attachments — 證據說話
不要只貼一張 screenshot。完整的證據是：
- Screenshot — 整個畫面、含 URL、含時間 → 一張
- Video — 重現過程 30 秒以內 → 一支（Loom、QuickTime、CleanShot）
- Console log — 瀏覽器 DevTools → Console 全選複製
- Network log — DevTools → Network export HAR
- Backend log（如果你拿得到）→ 失敗時間區間的 log
video 是金標準。能用 video 解決 50% 的「無法重現」退回。
工具推薦
| 工具 | 用途 |
|---|---|
| Loom / CleanShot | 螢幕錄影 + 上傳分享連結 |
| Chrome DevTools → 三點 → More tools → Recorder | 直接錄成可重播的 recording |
| BrowserStack | 跨平台跨瀏覽器重現 |
| Sentry / LogRocket | 自動錄影 + session replay（要前端設定） |
完整範例（直接 copy 改）
# [Checkout] iOS Safari 17 上連點「確認付款」會重複建立訂單
## Severity / Priority
S1 Critical / P0 — 影響使用者收費，每天可能發生
## Steps to Reproduce
1. iOS 17.4 Safari 開 https://staging.example.com
2. 登入 [email protected] / Test@123456
3. 加入「商品 A (sku-001)」到購物車
4. 進入結帳頁
5. 選「信用卡」、輸入測試卡 4111 1111 1111 1111
6. 在「確認付款」按鈕**快速連點兩次**（< 1 秒間距）
7. 等待 5 秒
## Expected
- 第二次點擊應被忽略（按鈕應 disable 或顯示 loading）
- 只建立 1 筆訂單
## Actual
- 兩次點擊都被接受
- 建立 2 筆相同訂單（order #12345 + #12346）
- 信用卡被扣款兩次
## Environment
- OS: iOS 17.4
- Device: iPhone 13 Pro
- Browser: Safari 17.4
- App version: v2.4.1 (build #2026-06-09-001)
- Backend: staging-api-v3 (commit a1b2c3d)
- Account: [email protected]
- 時間: 2026-06-09 14:32 UTC+8
## Attachments
- [影片重現](https://loom.com/share/xxx) (15 秒)
- [Network HAR export](attachments/network.har)
- [Console log](attachments/console.txt)
- Screenshot: `screenshot-2026-06-09.png`
## Related
- 類似 bug 於 2025 Q4：#3421（Android Chrome）
- 相關 spec：[結帳防重複點擊](https://confluence.example.com/checkout-double-click)
- 暫時 workaround：使用者刷新頁面、客服手動退款一筆
開發退回時常見原因 vs 解決
| 退回理由 | 真正原因 | 解決 |
|---|---|---|
| 「無法重現」 | Steps 太抽象 | 加 test data + 環境細節 + video |
| 「這是 spec」 | 沒對到 spec | 附 spec 連結 + 標明差異 |
| 「不是 bug」 | Expected 跟 dev 認知不同 | 拉 PM 三方確認 |
| 「資訊不足」 | 缺 console / network log | 補上 |
| 「我這邊 OK」 | 環境不同 | 詳列 OS / browser / build / account |
工具差異不大，內容結構不變
Jira / Linear / GitHub Issues / Notion — 工具決定樣式，8 個欄位永遠都要寫。
範本可以做成：
- Jira → Issue template
- GitHub →
.github/ISSUE_TEMPLATE/bug.yml - Notion → Database template
一次設好、團隊終身受益。
最後
Bug report 是 QA 對外的名片。寫得好的人，開發看到你的 ticket 會優先處理。寫得爛的人，再急的 bug 也被擱著。前期多花 5 分鐘寫好，後期省的不只 50 分鐘。