lesson · diff
git:20260705.2c23737 to git:20260807.7def344
22 added, 27 removed. Audit A to A.
---
name: lesson
- description: 被使用者糾正後，把教訓寫成可長期沿用的規則記入 tasks/lessons.md。在使用者說「不對」「不是這樣」「我說過」或任何形式指出錯誤後立即使用；也用於定期把重複的 lesson 升級成 CLAUDE.md 規則、skill 或 hook。
+ description: 被使用者糾正後，先分流（單純事實/偏好交給內建 auto memory，需要變成規則才進本流程），把規則寫成可長期沿用的條目記入 tasks/lessons.md。在使用者說「不對」「不是這樣」「我說過」或任何形式指出錯誤後立即使用；也用於定期把重複的 lesson 升級成 CLAUDE.md 規則、skill 或 hook。
---
# lesson：教訓落地與升級
- 目的：讓每次糾正只發生一次。lesson 寫得太抽象等於沒寫——下次的模型（可能更弱）必須能拿它直接比對情境。
+ 目的：讓每次糾正只發生一次。
+ ## 0. 先分流：這是事實/偏好，還是規則？
+
+ - **單純事實／偏好／build 指令**（例如「這個專案用 pnpm」「使用者偏好簡短回報」）
+ → 交給 Claude Code 內建 auto memory，不進本流程（預設開啟、自動記錄，不需要
+ 人工步驟）。
+ - **需要變成「以後都要遵守」的規則**（本 skill 的核心用途）→ 走下面 A／B 節。
+
## A. 記錄一條新 lesson
- ### 1. 先查重
- 在 `tasks/lessons.md` 內搜尋關鍵字。已有同類條目 → 不新增，改走「B. 升級」。
+ 先查重：在 `tasks/lessons.md` 搜尋關鍵字，已有同類條目 → 不新增，改走「B. 升級」。
- ### 2. 用固定格式追加（檔案不存在才建立，放在 `tasks/lessons.md`）
+ 用固定格式追加（檔案不存在才建立）：
```markdown
## [YYYY-MM-DD] <一行標題：動詞開頭>
- 觸發情境：<具體到下一個 session 能比對，含檔名/指令/使用者原話>
- 錯誤行為：<我實際做了什麼>
- 正確行為：<應該做什麼，可執行的一步步>
- 判準：<一句 if-then，讓弱模型能機械式套用>
- 狀態：first-hit
```
- ### 3. 品質判準：好壞範例
-
- **壞例（禁止這樣寫）：**
- ```markdown
- ## [2026-07-05] 要更小心測試
- - 觸發情境：測試出問題
- - 正確行為：更仔細地處理測試
- ```
- 太抽象，無法比對，無法執行。
-
- **好例：**
- ```markdown
- ## [2026-07-05] 改 API 回傳格式前先 grep 所有呼叫端
- - 觸發情境：改了 `get_user()` 的回傳型別（dict→dataclass），沒查呼叫端，弄壞 3 處
- - 錯誤行為：只改了函式本體與其單元測試就宣稱完成
- - 正確行為：改任何公開函式簽名前，先 `grep -rn "get_user(" --include="*.py"` 列出所有呼叫端，逐一確認相容或一起改
- - 判準：if 改動會變更函式簽名或回傳格式 → then 先列出全部呼叫端再動手
- - 狀態：first-hit
- ```
+ 判準欄位不可空白：寫不出 if-then 表示還沒想清楚，再想。太抽象等於沒寫——
+ 壞例「要更小心測試」對照好例「改任何公開函式簽名前先 grep 所有呼叫端」，差別在
+ 後者具體到下一個 session 能直接比對情境，不是換個說法重複同一句空話。
## B. 升級（同一 lesson 第 2 次被觸發時）
1. 把該條目的 `狀態：first-hit` 改為 `狀態：promoted-to:<位置>`。
2. 依「制度分層」選升級目的地：
- **規則可用程式判定**（如「禁止 commit 含 console.log」）→ 用 /update-config 做成 hook。最優先。
- - **1–2 行寫得完、每次都適用** → 加進 `~/.claude/CLAUDE.md`（全域通用）或 `<repo>/CLAUDE.md`（只限該專案）的「硬規則」。注意行數預算：加一條前先看能否刪一條或降級一條到 skill。
- - **多步驟程序** → 寫成 `~/.claude/skills/<name>/SKILL.md`，並在 CLAUDE.md 留一行觸發指引。
+ - **1–2 行寫得完、每次都適用** → 加進 CLAUDE.md 的「硬規則」，加一條前先看能否刪一條。
+ - **多步驟程序** → 寫成 skill，CLAUDE.md 留一行觸發指引。
3. lessons.md 的原條目保留（作為升級紀錄），不刪除。
## 鐵則
- 糾正發生的**當下**就記，不要等任務結束（會忘）。
- 一條 lesson 只記一個模式；混多個就拆開。
- - 判準欄位不可空白：寫不出 if-then 表示還沒想清楚，再想。
+
+ ## Changelog
+
+ - 2026-08-06：新增「0. 先分流」——事實/偏好走內建 auto memory，本 skill 只保留
+ 「需要升級成規則」的部分；A 節範例濃縮。詳見 docs/harness-overlap-2026-08.md
+ （使用者核准）。