# Milktea Skills Debug

> 供執行開發任務的 Claude 或 Codex 子 Agent 按需載入。遇到非預期錯誤、錯誤行為、不穩定測試或效能退化時，讀取既有 Spec、planning 文件、CONTEXT.md 與 ADR，重現問題、驗證根因、在正確接縫建立回歸測試或記錄替代驗證、完成最小修正，再繼續原任務。不處理 TDD 刻意產生的 Red 或尚未完成造成的預期失敗。

- Skill: `royalmilkteamaster/milktea-skills-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add royalmilkteamaster/milktea-skills-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/royalmilkteamaster/milktea-skills-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: RoyalMilkteaMaster (https://skillmd.com/u/royalmilkteamaster)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/royalmilkteamaster/milktea-skills-debug

---


# Milktea Skills Debug

在目前派工範圍內找出根因、修正並驗證。完成後繼續原任務。

## 使用方式

- 由正在工作的 Developer 遇到非預期失敗時按需載入；不由 Coordinator 預載，也不另外建立 Debug Agent。

## 觸發條件

使用於：

- 非預期例外、錯誤輸出或行為。
- 原本通過的測試突然失敗。
- 不穩定、競態或偶發問題。
- 可量測的效能退化。

不得使用於：

- TDD 刻意建立的 Red。
- 功能尚未完成造成的預期失敗。
- Ticket 已明列的暫時狀態。

## 前提

讀取目前派工、Ticket、Spec、`docs/planning/requirements.md`、`docs/planning/architecture.md`、`CONTEXT.md`、相關 ADR、變更 Diff 與既有測試。先確認問題屬於本次工作，不把無關舊問題混入。

回報命令、輸出、Log、Trace 或擷取檔前，先移除密鑰、Token、Cookie、授權標頭與其他敏感資料；遮蔽後不足以判斷時再請使用者處理。

## 除錯流程

1. 記錄預期、實際、環境、輸入與完整錯誤。
2. 建立能判定該問題的快速回饋迴圈：優先使用既有測試，其次使用最小測試、CLI／HTTP 重現、UI 自動化、Trace、Profiler 或 Bisect。
3. 實際執行回饋迴圈，確認捕捉的是同一問題；偶發問題先提高重現率。
4. 逐步移除輸入、設定、資料與呼叫鏈，保留最小重現案例。
5. 產生 2–5 個可推翻假設，依證據排序；一次只驗證一個變因。
6. 優先使用 Debugger 或只在能區分假設的位置加入觀測；臨時 Log 使用唯一 `[DEBUG-識別碼]`，不得大量亂灑。輸出預設送到 Console；必須存檔時放在作業系統暫存目錄，不寫入 Repository 或正式 `<專案名稱>_data/logs/`。
7. 效能問題先建立基準並使用 Profiler、Query Plan 或 Bisect；不得憑感覺最佳化。
8. 只有證據能解釋完整症狀時，才確認根因。

無法建立回饋迴圈時停止猜測，列出已嘗試方法，向使用者要求缺少的 Log、Trace、輸入、環境存取或臨時觀測權限。一般技術判斷自行完成，不為例行步驟打斷使用者。

## 修正與驗證

1. 選擇符合既有需求與架構限制的最小修正。
2. 存在能重現真實問題的正確測試接縫時，使用 `/milktea-agents-skills-for-claude:milktea-skills-tdd` 把最小重現轉成 Red 回歸測試；沒有正確接縫時記錄原因，保留可重現的替代驗證，不建立無法捕捉真實問題的測試。
3. 修改程式，使回歸測試或替代驗證通過。
4. 重跑最小重現、原始情境、相關測試，以及 Spec、專案指令或相關程式庫要求的驗證。
5. 加入臨時觀測的除錯 Agent 必須在回到原任務前，移除所有 Debug 程式碼、暫存 Log 檔案與拋棄式 Harness；只保留正式回歸測試。

不得降低斷言、停用測試、吞掉例外、擴大 Ticket 範圍或以重試掩蓋根因。

## 邊界

- 不建立新 Ticket、Task、Spec 或需求。
- 不重新調用 `grill-me` 或架構 Skill。
- 修正若必須改變已核准需求、公開介面、資料模型或架構限制，停止修改並回報派工者，等待使用者裁決。
- 不自行安裝、建立或切換環境與套件。
- 完成後回到原任務；不啟動或替代獨立 Review。

## 回報

回報：

- 症狀與重現指令。
- 已確認根因與排除證據。
- 修正內容與回歸測試，或沒有正確接縫時的理由與替代驗證。
- 驗證指令、退出碼與關鍵輸出。
- 已清除的臨時觀測。
- 未解風險或需要使用者裁決的範圍變更。

把精簡證據交給 Implement Coordinator，併入 Developer 的 Ready for Review 回報；不另建 Debug 報告，也不寫入 Ticket。