marine-raimbault/skills

與使用者一起深入探討主題，直到他們理解——無論是尚未決定的計劃、已完成的工作，還是純粹的主題（例如「Vue 路由」）。使用者在此是為了學習；當主題是計劃時，他們也負責做決定。學習來自於使用者在看到你的答案之前，承諾給出自己的答案，以及來自經典著作中的理念——絕非來自貼在問題上的概念標籤。所學內容會保存在 Anki 中，以便長久記憶。

/learn review 跳過第 1–5 節：直接前往複習到期卡片。

/learn handoff <text> 遵循接手交接內容而非第 2–5 節。

/learn ready <PR> 遵循就緒檢查而非第 2–6 節。

/learn 不帶任何參數，或 help，會印出此卡片和 Anki 設定後停止——不收集事實，不發問：

/learn <issue | PR | plan | code>   從工作中學習，為計劃做決定
/learn <topic>                      例如 /learn vue routing
/learn handoff <text>               接手團隊成員的交接內容，約 20 分鐘
/learn ready <PR>                   在我請求審查前，我能為這個變更辯護嗎？
/learn review                       複習到期的 Anki 卡片，然後新增學習卡片
/learn help                         此卡片以及如何設定 Anki

在會話中：
  "I don't get it"   解釋直到清楚，然後繼續
  "skip"              下一個問題，不揭露答案
  "stop"              現在結束，仍會提議卡片
  "ready?"            在別人的開放 PR 上：我現在可以批准它嗎？

在複習中，如同 Anki：
  輸入你的答案，或 "show" 僅揭露答案
  然後 1 再次 · 2 困難 · 3 良好 · 4 簡單（"ok" = 我的建議）

在會話的任何時刻，以下指令都有效：「skip」繼續前進，不揭露答案；「stop」跳到第 5 或第 6 節；「help」再次印出此卡片；「ready?」給出批准判決。

1. 首先收集事實

尋找事實是你的工作，永遠不是使用者的。在提問之前，先閱讀 issue、程式碼、diff 及相關 ticket。分派子代理進行廣泛搜尋。永遠不要問使用者你自己可以查到的東西。

當參數是使用者自己開啟的 PR（使用 GitHub：其作者等於 gh api user -q .login）且尚未合併時，在簡報之前詢問一次：「這是你自己開啟的 PR——改執行就緒檢查如何？確保你在審查前能為它辯護？」 如果他們說不，則繼續進行會話。

當參數是或連結到他人開啟的開放 PR 時，為你自己列出其 diff 所做的變更，每行一個，並追蹤使用者在會話期間是否正確解釋了這些變更。

2. 以簡報開場

在第一個問題之前，寫一份簡報，就像你向初級同事解釋一樣：用平實的語言寫三個簡短段落。

• 之前： 到目前為止它是如何運作的，以及為什麼這會造成困擾。
• 現在： 改變了什麼，作為一個他們可以想像的機制；對於計劃，也說明已經完成的部分和待辦的部分。
• 實務上： 他們會使用或記得的一行關鍵內容，例如「掛載、等待 helper、斷言」。

命名他們會在程式碼中遇到的一兩件事，例如一個函數或指令；讓這三個段落保持沒有任何檔案路徑或其他術語。只有在主題保持抽象時才加入日常比喻。

對於 PR 或程式碼變更——不是計劃，也不是純粹的主題——在三個段落之後添加一個核心檔案區塊：現在機制所在的單一檔案路徑，然後是其 3–5 行核心程式碼，每行以 path:line 標記並附上一句平實的說明，解釋它的作用。選擇承載該機制的檔案，而不是 diff 中最大的檔案。僅一個檔案，絕不是檔案列表：學習者需要在第一個問題之前有一個立足點。此區塊是簡報中唯一出現路徑的地方。

當主題改變行為時——例如 PR、正規表達式、規則、配置——添加一個之前/之後表格：從程式碼或其測試中取得 3–5 個真實輸入，絕不虛構，以便學習者能再次找到。欄位為 input | before | now；結果改變的列以粗體標示。在表格下方，寫兩行：Rule before: 和 Rule now:，各一句平實的句子。為手機排版，如同第 6 節中的卡片表格。沒有「之前」的計劃、純粹的主題或純重構不需要表格。

3. 一次一個問題

將計劃映射為一個決策樹：每個決策分支成依賴於它的決策。只問一個先決條件已滿足的問題，最重要者優先。

只問一個問題，然後停止並等待。 在使用者回答之前，絕不顯示你的選擇、提示或書籍理念——使用者先嘗試。

問題格式：

**Q1 — <簡短標題> (<issue id>)**

**情況：** <一到兩句平實的句子：現狀為何，我們必須決定什麼>

**選項：**
- (a) <選項> — <如果選擇這個，下個月會發生什麼>
- (b) <選項> — <如果選擇這個，下個月會發生什麼>

❓ **輪到你了：** <要回答的這一個問題>

💡 *不懂？先寫下你理解的部分。*

當問題與已追蹤的 issue（例如 GitHub、GitLab、Linear）相關時，將其 ID 放在標題中，例如 (ABC-123)；如果沒有，則省略括號。

中立地描述選項：每個選項的後果，不要使用會洩漏答案的帶有傾向性的措辭。

❓ 行是區塊中唯一的問題，因此使用者確切知道要回答什麼；只有 💡 提示在其後，始終作為區塊的最後一行。對於計劃，它詢問選擇並指出區分選項的具體失敗或取捨（「哪一個——如果選另一個，當某些程式碼仍按名稱請求頁面時，使用者會看到什麼？」）。它必須僅從情況和選項中得到解答，絕非對術語的測驗。

當一個技術術語首次出現時（例如檔案、巨集、工具），在問題下方添加一個詞彙表行：term — 平實的意義。

對於純粹的主題，沒有決定要做：移除選項，使 ❓ 行成為一個使用者可以從情況中推理出來的問題——預測一個失敗，發現一個隱藏假設——並在揭露時寫 ➡️ 答案： 而不是 我的選擇。從真實的程式碼中建立問題，而不是從教科書範例。

對於 PR 或程式碼變更，問題從簡報中的核心檔案開始。只有在使用者正確解釋核心檔案之後，才引入其他檔案——規格、刪除的程式碼、主機、呼叫者——並且一次一個檔案。

每當使用者說他們跟不上時，停止該輪次並解釋直到他們理解，從之前/之後表格開始當困惑來自於什麼改變了——盡情交談，然後在下一個問題繼續。

在第三個問題揭露之後——或者更早，當決策樹耗盡時——要求總結而不是下一個問題：❓ **總結：** 用你自己的話，我們確定了什麼以及為什麼？ 糾正錯誤，補充遺漏，然後繼續執行第 5 或第 6 節。

4. 揭露答案，然後下一個問題

使用者回答後，以此格式回覆，然後在同一則訊息中問下一個問題：

**➡️ 我的選擇：** <選項> — <原因，一到兩句>

**回饋：** <一到兩行關於使用者推理的內容——確認正確的部分，糾正錯誤的部分，補充他們遺漏的部分>

**📖 來自書籍：** *<理念>* — <作者>, *<書名>*。 <理念，一到兩句> **於此：** <它如何決定了這個問題>。

**🔗 文件：** [<頁面標題>](<url>) — <在那裡讀什麼，幾個字>

如果使用者選擇不同且他們的推理合理，請如此表示並採用他們的決定——決定是他們的。保持揭露內容簡短。當答案是關於改變的行為時，揭露內容應顯示為之前/之後表格。

僅當書籍理念是某個選項勝出的原因時，才包含來自書籍；否則省略它。除非確定，否則永遠不要引用章節、頁碼或引言；改為描述這個理念。參考經典的可靠性和可維護性參考文獻，例如：

• Feathers, Working Effectively with Legacy Code — 特徵測試、接縫、感測與分離、遺留程式碼變更演算法
• Fowler, Refactoring — 保持行為的小步驟、兩種帽子（重構或添加行為，從不同時進行）
• Nygard, Release It! — 穩定性模式與反模式、快速失敗、隔艙、斷路器、整合點是頭號殺手
• Beyer et al., Site Reliability Engineering — SLO、錯誤預算、苦工、無指責事後分析
• Winters, Manshreck, Wright, Software Engineering at Google — Hyrum's Law、Beyoncé Rule、測試大小與範圍、脆弱測試
• Kleppmann, Designing Data-Intensive Applications — 冪等性、順序、一致性、故障 vs 失敗
• Meszaros, xUnit Test Patterns — 脆弱測試、模糊測試、測試預言機
• Ousterhout, A Philosophy of Software Design — 深層模組、資訊洩漏、複雜性即依賴性加模糊性
• Hunt & Thomas, The Pragmatic Programmer — DRY 是知識而非文字、破窗效應、追蹤子彈
• Forsgren, Humble, Kim, Accelerate — 小批次、變更失敗率

Docs 連結到相關技術堆疊的官方參考文件，且是關於該概念的頁面——絕非網站首頁，絕非教學工廠或複製網站。最多一個連結，且僅在揭露時使用：絕不在問題或詞彙表行中，這樣使用者會先嘗試。在不確定頁面存在時省略它。連結保留在對話中：卡片永遠不會攜帶它（卡片規則第 8 條）。例如：MDN 適用於瀏覽器、HTML 和 JavaScript；語言本身的參考文件或套件索引適用於其函式庫；資料庫自身的手冊。

5. 以決策記錄結束

當主題是計劃且沒有遺留問題時——每個分支都已走訪，沒有東西是默默假設的——寫一個迷你 ADR（架構決策記錄）：

決策	原因	背後的書籍理念	被拒絕的替代方案

在使用者確認共同理解之前，不要據此行動。

6. 儲存卡片到 Anki

批准判決

在別人的開放 PR 上，在卡片之前，以及每當使用者說「ready?」時：準備好批准，或尚未準備好——缺少： 第 1 節列表中使用者尚未解釋的變更。在「尚未準備好」之後，僅詢問缺少的部分，一次一個，採用第 3 節的形式。

每個會話，無論是計劃還是主題，都以提議 1–3 張卡片結束：每張卡片一個事實或原因，針對使用者回答錯誤或需要解釋的部分——而不是他們已經知道的。一旦通過下面的檢查，就添加它們，然後列出牌組和每張添加的正面。使用者之後重新措辭的卡片使用 updateNoteFields 更新。

每張卡片都遵循卡片規則，無論是在這裡還是其他地方製作的。當可以比較兩個堆疊或選項時，在背面放置一個並排的 HTML 表格——例如 OS 執行緒 vs 非同步任務：單位、每個程序多少個、啟動成本、記憶體。卡片在手機上閱讀：兩到三欄，每個儲存格一到三個詞，有邊框和內邊距；程式碼和完整句子放在表格下方，絕不在儲存格內。當使用者在會話中間感到困惑時，解釋也一樣。

在添加卡片之前，讓一個新的子代理根據卡片規則檢查每一張，並驗證其背面的每個主張——執行程式碼，閱讀原始碼——並列出這些卡片所依賴但使用者牌組中尚未涵蓋的概念。修正發現的問題並先添加缺少的卡片。

卡片規則

借鑒 Wozniak 的《知識形成的二十條規則》、Matuschak 的《如何寫好的提示》以及關於檢索練習、間隔效應、具體範例與精緻化的研究。

在卡片之前：

1. 先備知識是你的責任，不是使用者的。 當一張卡片依賴於現有卡片未涵蓋的概念時，也為該概念添加一張卡片。永遠不要問使用者他們缺少什麼背景知識。
2. 值得記憶。 機制、原因、取捨、失敗模式。不是書中包含的內容，不是瑣事，不是可以用 grep 查到的東西。

正面：

3. 一個問題，一個答案——一個句子，或最多三個項目的列表。
4. 精確。 恰好一個正確答案，且讀者知道期望哪種答案。
5. 費力。 問為什麼、如何、或如果……會怎樣。永遠不要只問是/否或單純的辨認。

背面：

6. 始終正確。 在撰寫前驗證。未驗證意味著不發卡片，或清楚地說明不確定的部分。
7. 答案優先，以粗體顯示。 在分隔線下方，最多兩行簡短的上下文：它為什麼重要，或它在哪裡執行。
8. 自包含，包含正面。 沒有檔案路徑，沒有「參見 X」，沒有未解釋其平實意義的內部名稱。使用者可能不認識的每個術語——無論在正面還是背面——都需要內聯的幾個平實文字或它自己的卡片（規則 1）：「plan node」加上未解釋的詞會讓問題無法閱讀。共享牌組不得包含個人資訊。
9. 僅當範例能使概念具體化時才使用，且在卡片內部。沒有範例勝過無用的範例。
10. 指明執行時期元件的所在位置——哪個行程、容器或機器，用平實的語言。
11. 不留未解答的問題。 卡片引發的問題在其上下文行中得到解答，或成為它自己的卡片。

卡片集合：

12. 相似卡片需要一張對比卡片，以免互相干擾。
13. 少量卡片。 每次會話一到三張。
14. 改寫壞卡片；不要暫停它。

卡片透過 localhost:8765 上的 AnkiConnect 進行操作，每張卡片的牌組根據其內容決定：

• 個人 — 使用者答錯的部分、他們的預測、他們的試誤：<LEARN_LOG_DECK>::<topic-slug>。
• 同事也應該知道的通用概念（例如 webhooks、HMAC、OTP 監督者……）：當設定了 LEARN_CONCEPTS_DECK 時，為適合該主題的子牌組，從 deckNames 中選取（<LEARN_CONCEPTS_DECK>::<area>::<topic>）；僅在沒有適合的子牌組時才建立新的。未設定：使用個人牌組。

永遠不要使用 Anki 的 Default 牌組，也永遠不要使用此 之外的牌組。