pedro-oscar/shorts-ai

問問 Matt

你不可能記住每一個技能，所以問就對了。

在說明某個技能的功能或建議跳過某個步驟之前，請先閱讀該技能的 SKILL.md：這裡的摘要僅供參考。

一個流程是貫穿各個技能的路徑。大多數路徑會沿著一個主要流程運行，並有兩個入口匝道匯入。其他所有技能都是獨立的，或是作為底層運行的語彙層。

主要流程：從點子到上線

這是大多數工作會走的路線。你有一個點子，並且想要把它做出來。

1. /grill-with-docs 透過訪談來打磨點子。當你在一個工作目錄中工作時，從這裡開始：它是有狀態的，會將所學到的內容保留在 GLOSSARY.md 和 ADR 中。（沒有工作目錄？請改用 /grill-me，它在獨立技能中涵蓋。兩者都運行相同的 /grilling 基本元件；grill-with-docs 是會留下書面記錄的那一個，只要有儲存庫可以留下記錄，它就是兩者中較好的選擇。）

2. 分支：你能在對話中解決所有問題嗎？ 如果一個問題需要可運行的答案（狀態、業務邏輯、一個你必須看到的 UI），則繞道建立原型，並透過 /handoff 進行雙向橋接（原型應存在於自己的目錄中，這正是 /handoff 的用途；請參閱階段邊界）：

   • 先用 /handoff 將上下文轉移出去，然後為該檔案開啟一個新的對話視窗，
   • 使用 /prototype 用一次性程式碼來回答問題，
   • 再用 /handoff 將學到的東西轉移回來，並從原始的點子討論串中引用它。

3. 分支：這是一個需要多個對話進行的建置嗎？

   • 是 → /to-spec （將討論串轉換為規格書），然後是 /to-tickets 將其拆分為追蹤子彈式的工單，每個工單都宣告其阻塞邊界。然後以下列兩種方式之一處理工單：
     • 每個工單使用 /implement，並在每個工單之間使用 /clear 來清除上下文。在本機追蹤器上，這是在 .scratch/<feature>/issues/ 下每個工單一個檔案，並手動以阻塞者優先的方式處理；在真實的追蹤器上，邊界會變成原生的阻塞連結，因此任何阻塞者已完成的工作都可以被接手。每個工單都是自包含的，所以最後一個工單的上下文是可以拋棄的。
     • 一次運行就使用 /implement-spec 來處理整個規格書。它將工單視為一個任務圖，在準備就緒的邊境上並行運行實作子代理，並將所有內容合併到一個整合分支上。當你想要編排整個建置過程，而不是親自驅動每個工單時，可以選用這個方式。
   • 否 → 直接在相同的上下文視窗中使用 /implement。

   無論哪種方式，程式碼都是透過驅動 /tdd（一次一個紅-綠循環）來建置，並以 /code-review 結束，這是對差異進行的雙軸（標準 + 規格）審查。/implement 為每個工單執行這兩項操作；/implement-spec 的實作者各自驅動 /tdd，然後對整合分支進行一次 /code-review。當你只想在沒有完整規格書的情況下，測試優先地建立一個具體行為時，可以獨立使用 /tdd；而當你想要根據一個固定點審查一個分支或 PR 時，可以獨立使用 /code-review。

   當工作以 Pull Request 的形式提交時，/pr 會塑造其主體：一個能顯示變更的最小視覺呈現、變更前後的運作證據，以及一個單向或雙向門的呼叫。它是由模型調用的，所以代理程式在撰寫 PR 時就會使用它。

4. /retro 閉合了循環。在一個建置之後，特別是一個偏離軌道的建置，它會回顧整個對話，並建議對代理程式的環境進行變更，而不是程式碼：導航指標、自動檢查、/code-review 強制執行的編碼標準、引導檔案、工具鏈。機械性的錯誤變成了確定性的檢查；判斷上的失誤則變成了編碼標準。下一個建置就能從一個更好的環境開始。

上下文衛生

將步驟 1 到 3 保持在一個不中斷的上下文視窗中（在進入 /to-tickets 之前不要壓縮或清除），這樣訪談、規格書和工單都能建立在相同的思考基礎上。然後每個 /implement 都從一個全新的視窗開始，依據工單進行工作。在清除之前，在它所回顧的同一個對話中執行 /retro；清除之後，則指向該對話的日誌來執行。

這個方法的限制在於**智慧區間**：模型仍能清晰推理的視窗（在最先進的模型上約為 150k tokens）。如果在進入 /to-tickets 之前，一個對話視窗接近了這個限制，不要繼續在效能退化的情況下推進；請在最近的階段邊界使用 /compact 並繼續進行（請參閱階段邊界）。

入口匝道

一種起始情境，它會產生工作，然後匯入主要流程。

• 錯誤和請求堆積如山 → /triage。它會透過分類角色來處理議題，並產出可供代理程式使用的議題，然後由 /implement 在後續處理。

  分類僅適用於不是你建立的議題：錯誤回報、新功能請求，以及任何原始輸入的內容。由 /to-tickets 產生的工單已經可供代理程式使用，所以不要對它們進行分類。

• 某個東西壞了 → /diagnosing-bugs。用於處理那些棘手的錯誤：一眼看不出原因的錯誤、間歇性的測試不穩定、在兩個已知正常狀態之間悄悄出現的迴歸。它拒絕在沒有緊密回饋迴路（一個已經能在此錯誤上顯示紅色的命令）之前進行理論推測，然後用一個迴歸測試來修復。一旦修復完成，在同一個對話中執行 /retro，詢問是什麼原因可以阻止這個錯誤；如果實際發現是沒有好的接縫來鎖定它，那麼這就是 /improve-codebase-architecture 的工作。

• 一個龐大而模糊的工作：一個全新的專案或一個大型功能建置，規模太大無法在一個對話中完成 → /wayfinder，這是這裡最具認知負擔的流程。當從這裡到目的地的路徑還不明朗時，它會在問題追蹤器上繪製一個由決策工單組成的共享地圖，並一次解決一個，產出的是決策，而非可交付成果，直到迷霧散去、路徑清晰為止。相較之下，/grill-with-docs 是為了一個可以在一個對話中掌握的點子，而 wayfinder 則是為了一個你無法掌握的點子，它更慢、更密集，所以只在這種情況下使用它，絕不用於範圍良好的功能。

  當地圖清晰時，它會進行交接，而不是建置：在 /to-spec 處匯入主要流程，它將地圖中連結的決策收斂成一個可建置的計劃，然後照常進行 /to-tickets 和 /implement。將地圖直接導入 /implement 會跳過這個收斂步驟，並丟失連結的細節，所以只有在工作規模真的很小時才直接進行 /implement。

程式碼庫健康

非功能開發，僅是維護。

• /improve-codebase-architecture 在你有多餘時間讓程式碼庫保持良好狀態以便代理程式操作時運行。它會浮現出深化機會；選擇一個機會會產生一個點子，你可以將其帶入主要流程的 /grill-with-docs。它是用來發現候選項目的調查；/codebase-design（下方）則是你在其上設計所選項目的工作檯。

底層的語彙

兩個由模型調用的參考，運行在其他技能之下，各自是其語彙的唯一事實來源。當詞彙（而非流程）是問題所在時，可以直接使用它們；或者讓上面的技能來引入它們。

• /domain-modeling：精煉專案的領域語言：挑戰一個模糊的術語、解決一個過載的詞語（例如「account」身兼數職）、將一個難以逆轉的決策記錄為 ADR。這是 /grill-with-docs 所驅動的主動紀律，用以保持 GLOSSARY.md 是一個乾淨的詞彙表。
• /codebase-design 是深層模組的語彙（模組、介面、深度、接縫、適配器、槓桿、局部性），用於設計模組的形狀：在一個乾淨的接縫後面，用一個小介面提供大量行為。/tdd 和 /improve-codebase-architecture 都會使用這個詞彙。

階段邊界

一個階段是對話內部的一部分工作：訪談、實作、品質驗證。在兩個階段的邊界處，你有五個選擇，在這整個地圖中，選擇哪一個是最模糊的決策：

• 繼續：保持不變。沒有成本，也沒有損失。
• /clear：清空視窗，當這裡的內容對接下來要做的事不重要時。
• /handoff 會撰寫一個可攜帶的 Markdown 檔案。用途狹窄：僅適用於一個新的測試環境、一個新目錄、一個同事，或者在階段中途分支一個次要任務。它帶來的好處是可攜帶性。
• 子代理：將一個範圍狹窄的任務發送到其自己的視窗，並取得報告回來。
• /compact 壓縮此上下文，並用其種子建立一個新的對話視窗。這是預設選項，位於決策樹的底部，而非首選。

閱讀 PHASE-BOUNDARIES.md 以了解排序後的決策樹：五個問題、每個分支背後的理由，以及為什麼主要來源成本使得繼續成為首先要排除的選項。在邊界處做出決定；在階段中途，則繼續進行或將剩餘任務拆分給子代理。

獨立技能

完全脫離主要流程。

• /grill-me：與 /grill-with-docs 相同的犀利訪談，但它是無狀態的：它不會在本地儲存任何內容，也不會建立 GLOSSARY.md。當你不在工作目錄中工作時使用它（例如打磨一個計劃、一個設計、一段文字，或者任何沒有儲存庫在底下的東西）。如果你在工作目錄中，請改用 /grill-with-docs：它執行相同的訪談並留下書面記錄，所以嚴格來說它是更好的選擇。
• /grilling 是訪談的基本元件本身：輪次、邊境、事實是代理程式的責任，而決策是你的責任。/grill-me 和 /grill-with-docs 是兩個命名的入口，而 /triage、/wayfinder 和 /improve-codebase-architecture 都在內部運行它。只有當你想要進行沒有包裝的純粹訪談時，才直接使用它。
• /prototype 是一個小型、一次性的程式，用來回答一個設計問題：這個狀態模型感覺對嗎，或者這個 UI 看起來應該是什麼樣子。一次性是對程式碼撰寫方式的一種約束，而不是保證要銷毀它：答案會融入實際的程式碼中，而原型本身會作為主要來源，保存在從 main 分支分出的 prototype/<name> 分支上，並在實作議題中指向它。這是主要流程步驟 2 中的繞道，但任何時候當一個設計問題難以在紙上決定時，都可以使用它。
• /research：將閱讀調查的工作委派給一個背景代理：它會針對主要來源調查一個問題，然後在儲存庫中留下一個有引用的 Markdown 檔案。在它閱讀的同時，你可以繼續工作。它所產生的檔案是可以帶入主要流程 /grill-with-docs 的素材，因為研究是為思考提供養分，而非取代思考。
• /to-questionnaire 在你受阻的原因不在你的腦中或程式碼庫中，而是在其他人的腦中時派上用場。它會為他們撰寫一份問卷來填寫。這與 /grill-me 相反：它不是訪談你有關主題的事，而是訪談你有關發送對象的事（要發給誰、你需要什麼回報），並將問題對準資訊缺口。回來的資料就是 /grill-with-docs 或 /to-spec 的素材。
• /wizard 用於那些只有人類才能採取的步驟：佈建基礎設施、設定憑證或 CI 密鑰、點擊操作不熟悉的第三方儀表板、執行一次性遷移或切換。它會產生一個互動式的 bash 腳本，該腳本會打開每個 URL、擷取每個值，並將其寫入 .env 和 GitHub Secrets，這樣這個程序就不再需要每次向代理重新解釋。這是由模型調用的，所以當代理程式遇到只有你能突破的牆時，它就會自動使用這個技能。如果代理程式自己就能做，那它應該自己做；這是為人類確實身處迴路中的情況準備的。
• /wait-what 是對一條沒有被理解訊息的補救措施。在任何其他技能中，於對話中途使用它，代理程式會使用 GLOSSARY.md 的詞彙，以簡單明瞭的英文，根據你缺少的上下文重新說明它剛才說過的話。這是在事後的補救；而 /grill-with-docs 是事前的預防，因為一個及早達成共識的共同語言，才能從根本上杜絕行話的出現。
• /teach：在多次對話中學習一個概念，並使用當前目錄作為有狀態的工作空間。
• /writing-for-agents 是為代理程式撰寫文件（技能、AGENTS.md、被指向的文件）時的參考。

前置條件

/setup-matt-pocock-skills：在你的第一個工程流程之前執行，用以設定問題追蹤器、分類標籤和文件佈局，這些是其他技能所假設的。自訂的問題追蹤器也可以運作。