Brians-brain/claude-skills

問 Matt

以繁體中文回答使用者。

你不會記得每一個 skill，所以來問。

在說明某個 skill 做什麼、或建議跳過某個步驟之前，先讀那個 skill 的 SKILL.md：這裡的摘要只是用來定位方向。

一條流程是穿過這些 skill 的一條路徑。大部分路徑走在一條主流程上，另外有兩個匝道匯入它。其他的都是獨立使用的，或是在底下運作的詞彙層。

主流程：想法 → 上線

大部分工作走的路線。你有一個想法，想把它做出來。

1. /grill-with-docs 透過訪談磨利想法。只要你是在一個工作目錄裡工作，就從這裡開始：它是有狀態的，會把學到的東西保留在 GLOSSARY.md 和 ADR 裡。（沒有工作目錄？改用 /grill-me，見「獨立使用」。兩者都執行同一個 /grilling 基本機制；grill-with-docs 會留下書面紀錄，所以只要有 repo 可以留，它就是比較好的那一個。）

2. 分支：每個問題都能在對話中解決嗎？ 如果某個問題需要可以執行的答案（狀態、商業邏輯、一個你必須親眼看到的 UI），就繞道走原型，兩個方向都用 /handoff 銜接（原型放在它自己的目錄，這正是 /handoff 的用途；見「階段邊界」）：

   • 用 /handoff 交出去，然後針對那個檔案開一個新 session，
   • 用 /prototype 以拋棄式程式碼回答問題，
   • 用 /handoff 把學到的東西交回來，並從原本的想法討論串引用它。

3. 分支：這是需要多個 session 的建置嗎？

   • 是 → /to-spec（把討論串變成一份 spec），然後用 /to-tickets 把它拆成 tracer-bullet ticket，每張都標明它的阻擋邊。接著用以下兩種方式之一處理 ticket：
     • 每張 ticket 用一次 /implement，每張之間都 /clear 情境。在本地 tracker 上，就是 .scratch/<feature>/issues/ 底下一張 ticket 一個檔案，手動依阻擋者優先的順序處理；在真正的 tracker 上，邊會變成原生的阻擋連結，所以任何阻擋者都已完成的 ticket 都可以接手。每張 ticket 都是自給自足的，所以上一張的情境可以丟掉。
     • 用 /implement-spec 一次跑完整份 spec。它把 ticket 當成任務圖讀取，在已就緒的前沿上平行執行實作子 agent，並把所有東西落在同一條整合分支上。當你寧可統籌整個建置、而不是自己逐張推進時使用。
   • 否 → 就在這裡、同一個情境視窗中用 /implement。

   無論哪種，程式碼都是透過 /tdd（一次一個 red-green 切片）建出來的，最後以 /code-review-zh 收尾，也就是對 diff 做雙軸審查（Standards＋Spec）。/implement 對每張 ticket 都跑這兩個；/implement-spec 的每個實作者都會用 /tdd，最後對整合分支跑一次 /code-review-zh。當你只想以測試先行做出一個具體行為、不需要完整 spec 時，單獨使用 /tdd；任何時候想針對某個固定點審查一個分支或 PR，就單獨使用 /code-review-zh。

   當工作要以 pull request 送出時，/pr 決定 PR 內文的形狀：呈現變更的最小視覺、證明它有效的前後對照證據，以及單向門／雙向門的判斷。它是模型呼叫型的，所以 agent 每次寫 PR 都會用到它。

4. /retro 讓迴圈閉合。在一次建置之後，尤其是出了狀況的那種，它會回顧整個 session，並建議改善 agent 的工作環境，而不是程式碼：導航指標、自動檢查、/code-review-zh 執行的寫作規範、引導檔、工具。機械性的錯誤變成確定性的檢查；判斷題變成寫作規範。下一次建置就從更好的環境開始。

情境衛生

讓步驟 1–3 保持在同一個不中斷的情境視窗中（在 /to-tickets 之前不要 compact 或 clear），讓拷問、spec 和 ticket 都建立在同一套思考上。之後每次 /implement 都從頭開始，依據 ticket 工作。在 /retro 要回顧的那個 session 中、clear 之前執行它；如果已經 clear 了，就把它指向那個 session 的紀錄。

這件事的限制是**聰明區（smart zone）**：模型仍能敏銳推理的視窗範圍（在最先進的模型上約 15 萬 token）。如果一個 session 在 /to-tickets 之前就接近這個上限，不要在退化的狀態下硬撐；在最近的階段邊界 /compact，然後繼續（見「階段邊界」）。

匝道

會產生工作、然後匯入主流程的起始情境。

• Bug 和請求越堆越多 → /triage。它讓 issue 在 triage 角色間流轉，產出可交給 agent 的 issue，之後由 /implement 接手。

  Triage 只用於不是你建立的 issue：bug 回報、新進的功能請求、任何未經處理就進來的東西。/to-tickets 產出的 ticket 已經可以交給 agent，所以不要 triage 它們。

• 有東西壞了 → /diagnosing-bugs。用於難纏的：第一眼看不出來的 bug、間歇性的不穩定、在兩個已知正常的狀態之間偷偷溜進來的退化。在擁有一個緊密的回饋迴路（一個已經會因為這個 bug 變紅的指令）之前，它拒絕提出理論，然後以回歸測試修正。修好之後，在同一個 session 執行 /retro，問問什麼能預防這個 bug；如果真正的發現是沒有好的 seam 能把它鎖住，那就是 /improve-codebase-architecture 的工作。

• 一個龐大、迷霧重重的專案：全新專案或巨大的功能建置，一個 session 裝不下 → /wayfinder，這裡最耗腦力的流程。當從這裡到目的地的路還看不見時，它在 issue tracker 上畫出一張由決策 ticket 組成的共享地圖，一次解決一張，產出決策而非成品，直到迷霧退去、路變清楚。/grill-with-docs 磨利的是你能在一個 session 中掌握的想法；wayfinder 則是給你掌握不了的想法，而且它更慢、更密集，所以只把它留給那種情況，絕不用在範圍明確的功能上。

  地圖清晰之後，它交棒，而不是建置：在 /to-spec 匯入主流程，由它把地圖上連結的決策收斂成可建置的計畫，然後照常 /to-tickets 和 /implement。把地圖直接接進 /implement 會跳過這個收斂，丟掉連結的細節，所以只有當這個專案最後證明其實很小時，才直接走 /implement。

程式碼健康

不是功能開發，只是維護保養。

• /improve-codebase-architecture 在你有空的時候就執行，讓程式碼保持適合 agent 工作的狀態。它會找出加深的機會；選定其中一個就會產生一個想法，你可以把它帶到主流程的 /grill-with-docs。它是找出候選的勘查；/codebase-design（見下方）是你設計選定候選的工作台。

底層的詞彙

兩個在其他 skill 底下運作的模型呼叫型參考，各自是其詞彙的單一真實來源。當問題出在用詞而不是流程時，直接使用它們；或讓上面的 skill 把它們帶進來。

• /domain-modeling：磨利專案的領域語言：挑戰一個模糊的術語、解決一個被過度使用的詞（例如「料號」同時指三種東西）、把一個難以反悔的決策記錄成 ADR。它是 /grill-with-docs 用來讓 GLOSSARY.md 保持乾淨的主動紀律。
• /codebase-design 是 deep module 的詞彙（模組、介面、深度、seam、轉接器、槓桿、局部性），用來設計模組的形狀：在乾淨的 seam 上、小介面背後放大量行為。/tdd 和 /improve-codebase-architecture 都使用它。

階段邊界

階段是一個 session 中的一段工作：拷問、實作、QA。在兩個階段之間的邊界上，你有五個選項，而在它們之間做選擇，是整張地圖中最模糊的決策：

• 繼續：待在原地。不花任何成本，也不失去任何東西。
• /clear：清空視窗，當這裡的任何東西對接下來都不重要時。
• /handoff 寫一個可攜的 markdown 檔。用途很窄：只用於換一個 harness、換一個目錄、交給同事，或在階段中途分出一個支線任務。它換來的是可攜性。
• 子 agent：把一個範圍明確的任務送到它自己的視窗，並拿回一份報告。
• /compact 壓縮這個情境，並用它來啟動一個新 session。它是預設，位在樹的最底端，而不是第一個要伸手拿的。

依序排列的決策樹見 PHASE-BOUNDARIES.md：五個問題、每個分支背後的理由，以及為什麼一手資料的代價讓繼續成為第一個要排除的選項。在邊界上做決策；階段中途，就繼續，或把剩下的工作拆給子 agent。

獨立使用

完全不在主流程上。

• /grill-me：和 /grill-with-docs 同樣嚴格的訪談，但無狀態：它不在本地保存任何東西，也不建立 GLOSSARY.md。當你不是在工作目錄中工作時使用（磨利一個計畫、一個設計、一篇文章，任何底下沒有 repo 的東西）。如果你在工作目錄中，改用 /grill-with-docs：它進行同樣的訪談，還留下書面紀錄，所以它絕對比較好。
• /grilling 是訪談的基本機制本身：回合、前沿、找事實是 agent 的工作、做決策是你的工作。/grill-me 和 /grill-with-docs 是兩個有名字的入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都在內部執行它。只有當你想要沒有任何包裝的訪談時，才直接使用它。
• /prototype 是一個小的拋棄式程式，回答一個設計問題：這個狀態模型合理嗎，或這個 UI 該長什麼樣子。「拋棄式」是對程式碼寫法的限制，而不是銷毀它的承諾：答案會整合進正式程式碼，原型本身則以一手資料的形式保存在 main 之外的 prototype/<name> 分支，並從實作 issue 指向它。它是主流程步驟 2 的繞道，但任何時候設計問題很難在紙上解決，都可以使用它。
• /research：把閱讀的跑腿工作交給一個背景 agent：它依據一手來源調查一個問題，然後在 repo 中留下一個附引用的 Markdown 檔。它閱讀的同時，你繼續工作。它產出的檔案是要帶進主流程 /grill-with-docs 的東西，因為研究是餵養思考，而不是取代思考。
• /to-questionnaire 用在卡住你的東西不在你腦中、也不在程式碼裡，而是在別人腦中的時候，它幫你寫一份問卷讓對方填。它是 /grill-me 的反面：它不是拷問你主題本身，而是拷問你寄送這件事（要寄給誰、需要拿回什麼），並把問題瞄準落差。拿回來的東西是 /grill-with-docs 或 /to-spec 的材料。
• /wizard 用於只有人能做的步驟：建置基礎設施、設定憑證或 CI secrets、點過一個不熟悉的第三方後台、執行一次性的遷移或切換。它產生一個互動式 bash 腳本，打開每個 URL、擷取每個值，並寫進 .env 和 GitHub secrets，讓這個程序不再是每次都要重新跟 agent 解釋的東西。它是模型呼叫型的，所以 agent 一碰到只有你能通過的牆就會用它。如果 agent 自己就能做，它就應該自己做；這是給真的需要人在迴路中的情況。
• /wait-what 是給沒傳達到的訊息的補救。在對話中途、在任何其他 skill 裡都能使用，agent 會補上你缺少的背景，用簡單的語言、GLOSSARY.md 的詞彙，重新講一次它剛才說的話。它是事後補救；/grill-with-docs 才是事前的解藥，因為及早約定好的共同語言，才能讓術語一開始就不會冒出來。
• /teach：以目前目錄作為有狀態的工作區，跨多個 session 學習一個概念。
• /writing-for-agents 是撰寫給 agent 讀的文件的參考：skill、AGENTS.md／CLAUDE.md、被指向的文件。
• /handoff：把目前對話壓縮成一份交接文件，給新的 session、新的目錄或同事接手（見「階段邊界」）。
• /git-guardrails-claude-code：安裝一個 Claude Code hook，在危險的 git 指令（push、reset --hard 等）執行前就擋下來。每台電腦或每個專案設定一次。

前置條件

/setup-matt-pocock-skills：在第一次使用工程類流程之前執行，設定其他 skill 所假設的 issue tracker、triage 標籤與文件配置。也支援自訂的 issue tracker。