Castle-Solutions/landing

Ask 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 將其拆分為多個 tracer bullet 任務（ticket），每個任務宣告其阻塞邊界。然後以下列兩種方式之一處理這些任務：
     • 每個任務執行 /implement，並在每個任務之間 /clear 上下文。在本機追蹤器上，每個任務在 .scratch/<feature>/issues/ 下是一個檔案，手動以阻塞者優先的方式處理；在真正的追蹤器上，邊界會變成原生的阻塞連結，因此任何其阻塞者已完成的任务都可以被選取執行。每個任務都是自包含的，所以前一個任務的上下文可以丟棄。
     • 對整個規格一次執行 /implement-spec。它將任務讀取為一個任務圖，跨已準備好的前緣並行執行實作子代理，並將所有內容合併到一個整合分支上。當你寧可編排整個建置過程，而不是親自驅動每個任務時，可以考慮使用它。
   • 否 → 直接在同一個上下文視窗中執行 /implement。

   無論哪種方式，程式碼都是透過驅動 /tdd（一次一個紅-綠循環）來建置，並以 /code-review（對 diff 進行標準與規格的雙軸審查）來收尾。/implement 對每個任務執行這兩步驟；/implement-spec 的實作子代理各自驅動 /tdd，然後它對整合分支執行一次 /code-review。當你只想在沒有完整規格的情況下，以測試優先的方式建置一個具體行為時，可以單獨使用 /tdd；而當你想針對一個固定點審查某個分支或 PR 時，可以單獨使用 /code-review。

   當工作以 Pull Request 的形式提交時，/pr 會塑造 PR 內容：用最小的視覺元素展示變更、提供變更前後的證據證明其運作正常，並說明這是一個單向還是雙向的決定。它是由模型調用的，因此當代理撰寫 PR 時會自動使用它。

4. /retro 閉環。在一個建置完成後，特別是當它偏離軌道時，它會回顧整個對話視窗，並建議對代理的環境進行更改，而不是程式碼：例如導航提示、自動化檢查、/code-review 強制執行的編碼標準、引導檔案、工具鏈。機械性的錯誤會變成確定性的檢查；需要判斷的決策則會變成編碼標準。這樣，下一個建置就能從一個更好的環境開始。

上下文衛生

將步驟 1 到 3 保持在一個不中斷的上下文視窗中（在 /to-tickets 之前不要進行壓縮或清除），這樣打磨、規格和任務都能建立在相同的思考基礎上。然後，每次執行 /implement 時都從任務開始。在同一個對話視窗中執行 /retro，在清除上下文之前進行回顧；清除之後，則需要將回顧指向該對話視窗的日誌。

此方法的限制在於**智慧區間**：即模型仍能清晰推理的視窗大小（在最先進的模型上約為 150k tokens）。如果一個對話視窗在到達 /to-tickets 之前就接近這個限制，不要勉強在效能下降的狀態下繼續；請在最近的階段邊界執行 /compact 並繼續（請參閱階段邊界）。

入匝道

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

• 錯誤和請求不斷堆積 → /triage。它將問題通過分類角色進行處理，並產出代理可直接處理的問題，稍後由 /implement 接手。

  分類僅適用於不是你建立的問題：錯誤報告、進來的功能請求，以及任何未經處理的原始資訊。由 /to-tickets 產生的任務已經是可以直接被代理處理的，所以不要對它們進行分類。

• 某個東西壞了 → /diagnosing-bugs。用於處理棘手的 bug：那些一眼看不出問題的 bug、偶發的測試不穩定、以及兩個已知正常狀態之間悄悄出現的迴歸。它拒絕在擁有緊密反饋迴圈（一個已經能針對這個 bug 顯示失敗的命令）之前進行理論推測，然後在修復時加入一個迴歸測試。修復完成後，在同一個對話視窗中執行 /retro，詢問什麼措施可以防止這個 bug 的產生；如果發現真正的問題是缺乏良好的接縫來鎖定它，那麼這就是 /improve-codebase-architecture 的工作。

• 一個巨大且模糊的工作：一個全新的專案或一個龐大的功能建置，規模太大以至於無法在單一對話視窗中完成 → /wayfinder，這是此處認知需求最高的流程。當從這裡到目的地的路徑還不明確時，它會在問題追蹤器上繪製一個由決策任務組成的共享地圖，並逐一解決這些任務，產出的是決策，而非可交付成果，直到迷霧散去、路徑清晰。如果說 /grill-with-docs 能打磨一個可以在一次對話視窗中掌握的 idea，那麼 wayfinder 就是為你無法掌握的 idea 設計的。它更慢、更密集，所以請只在這種情況下使用它，絕對不要用於一個範圍定義良好的功能。

  當地圖清晰後，它會進行交接，而不會直接建置：匯入主流程的 /to-spec 階段，由 /to-spec 將地圖中關聯的決策壓縮成一個可建置的計劃，然後像往常一樣進行 /to-tickets 和 /implement。直接將地圖迴圈送入 /implement 會跳過這個壓縮步驟，並丟棄關聯的細節，所以只有當工作量真的很小時，才直接跳到 /implement。

程式碼庫健康

不是功能開發，只是維護工作。

• /improve-codebase-architecture 在你空閒時可隨時運行，以保持程式碼庫適合代理操作。它會找出改善機會；選擇一個機會會產生一個 idea，你可以將它帶入 grill-with-docs 的主流程中。它是用來發現候選項目的調查工具；而 /codebase-design（見下方）則是你在選擇後進行設計的工作檯。

底層詞彙

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

• /domain-modeling：打磨專案的領域語言：質疑模糊的術語、解決一個詞語多義的問題（例如「帳戶」同時扮演三個角色）、將難以逆轉的決策記錄為 ADR。這是 /grill-with-docs 驅動的主動學科，用於保持 GLOSSARY.md 的清晰度。
• /codebase-design 是深層模組詞彙（模組、介面、深度、接縫、轉接器、槓桿、局部性），用於設計一個模組的形狀：在一個乾淨的接縫上，用一個小型介面封裝大量行為。/tdd 和 /improve-codebase-architecture 都會用到它。

階段邊界

一個階段是一個對話視窗內的一個工作區塊：例如打磨、實作、QA。在兩個階段的邊界上，你有五個選項，而選擇其中一個是整個地圖中最模糊的決策：

• 繼續：留在原地。沒有任何成本，也不失去任何東西。
• /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 應該長什麼樣子。「即拋式」是對程式碼如何撰寫的一種約束，而不是銷毀它的承諾：答案會被融入真正的程式碼中，而原型本身則作為主要參考資料保存在從主分支分出的 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 是編寫給代理閱讀的文件（例如 skills、AGENTS.md、指向的文件）的參考指南。

前置條件

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