如何撰寫好的錯誤回報（給 AI 或開發者）

好的錯誤回報，能讓另一個人（開發者或 AI）看到你看到的同一個問題，而且不需要再問你任何問題。它需要一個具體的標題、重現問題的精確步驟、你預期會發生什麼、實際發生了什麼、逐字複製的錯誤訊息，以及問題發生的位置：哪個頁面、哪個瀏覽器、哪個裝置、哪位使用者。每份回報只描述一個錯誤，有幫助的話再附上截圖。

大多數錯誤花在理解上的時間，比修正的時間還要長。清楚的回報能省去理解的部分。這在使用 AI 工具時尤其重要：AI 無法追問你「結帳怪怪的」到底是什麼意思，所以它只能猜，而錯誤的猜測可能會弄壞其他東西。

範本

複製這份範本並填寫：

標題：[什麼東西壞了、在哪裡] — 例如「預約表單在晚上 6 點後拒絕時間」

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

預期：[應該發生什麼]
實際：[實際發生了什麼]

錯誤訊息：[確切文字，如果有的話]
位置：[頁面／網址、瀏覽器、裝置、以哪位使用者身分登入]
發生頻率：[每次／有時／只有一次]
截圖或錄影：[已附上]

本指南的其餘部分會說明每個部分。

步驟一：先試著重現

在寫之前，先試著讓錯誤再次發生。你會知道哪些步驟是關鍵，以及它是否每次都會發生。

• 從乾淨的狀態開始：重新整理，或登出後再登入。
• 記下每一次點擊和你輸入的每一樣東西。
• 嘗試找出觸發錯誤的最短路徑。
• 換另一個瀏覽器或帳號試試。如果只有某一位使用者會遇到，那是很大的線索。

想了解更多，請參閱如何除錯 AI 建置的應用程式。

步驟二：寫出具體的標題

標題應該說明什麼東西壞了、在哪裡，這樣有人在瀏覽清單時，就能知道這是哪一個錯誤。

步驟三：列出精確的步驟

把步驟編號。寫得要具體：哪一頁、哪一個按鈕、你輸入了什麼。

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

只寫「試著用折扣碼結帳」，會漏掉那些常常很關鍵的細節：是哪位使用者、哪個產品、哪個折扣碼，以及折扣碼是否先被套用。

步驟四：預期與實際

這是錯誤回報的核心。兩者都要寫，因為兩者之間的差異就是錯誤。

• 預期： 結帳頁面開啟，總額中顯示 10% 的折扣。
• 實際： 按鈕顯示一秒鐘的載入中圖示，然後什麼都沒發生。沒有折扣碼時，結帳可以正常運作。

如果沒有「預期」，讀者可能不知道這個行為是錯的。如果沒有「實際」，他們就不知道該找什麼。

步驟五：逐字複製錯誤訊息

錯誤訊息是找到原因最快的途徑。請把它們以文字形式逐字複製，不要改寫。

到哪裡找：

• 畫面上： 應用程式顯示的任何訊息。
• 瀏覽器主控台： 開啟開發者工具（F12，或右鍵 → 檢查），查看 Console 分頁中的紅色行。
• Network 分頁： 在開發者工具中找出失敗的請求，並記下它的網址與狀態碼（例如 POST /api/checkout → 500）。
• 伺服器日誌，如果你有權限查看。

像 TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 這樣的一行訊息，通常能直接指向問題所在。

步驟六：補充背景資訊

• 位置： 頁面網址、環境（預覽、測試或正式）。
• 對象： 哪位使用者或角色：管理員、一般會員、未登入。
• 裝置與瀏覽器：「iPhone 上的 Safari」與「Windows 上的 Chrome」可能差異很大。
• 資料： 與該筆紀錄有關的任何不尋常之處，例如非常長的文字、特殊字元、大量的項目。
• 何時開始：「昨天修改折扣碼之後開始」非常有價值。
• 發生頻率： 每次都會，還是十次裡有一次。

步驟七：把它展示出來

用圈出問題的截圖，或一小段螢幕錄影，可以消除歧義，特別是版面相關的錯誤。如果你的 AI 工具支援圖片，就附上一張。截圖前請裁掉任何隱私內容，包括金鑰和其他人的資料。

為 AI 建置工具撰寫錯誤回報

同樣的結構也可以當成提示使用。有兩個補充會很有幫助：

• 說明哪些東西不能改變，這樣修正不會引發新的問題。
• 要求它驗證修正結果，而不只是寫出修正。

以客戶身分登入，購物車中有「入門套件」並已套用折扣碼 WELCOME10，然後點擊 結帳 沒有反應。預期：結帳頁面開啟，總額折扣 10%。實際：短暫的載入圖示，然後什麼都沒有。網路分頁顯示 POST /api/checkout 回傳 500。沒有折扣碼時結帳可以正常運作。請找出原因並修正，同時不要改變沒有折扣碼的訂單的價格計算方式。修正後，請用百分比折扣碼、固定金額折扣碼，以及不使用折扣碼，分別測試結帳。

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

先不要修改程式碼。根據這份回報，可能的原因有哪些？每一項分別要用什麼來確認？

常見錯誤

• 「它壞了。」 沒有步驟、沒有預期結果，沒有任何可以行動的內容。
• 同一份回報裡放好幾個錯誤。 有些會被修好，其他的則會被遺忘。
• 錯誤訊息被改寫。「某個 undefined 的東西」會把真正有用的部分藏起來。
• 漏掉使用者或角色。 很多錯誤只會影響管理員，或只影響新使用者。
• 只描述你想要的修正方式（「加一個 null 檢查」），而不是描述問題本身。
• 在截圖或貼上的日誌中分享機密。

檢查清單

• 我已經重現了這個錯誤，並找到最短的步驟。
• 標題說明了什麼東西壞了、在哪裡。
• 步驟有編號，而且寫得具體。
• 同時寫出了預期與實際結果。
• 錯誤訊息已逐字複製，並附上失敗的請求與狀態碼。
• 已包含頁面、環境、使用者、裝置與瀏覽器。
• 我說明了發生頻率與開始的時間。
• 已附上截圖或錄影，並移除私人資料。
• 每份回報只包含一個錯誤。

向 Mythex 的代理程式回報錯誤

在 Mythex 專案中，回報內容本身就是提示。以下幾項功能會有幫助：

• 附上截圖，可以是預覽或錯誤畫面，每則訊息最多 5 個檔案。
• /fix 會讓代理程式專注於修正錯誤；**計畫（Plan）**模式則讓它在編輯前先進行調查。
• /test 會讓代理程式在預覽中直接重現流程，並回報它看到的內容。
• **還原到此處（Revert to this point）**可以撤銷讓情況變得更糟的修正。

文件中的以提示進行除錯頁面，使用的也是同樣的步驟／預期／實際結構。至於圍繞它的修正與檢查循環，請參閱如何反覆修改 AI 建置的應用程式。

常見問題