pstack 系列（2）：改程式之前，先看懂再設計

AI 程式助理接到「改一下這個功能」，常常直接從第一個看起來合理的地方動手，用的也是它第一個想到的做法。這篇教你用 pstack 的五個 skill 把順序倒過來：先讓 AI 說清楚程式現在怎麼運作、為什麼長這樣，再讓它比較幾種設計，改完之後再找別的模型挑毛病。每個 skill 我都會說明什麼時候用、指令怎麼寫（附可以直接複製再改寫的範例）、它會一步一步做什麼、你會拿到什麼，以及下一步怎麼接。最後用一個虛構的例子把五個串起來，再附一張「什麼時候用哪一個」的對照表。

pstack 系列｜第 2 篇

• 系列導讀：這套 skill 是什麼、四篇該怎麼讀（尚未發布）
• 上一篇（第 1 篇）：安裝、選模型，再用 /poteto-mode 挑 playbook
• 下一篇（第 3 篇）：寫完程式之後，先證明它能用再合併

版本提醒：本文以 pstack 0.15.30 版為準，對應 cursor/plugins 的 commit eb4db2b（2026-10-22 14:08，台北時間），搭配 Claude Code 2.1.309。之後的版本，行為可能會改變。兩篇查證時用的版本不同，列在下表（第 1 篇正文沒有寫 Claude Code 的版本號）：

	第 1 篇	本篇
pstack	0.15.29（88d4751）	0.15.30（eb4db2b）
skill 數量	56	57
Claude Code	2.1.306	2.1.309

0.15.29 到 0.15.30 只新增了 statechart 這個 skill。本篇用到的 how、why、architect、interrogate、arena、poteto-mode，以及 Claude Code 對照說明都沒有改。我在 2026-10-24 10:31（台北時間）查證時，cursor/plugins 的 main 已經到 0.15.32（6dbc3ff）。eb4db2b 之後的 pstack 改動沒有碰到本篇用到的五個 skill、poteto-mode 的說明檔，以及本篇引用的指南段落。

開始之前

pstack 是 Cursor 官方外掛庫裡的一整組 skill。skill 是一份告訴 AI 怎麼完成某類工作的操作說明。安裝和選模型的方法在第 1 篇，這篇假設你已經裝好了。

指令要加前綴。 pstack 的文件用 Cursor 的寫法，例如 /how。在 Claude Code（在終端機裡使用的 AI 程式助理）裡，外掛的指令前面要加上外掛名稱，寫成 /pstack:how。下面的範例都用 Claude Code 的寫法；在 Cursor 裡，把 pstack: 拿掉就好。

這五個 skill 不會自己啟動。 它們都設定成不讓 AI 自行呼叫，所以你要親自輸入指令。另一個做法是把任務交給 /pstack:poteto-mode，讓它依任務自己排順序：例如在提示裡寫「先不要改任何程式」，它就會走唯讀調查，自動先跑 /how，遇到「為什麼」的問題再加上 /why。

下面會常出現「子代理」這個詞：skill 執行時，會另外派出幾個 AI 分頭做事，每一個就是一個子代理。派出去的子代理越多，用掉的額度通常也越多。

先看懂，再設計，改完再審查。/arena 可以單獨用，也是 /architect 內部用來比較草稿的工具。

/how：先弄懂程式現在怎麼運作

什麼時候用：要改一塊不熟的程式之前；或是想問「這段程式該放在哪裡、該由哪個模組負責、放在這一層對不對」。它只回答「現在怎麼運作」，不回答「為什麼這樣寫」，那是 /why 的工作。

指令怎麼寫：直接問你真正想知道的事。可以加上入口點和你最在意的部分：

/pstack:how <功能或模組> 是怎麼運作的？請從 <入口，例如某個 API 或指令> 開始，說明資料怎麼一路流動、每個檔案負責什麼。我最想知道 <你在意的部分>。

例如：

/pstack:how 使用者登入之後，session 是在哪裡建立、怎麼過期的？過期之後前端會發生什麼事？

它會怎麼做：

1. 先判斷問題的大小。問題範圍不清楚時，它會先說出自己的理解，直接開始找；理解錯了，你再糾正。
2. 簡單的問題（單一模組、一個小工具、像「這個函式怎麼運作」這種窄問題），只派一個子代理，邊讀邊解釋。拿不準時，它會選簡單的做法。
3. 複雜的問題（跨好幾個檔案或服務的子系統、整體架構），它會把問題拆成 2 到 4 個角度，各派一個只讀不寫的子代理同時去讀程式。
4. 全部讀完後，再派一個子代理把結果整合成一份說明。
5. 把這份說明交給你，最多做些小幅潤飾，不會大幅改寫。

你會拿到：一份給資深工程師看的架構說明，大小剛好夠你建立正確的理解，不會像逐行註解。用不到的段落會省略：

• Overview：這是什麼、做什麼、為什麼存在。
• Key Concepts：讀懂後面需要的型別（資料的種類和形狀，例如一筆訂單有哪些欄位）、服務或抽象概念。
• How It Works：最長的一段，說明什麼會觸發它、一步一步發生什麼、資料流到哪裡。會指出具體的檔案和函式；流程牽涉多個元件時，會附上流程圖。
• Where Things Live：開始動手時要知道的檔案和資料夾。
• Gotchas：不明顯、容易踩到的地方。

下一步：如果你接著想知道「為什麼會長這樣」，就跑 /why。pstack 指南的建議順序是先 how 再 why：先弄懂機制，再查歷史。如果已經懂了、準備動手，就跳到 /architect。

/why：查出程式為什麼長這樣

什麼時候用：想知道某段程式為什麼這樣寫、當初為什麼選這個做法、某個門檻數字從哪裡來，或是追查一次退化（原本正常、後來壞掉）的來龍去脈。它特別適合在你動手改之前用，先知道哪些地方有它的道理、不能隨便動。

指令怎麼寫：指出目標，說明你的問題。如果你是為了改它才問，記得說出來：

/pstack:why 為什麼 <某段程式或某個決定> 要這樣做？這個理由現在還成立嗎？我打算 <你想做的修改>。

例如：

/pstack:why 為什麼 API 的重試上限設成 5 次？這個理由現在還成立嗎？我打算把它改成可以設定。

如果你懷疑是歷史包袱造成現在的混亂，也可以一次要兩個：「先用 why 查歷史，再用 how 說明現在怎麼運作」。

它會怎麼做：

1. 確認目標和問題。 你說得不清楚時，它會從對話的前後文推測你指的是哪段程式，簡短說出它的解讀，然後繼續；猜錯了你再糾正。
2. 先把程式碼的線索整理好。 包括檔案和行號、關鍵的函式和常數、最近改過這段的 commit（commit 是 git 裡的一次修改紀錄），以及這些 commit 對應的 PR（合併請求）和討論。它會用 git blame（查每一行最後是誰、在哪次 commit 改的）和 git log 這類指令。
3. 分頭找證據。 它會先看你接了哪些 MCP（讓 AI 連到外部工具的接口，例如 issue 系統、Slack、Notion），把它們對應到七類證據：版本控制、issue 或工單、長篇文件、即時聊天、基礎設施監控、錯誤追蹤、產品數據。每一類有對應工具的，就派一個子代理同時去查。版本控制一定會查。沒查某一類時，要寫明原因。
4. 整合。 再派一個子代理，把所有發現依可信度整理：哪些有人明文寫過，哪些是幾個線索互相佐證，哪些只是推論，哪些查不到。
5. 交給你。 可以小幅潤飾，但不會改掉原本表達信心程度的措辭，例如「看起來是」不會被改成「就是」。

你會拿到：一份每一點都附來源的報告，段落包括：問題、相關的程式、找到了什麼、可以合理推論什麼、其他可能的解釋、還不知道什麼、查了哪些來源、信心總結。「查了哪些來源」每一類一行，連沒找到東西或跳過的也會列出來，並寫明原因。「沒有人寫下原因」本身也是一種答案。

如果你說了是為了改程式才問，報告最後還會多一份限制清單：哪些要保留（Preserve）、哪些可以改（Change）、哪些要避免（Avoid），以及有什麼風險（Risk）。

下一步：把這份 Preserve／Change／Avoid／Risk 清單帶到 /architect，當作設計的限制條件。

/why 會用你接上的 MCP 去讀 issue、文件和聊天紀錄，也會用 gh（GitHub 的命令列工具）讀 PR 的討論。開始之前，先確認你願意讓 AI 讀到哪些資料。權限怎麼收，可以參考裝了第三方 skill 和 MCP 之後，你的 Coding Agent 多了哪些破口？。

/architect：寫程式之前，先畫設計草稿

什麼時候用：不是小修小改、一動手就可能把結構定錯的工作。pstack 指南的分法是：改動會跨過函式的邊界，或會改變某段程式歸誰負責，就值得用 /architect。

指令怎麼寫：說明要做什麼，加上你最在意的地方。如果想在它動手實作之前先看設計，一定要寫 with checkpoint：

/pstack:architect with checkpoint. 幫我設計 <要做的功能>，設計完先停下來給我看，不要實作。我最在意 <呼叫端怎麼用／效能／之後好不好擴充>。限制：<上一步 /why 給的 Preserve／Avoid 清單>。

例如：

/pstack:architect with checkpoint. 幫我設計匯入資料的流程，設計完先停下來給我看。我最在意呼叫端怎麼用。

它會怎麼做：它會先開一份待辦清單，分成五個階段。

1. Ground（打底）：對新程式會碰到的每一塊，先跑一次 /how。如果這個設計會改變某段程式歸誰負責、放在哪一層，也會跑 /why，把原本的理由變成限制，而不是用猜的。只有完全從零開始、沒有現有程式要接的工作，才會跳過這一步。
2. Sketch（畫草稿）：用 /arena 讓幾個子代理各畫一份草稿，而且至少要有兩份結構完全不同的設計，不是在同一個設計裡改小地方。草稿只有型別、函式簽名（函式的名稱、參數和回傳值）和模組的分工，函式內容先標成「尚未實作」或寫成虛擬碼（看起來像程式、但不能執行的步驟說明）。每份草稿都會對照一份「設計警訊」清單檢查，例如對外介面很大、裡面卻沒藏多少東西，或同一份狀態有好幾個模組在寫。它會偏好對外介面小、把複雜度藏在裡面的設計。
3. Agree（確認）：預設不會停，畫完草稿就直接進入實作。只有你明確要求（例如寫 with checkpoint 或「實作前先停下來給我看」），它才會把設計交給你，等你點頭。你對設計有意見時，它會回到第 1 步重新打底、重畫草稿，再繼續寫程式。
4. Implement（實作）：照草稿把「尚未實作」換成真的程式。草稿就是約定；實作時如果發現草稿沒料到的需求，它要提出來，不會默默改掉。
5. Scrap（打掉重來）：如果實作一直卡住，例如同一種繞路寫法在不相干的地方一再出現，或型別要靠強制轉型才能編譯，它會把草稿整個丟掉：重新跑 /how，把新發現當成一開始就知道的條件重新設計，先刪減再增加，然後回到第 2 步。

你會拿到：先寫好的「呼叫端怎麼用」，再從它推出型別草稿。小改動是一個放新型別和函式簽名的檔案；大一點的工作是模組地圖加型別定義。旁邊附一頁設計說明，包括：問題、呼叫端的用法、建議的結構、選了哪份草稿當底和原因、接受了哪些取捨、考慮過的其他做法、需要你決定的問題和風險，以及下一步先實作什麼。

下一步：在 checkpoint 停下來時，回答設計說明裡的問題，同意後它再往下實作。如果這個設計很重要、改錯代價很高，可以在實作之前，先對草稿跑一次 /interrogate（草稿裡已經有具體的型別和函式簽名，不算抽象的計畫）；不然就等實作完，再對改動跑 /interrogate。

/interrogate：找幾個模型一起挑毛病

什麼時候用：程式改完、合併之前，想找出自己和 AI 都沒看到的問題。它要審的是實際的程式改動，不是抽象的計畫：拿一份沒有程式的計畫去審，審查者容易想出一堆根本不會發生的風險。

指令怎麼寫：指出要審什麼。範圍可以是幾個檔案、一份 diff（兩個版本之間改了哪些行），或整個 branch（git 裡的一條開發分支）。加上「先不要改任何東西」和「不要挑小毛病」，結果會更好用：

/pstack:interrogate 審查這個 branch 的全部改動，要嚴格。先不要改任何東西。除非是真正的 bug 或行為退化，不要挑小毛病。

只審幾個檔案時：

/pstack:interrogate 審查 <檔案或資料夾>。這次改動的目的是 <你想達成的事>。

它會怎麼做：

1. 確定範圍。 你指定了檔案或 diff 就用那些；如果你在 feature branch 上，它會用 git diff main...HEAD 取出整個 branch 的改動；你提到最近的工作，它就去找相關的檔案。
2. 先寫一段「這次改動想達成什麼」。 依據是你的訊息、commit 說明、PR 說明和程式本身。不確定時，它會先問你，再往下做。
3. 派審查者。 你設定的每個模型各派一位審查者，標成 Reviewer A、B……，大家拿到同一份範本、同一份改動和同一套評分標準。它靠的是不同模型有不同的盲點，不是替每位審查者設定不同角色。
4. 合併結果。 把描述不同、但其實是同一個問題的發現合在一起，記下是哪些模型提出的。兩個以上模型各自提出的問題，可信度最高；只有一個模型提出的也會看，但權重較低。
5. 主審判斷。 由它扮演務實的資深工程師，把每個發現分到四類，各附一句理由。

你會拿到：一份結論，依序是：改動的意圖、每位審查者用的模型和提出幾項、四類發現，以及一張 Agreement Map（各模型在哪裡意見一致、哪裡不同）。四類是：

• Act on：會影響正確性、安全性或可維護性，真正的 PR 會因此被擋下來的問題。
• Consider：有道理，但現在處理不一定划算，值得你看一下。
• Noted：技術上沒錯，但現在不需要處理。
• Dismissed：錯的、太瑣碎，或缺少前後文，附簡短理由。

它不會自動改你的程式。 要不要改、改哪些，由你決定。

下一步：先處理 Act on，再看 Consider。被歸到 Dismissed 的也要讀：主審只是務實的資深工程師，不是標準答案，你可以推翻它的判斷。

同一份改動交給幾個模型各自審查，再由主審分成四類。它不會自動改程式。

/arena：讓幾個 AI 各做一份，再挑最好的

什麼時候用：只做一次，很可能就把做法定錯的事。pstack 指南舉的例子是命名、資料格式和演算法這類單獨的決定。你也可以拿它要第二意見：把你現在的設計當成其中一份，看看其他做法有沒有更好的。它也是 /architect 第 2 步畫草稿時用的工具。

指令怎麼寫：說清楚任務、為什麼重要，以及你要幾份。決定越重要，可以要越多份；不重要就少一點：

/pstack:arena <任務>。這件事很重要，因為 <之後很難改／會影響很多地方>。要 <N> 份候選，每份用自己的 worktree。

例如：

/pstack:arena 幫我決定快取 key 的格式，要 3 份候選。這個格式之後很難改。

/pstack:arena 針對我們現在的做法給第二意見。

它會怎麼做：它會先開一份待辦清單，分成六個階段。

1. Frame（定規則）：每份候選拿到的提示完全相同，所以提示就是約定。它會先寫清楚每份候選要交出什麼，再訂 3 到 6 條可以打分的評分標準。評分標準是評審打分、以及它自己在第 4 步選底稿時用的，候選只看到任務。每份候選各有自己的工作位置（盡量用 git worktree，也就是同一個專案的另一份工作副本），避免互相覆蓋。
2. Fan out（分頭做）：同時派出 N 個子代理，各自完成任務，並附一段說明：考慮過哪些做法、為什麼不選。有一份沒交出東西時，就用剩下的 N-1 份繼續，並記下來。
3. Cross-judge（評審）：所有候選都完成後，派一位只讀不寫的評審，盡量選和主對話不同家族的模型（例如 Claude 和 Grok 是不同家族）。評審依評分標準逐條打分，推薦一份當底。
4. Pick（選底稿）：它自己也把每份候選從頭讀到尾，逐條依評分標準打分，再和評審的結果比較。兩邊選的一樣，就確定；不一樣，就代表有一邊有偏見，或評分標準寫得不清楚，要再讀兩邊的理由才決定。它會選一份之後最好擴充、又不容易破壞既有規則的版本。
5. Graft（嫁接）：再看一次落選的候選，每份通常挑一兩個值得搬過來的優點，親手融進底稿，而不是直接貼上。如果幾份候選做法一致，就直接用這個共同的做法，不必嫁接；如果彼此差太多，代表第 1 步的任務沒講清楚，要重新定規則再跑一次，而不是取平均。
6. Verify（驗證）：像驗證其他產出一樣，驗證合併後的結果。發現問題時，判斷是第 1 步定錯了（重來），還是某份候選其實抓到了、只是漏了嫁接（回到第 5 步）。

你會拿到：一份合併後的結果，加上一段簡短的說明：選了哪份當底和原因、評審的結論、每一項嫁接來自哪份候選、哪些被捨棄和原因、有沒有候選收斂或缺席，以及驗證的結果。

下一步：如果產出是程式，合併前可以再跑 /interrogate。如果你要的是「每個套件都檢查一遍」這種覆蓋，而不是比較做法，那是另一個 skill /swarm 的工作，不要用 /arena。

候選越多，派出的子代理就越多：N 份候選再加一位評審。

一個完整的例子（虛構）

以下是虛構的情境，只用來示範五個 skill 怎麼接在一起，不是實際執行的紀錄，也沒有附上任何輸出。

假設你維護一個網站，現在每來一則通知（有人留言、有人按讚），系統就寄一封信。你想加一個選項：使用者可以改成每天只收一封摘要信。

1. 先看懂現在的通知怎麼寄。

/pstack:how 通知是從哪裡觸發、怎麼排進佇列、最後由誰寄出信件的？我最想知道寄信這一步跟使用者偏好設定是怎麼接起來的。

讀它的 How It Works 和 Gotchas，確認你知道寄信的程式在哪裡、有哪些容易踩到的地方。

2. 查清楚為什麼現在是一則一封。

/pstack:why 為什麼通知是每來一則就馬上寄，而不是整批寄？這個理由現在還成立嗎？我打算加一個「每日摘要」的選項。

因為你說了打算修改，報告最後會有一份 Preserve／Change／Avoid／Risk 清單。例如它可能提醒你，某類通知當初就是為了即時才這樣設計，要保留。

3. 先畫設計，停下來給你看。

/pstack:architect with checkpoint. 幫我設計「每日摘要信」這個選項，設計完先停下來給我看。我最在意現有的即時通知不要受影響。限制：<貼上第 2 步的 Preserve／Avoid 清單>。

/architect 的第一步本來就會自己跑 /how，必要時也會跑 /why。這個例子前兩步先手動跑，是為了先看懂程式、也先檢查 AI 的理解有沒有偏；如果你不需要親自看，可以直接從這一步開始。它停下來時，讀設計說明裡「需要你決定的問題」，回答之後再讓它實作。

4. 遇到一個單獨的決定，交給 /arena。

假設設計說明裡有一個問題：摘要信的內容要依時間排，還是依通知類型分組？這種單獨的決定，可以另外交給 /arena：

/pstack:arena 幫我設計每日摘要信的內容格式，要 3 份候選。重點是讓使用者一眼看到最重要的通知。

5. 改完之後，合併之前審查。

/pstack:interrogate 審查這個 branch 的全部改動，要嚴格。先不要改任何東西。除非是真正的 bug 或行為退化，不要挑小毛病。

先處理 Act on，再看 Consider；Dismissed 也讀一遍，不同意就推翻它。

這個例子是逐一手動呼叫每個 skill，好讓你掌握每一步。平常你可以直接把目標和限制交給 /pstack:poteto-mode，它會自己決定要用哪些 skill、照什麼順序。這時候不要在提示裡逐一列出 skill，那會打亂它原本排好的順序；只有想改變預設做法時，才點名某個 skill。

什麼時候用哪一個

pstack 指南先講了一句很重要的話：大部分的改動，這些都不需要。下面是它建議的分法，加上 /how 和 /why：

情況	用哪個
要改一塊不熟的程式，先弄懂它現在怎麼運作	/how
想知道為什麼這樣寫、改之前哪些不能動	/why（說明你打算改它）
一個已經改完的小改動，但你不放心	只用 /interrogate
改動會跨過函式的邊界，或改變某段程式歸誰負責	/architect（它會帶上 /arena）
一個單獨的決定，例如命名、資料格式、演算法	直接用 /arena
有爭議、改錯代價很高的設計	先 /architect，合併前再 /interrogate
要做覆蓋，例如每個套件都檢查一遍	不是這五個，用 /swarm
想交給 AI 自己判斷	/poteto-mode，它已經內建這套分法

注意事項

• 額度：派出的子代理越多，通常越耗額度。/how 遇到簡單問題只派一個，複雜時是 2 到 4 個探索者加一個整合者；/why 每類有工具的證據各派一個，再加一個整合者；/interrogate 每個模型一位審查者；/arena 是 N 份候選加一位評審；/architect 裡面包含 /how、可能的 /why，還有一整場 /arena，派出的子代理通常是五個裡面最多的。小改動不值得動用 /architect 或 /arena。
• /architect 預設不會停：想在實作前看設計，要寫 with checkpoint。
• 不要只採用第一個設計：第一次做出來的設計，往往只是模型第一個想到的形狀。重要的設計，用 /architect 或 /arena 多看幾種。
• 不要審抽象的計畫：/interrogate 用在實際的程式改動上。
• 不要全盤接受審查意見：/interrogate 會把意見分類並附理由，但最後由你決定，兩個方向都可以推翻。
• 平行的 AI 不要共用一個工作目錄：它們會互相覆蓋，也分不出誰改了什麼。用 /arena 時，可以要求每份候選用自己的 worktree。
• 版本：以上依 pstack 0.15.30 的說明檔整理，之後的版本可能會改變做法。

結論

用 pstack 改程式之前，順序是：先用 /how 弄懂程式現在怎麼跑，需要時用 /why 找出不能動的理由；再用 /architect 寫好呼叫端的用法和型別草稿，記得加 with checkpoint 先看過；遇到單獨的決定，用 /arena 讓幾份候選比一比；程式改完，用 /interrogate 讓幾個模型各自挑毛病，再自己決定改哪些。不是每次都要五個全跑：小改動直接改，改完不放心再審查就好。

延伸閱讀

• 指南：Understand the code：/how、/why、/teach、/recall 各自適合的情況。
• 指南：Design：/architect、/arena、/swarm、/interrogate 和試作。
• 指南：Recipes and pitfalls：可以直接複製的提示和常見陷阱。
• 五個 skill 的說明檔：how、why、architect、interrogate、arena。
• pstack 系列（1）：安裝、選模型，再用 /poteto-mode 挑 playbook：怎麼安裝，以及 /poteto-mode 怎麼替任務排順序。
• 自己寫 Agent Skill：從寫 skill 的角度看 SKILL.md 的結構和測試。
• 裝了第三方 skill 和 MCP 之後，你的 Coding Agent 多了哪些破口？：agent 讀得到哪些檔案、權限怎麼收。
• 另一套 skill 的做法：mattpocock/skills 系列導讀、把模糊需求問清楚、先找出缺口，再決定要寫規格還是拆工作單、程式寫完之後，誰來看結構、審修改、解衝突、查資料、做交接、學新東西。