點樣寫好嘅 Bug 報告（俾 AI 或者開發者）

一份好嘅 bug 報告，可以令另一個人（開發者或者 AI）見到你見到嘅同一個問題，而唔使再問你任何嘢。佢需要一個具體標題、重現問題嘅確切步驟、你預期嘅結果、實際發生嘅結果、原文照抄嘅任何錯誤訊息，以及發生嘅位置：邊一頁、邊個瀏覽器、邊部裝置、邊位用戶。每份報告只寫一個 bug，如果有幫助就附上截圖。

大部分 bug 理解問題所花嘅時間，遠多過修復所花嘅時間。一份清晰嘅報告可以令理解呢部分變得容易。用 AI 工具時尤其重要：AI 唔可以就「結賬好怪」問你一條跟進問題，所以佢只會猜，而猜錯就可能弄壞其他嘢。

範本

複製以下內容並填寫：

標題：[邊度出咗乜問題] — 例如「預約表格拒絕晚上六點後嘅時間」

重現步驟：
1. ...
2. ...
3. ...

預期：[應該發生乜]
實際：[實際發生咗乜]

錯誤訊息：[確切文字，如有]
位置：[頁面／網址、瀏覽器、裝置、以邊個用戶登入]
發生頻率：[每次／有時／一次]
截圖或錄影：[已附上]

本指南其餘部分會解釋每個部分。

第一步：先重現

寫報告之前，先試吓令 bug 再次出現。咁你就會知道邊啲步驟係關鍵，以及係咪每次都會發生。

• 由乾淨狀態開始：重新整理，或者登出再登入。
• 記低每一下點擊同每樣你輸入嘅嘢。
• 試吓搵出觸發問題嘅最短路徑。
• 試吓第二個瀏覽器或者帳戶。如果只係某一位用戶先出現，呢個就係一個重要線索。

想了解多啲，可以睇點樣除錯 AI 建立嘅 App。

第二步：寫具體標題

標題要講明乜嘢出錯，以及喺邊度出錯，令掃視清單嘅人知道係邊個 bug。

第三步：列出確切步驟

將步驟編號。要寫得直接：邊一頁、按邊粒掣、輸入咗乜。

1. 以客戶身份登入（測試帳戶：customer@example.com）。
2. 將「入門套件」加入購物車。
3. 輸入折扣碼 WELCOME10，然後點擊套用。
4. 點擊結賬。

只寫「試吓用折扣碼結賬」，會漏去一啲經常好重要嘅細節：邊個用戶、邊件產品、邊個折扣碼，以及折扣碼係咪先套用。

第四步：預期對比實際

呢部分係報告嘅核心。兩者都要寫，因為兩者之間嘅差異就係 bug。

• **預期：**結賬頁面打開，總額已經顯示 10% 折扣。
• **實際：**按鈕轉咗一秒鐘嘅加載圈，然後冇任何反應。冇折扣碼時，結賬可以正常進行。

冇「預期」，讀者可能唔知道呢個行為係錯嘅。冇「實際」，佢哋又唔知道要留意乜。

第五步：確切照抄錯誤

錯誤訊息係搵出原因最快嘅途徑。將佢哋以文字形式複製，逐字逐句，唔好改寫。

喺邊度搵到佢哋：

• **喺螢幕上：**App 顯示嘅任何訊息。
• 瀏覽器主控台：打開開發者工具（F12，或者右鍵 → 檢查），去主控台標籤睇紅色嘅行。
• **網絡標籤：**喺開發者工具入面搵到失敗嘅請求，記低佢嘅網址同狀態碼（例如 POST /api/checkout → 500）。
• 伺服器日誌，如果你有權限睇。

一行好似 TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 嘅訊息，通常會直接指向問題所在。

第六步：加入背景資料

• **位置：**頁面網址、運行環境（預覽、測試或正式環境）。
• **邊個：**邊位用戶或者角色，例如管理員、成員、未登入。
• 裝置同瀏覽器：「iPhone 上嘅 Safari」同「Windows 上嘅 Chrome」可能有分別。
• **資料：**任何記錄嘅特別之處，例如好長嘅文字、特殊字元、大量項目。
• 幾時開始：「自從昨日改咗折扣碼之後」係好有用嘅資料。
• **發生頻率：**每次，或者十次之中一次。

第七步：顯示出嚟

一張圈出問題位置嘅截圖，或者一段短片錄影，可以消除歧義，尤其係版面問題。如果你嘅 AI 工具接受圖片，就附上一張。裁走任何私隱內容，包括金鑰同其他人嘅資料。

為 AI 建置工具寫 bug 報告

同一個結構亦可以當成 prompt 用。以下兩點會有幫助：

• 講明乜嘢唔可以改變，免得修正又引致新問題。
• 要求佢核實修正，而唔係只係寫完就算。

以客戶身份登入，購物車有「入門套件」，並已套用折扣碼 WELCOME10，點擊結賬冇任何反應。預期：結賬頁面打開，總額減 10%。實際：短暫加載圈，然後冇嘢發生。網絡標籤顯示 POST /api/checkout 返回 500。冇折扣碼時結賬正常。找出原因並修好，同時唔好改變冇折扣碼訂單嘅價格計算方法。然後用百分比折扣碼、固定金額折扣碼同冇折扣碼，分別核實結賬功能。

如果你唔確定原因，可以先要求診斷：

暫時唔好改程式碼。根據呢份報告，可能嘅原因有邊啲？每個原因要點樣確認？

常見錯誤

• **「壞咗。」**冇步驟、冇預期結果，冇嘢可以跟進。
• **一份報告入面有幾個 bug。**有啲會被修好，有啲會被遺漏。
• 改寫過嘅錯誤訊息。「某個 undefined 嘅嘢」會隱藏最有用嘅部分。
• **漏咗用戶或者角色。**好多 bug 只影響管理員，或者只影響新用戶。
• 只描述你想要嘅修正方法（「加一個 null 檢查」），而唔係描述問題。
• 喺截圖或者貼上嘅日誌中分享機密資料。

檢查清單

• 我已經重現咗 bug，並搵到最短步驟。
• 標題講明乜嘢出錯，以及喺邊度出錯。
• 步驟有編號，並且寫得直接。
• 預期同實際都有寫明。
• 錯誤訊息照抄，包括失敗嘅請求同狀態碼。
• 包括頁面、環境、用戶、裝置同瀏覽器。
• 我寫明咗發生頻率同幾時開始。
• 已附上截圖或錄影，並且已移除私人資料。
• 每份報告只寫一個 bug。

向 Mythex 嘅 agent 報告 bug

喺 Mythex 專案入面，報告就係 prompt。以下幾項功能會有幫助：

• 附上截圖，可以係預覽或者錯誤畫面，每則訊息最多 5 個檔案。
• /fix 會令 agent 專注修復 bug；計劃模式則容許佢喺編輯之前先調查。
• /test 會令 agent 喺預覽中重現流程，並報告佢見到嘅嘢。
• 還原到呢個點可以撤銷令情況變差嘅修正。

文件中嘅用 prompt 除錯頁面，使用同樣嘅步驟／預期／實際結構。至於圍繞佢嘅修正與核實循環，可以睇點樣反覆改進 AI 建立嘅 App。

常見問題