Harness retro
找出過去工作階段出了哪些問題，並調整設定以防止再次發生。每個發現都必須指向對話記錄中的證據。未經使用者核准，絕不套用任何變更。
1. 挖掘對話記錄
挖掘器是一個僅使用標準函式庫的 Python 腳本，與此檔案位於同一目錄。使用 -I 選項執行它。將輸出寫入工作階段的暫存區，如果沒有暫存區，則寫入臨時目錄：
python3 -I <此技能基礎目錄>/scripts/mine.py [PATH] [--since 30d] --out <scratchpad>/retro.json
- 若不指定 PATH，則會挖掘目前工作目錄所屬的專案。若要挖掘不同專案，請提供其工作目錄路徑，或使用
--project=<key>指定~/.claude/projects下的資料夾名稱。請使用=形式，因為鍵值是以-開頭。 - 如果使用者有指定時間範圍，請使用
--since。僅在輸出被截斷且你需要更多資料時，才提高--max-bytes（預設值 40000）。 - 如果使用者想查看所有專案，請對
~/.claude/projects中的每個資料夾執行一次挖掘，並關注摩擦最多的專案。
腳本會輸出一行摘要。如果它掃描到的對話很少或沒有，請告知使用者。Claude Code 會根據 cleanupPeriodDays（預設 30）刪除對話記錄，因此較舊的歷史可能已不存在。如果使用者未來想做更深入的回顧，建議調高此設定。
2. 閱讀命中結果
JSON 檔案中會列出依摩擦分數排序的工作階段。每個命中結果包含 signal（訊號）、score（分數）、ts（時間戳記）、prior_prompt（使用者的提問）、recent_actions（Claude 在命中前的最後工具呼叫），以及 user_reaction（使用者反應）或 detail（詳細資訊）。
訊號依價值大致排列如下：
user_correction：使用者提出異議。分數達 5 或以上表示強烈挫折或重複發生（例如「還是」、「又來了」、「我說了」、咒罵）。edit_revert和edit_churn：Claude 在同一個檔案上來回修改。tool_error_streak：Claude 持續遇到相同的失敗。interrupted：使用者在中途打斷 Claude。這通常代表它正在往錯誤的方向前進。permission_denied：Claude 嘗試了使用者或分類器阻止的操作。self_retraction：Claude 承認錯誤。此訊號雜訊較多，僅應作為輔助證據使用。
這些規則的比對邏輯較為粗略。請排除誤報，例如正常指令中的「不要」或網路錯誤後的「再試一次」。當一個命中結果模稜兩可時，請開啟該時間點附近的對話記錄。檔案位於 ~/.claude/projects/<key>/<session>.jsonl；用 grep 搜尋時間戳記，然後讀取前後幾行。不要讀取整份對話記錄。
3. 歸納為模式
將真正的命中結果歸納為重複出現的模式。一個模式代表一個根本原因，以 Claude 做錯了什麼來描述。例如：「產生新圖片而非使用已核准的素材庫」、「編輯當前版本而非建立新版本」、「聲稱變更已生效，卻未檢查建置輸出」。針對每個模式，記錄：
- 發生頻率，以及涉及多少個工作階段。
- 兩到三則來自使用者的簡短引述，附上工作階段標題和日期。
- 根本原因。從以下選項中擇一：缺乏知識、存在但被忽略的規則、不佳的預設工作流程、缺少驗證、或工具/權限缺口。
單一事件僅在使用者明顯生氣或成本高昂（例如造成破壞或工作遺失）時才計入。
4. 檢查現有設定
在提出任何建議之前，請先閱讀已有的設定：
~/.claude/CLAUDE.md，以及專案的CLAUDE.md和任何巢狀的CLAUDE.md。~/.claude/settings.json，以及專案的.claude/settings.json和.claude/settings.local.json（鉤子、權限）。- 專案記憶目錄
~/.claude/projects/<key>/memory/及其中的MEMORY.md。 ~/.claude/skills/和專案.claude/skills/中的技能。
如果某個模式已被 Claude 忽略的規則所涵蓋，那麼再次加入相同的規則並不會有幫助。請讓規則更具體，並將其放在能被看見的地方，或者改用更強大的機制。
5. 選擇修正方式
針對每個模式，使用最輕量且確實有效的機制：
| 根本原因 | 修正方式 |
|---|---|
| Claude 不知道的專案事實 | 在專案記憶目錄中建立一個記憶檔案，包含 name、description、metadata.type 的前置資料，內文則有 Why: 和 How to apply:，並在 MEMORY.md 中加上一行指標。更新現有記憶而非重複建立。 |
| 此儲存庫的長期規則 | 專案 CLAUDE.md |
| 所有專案都適用的規則 | ~/.claude/CLAUDE.md |
| 經常被違反且可透過腳本檢查的規則（格式、禁用字串、提交前需要執行的指令） | 在 settings.json 中新增一個鉤子。如果 update-config 技能可用，請使用它。 |
| 針對安全指令的重複權限提示或拒絕 | 提議加入允許清單，或建議使用 fewer-permission-prompts 技能（如果可用）。請勿為破壞性指令放寬權限。 |
| 經常出錯的多步驟工作流程 | 新增或編輯一個技能（如果可用，請使用 skill-creator）。 |
| Claude Code 的產品錯誤 | 在報告中註明。沒有設定上的修正方式。 |
將規則寫成具體、可檢查的指令，並明確指出特定事物，例如檔案、素材路徑、指令或版本命名。「處理圖片時要小心」這樣寫太過模糊，難以執行。
6. 報告並取得核准
每個模式一個章節，成本最高的優先。每個章節包含：
- 模式，用一行描述。
- 證據：次數、工作階段，以及 2 到 3 則附有日期的簡短引述。
- 根本原因。
- 建議的變更：目標檔案以及確切的文字或差異。
然後詢問要套用哪些變更。使用一個多選的 AskUserQuestion，為每個模式提供一個選項，效果很好。僅套用經核准的變更，然後列出已更改的項目和位置。
撰寫規則
寫入 CLAUDE.md、記憶或技能的任何內容，都必須遵循使用者自己 CLAUDE.md 檔案中的任何撰寫規則，例如語氣、禁用詞彙或歸屬規則。保持簡短且具體。對話記錄中的引述可能包含使用者貼入的機密資訊。挖掘器會遮蔽常見的金鑰格式，但在將文字複製到任何檔案之前，請務必檢查。