PStack 深讀（上）：一套 Cursor Plugin，如何把工程紀律變成可執行檔案

PStack 深讀系列｜上篇（本篇）講方法論骨架：為什麼、三層結構、24 條原則、23 個 playbook、poteto-mode。下篇（PStack 深讀（下）：兩個 agent、五個特別設計，與真正的落地方式）講執行體與落地：兩個 agent、benny 自動化、五個真正特別的地方、OpenClaw 與 DeepSeek Harness 的實作與限制。

本篇要回答的一個問題

為什麼一套寫成純文字檔的 Cursor Plugin，可以讓 AI agent 的工程輸出變得可預測、可審計？

答案不在模型，而在「把資深工程師的判斷寫成可執行檔案」。本篇先把 pstack 的骨架拆開：它由哪些層組成、24 條原則是什麼、23 個 playbook 如何覆蓋日常工程、以及 poteto-mode 這個「操作系統」怎樣把一切串起來。

1 為什麼又一套 agent 方法論？

AI coding agent 氾濫的今天，「agent 方法論」已經是個被用壞的詞。大部分這類專案賣的是同一件事：更多代碼、更快產出。pstack 的作者 Lauren Tan（網名 poteto）——先後任職 Meta、Netflix、Cursor，亦是 React core team 成員，參與維護 React Compiler——對此的診斷非常直接：「there's a growing sense that ai writes too much slop code. i agree.」（README.md）。她給出的目標也與主流相反：「pstack helps you write less, but higher quality code.」（README.md）。

這不是姿態。pstack 真正解決的問題是：agent 的工程判斷不應該依賴每次對話的即興發揮。市面上的 agent 工具普遍把品質寄望於模型變強——模型外面那層運行系統叫 harness，不熟的讀者可以先看 Agent Harness 是什麼：模型外面那層普通程式——pstack 把品質寄望於紀律被文件化：把「資深工程師如何做決定」寫成 24 條具名原則，把「這類任務如何執行」寫成 23 個 playbook，再用一個名為 poteto-mode 的操作系統把兩者接起，並強制 agent 在回覆中具名引用它依據的原則。判斷被文件化，文件被機械引用，引用可被審計——這條鏈是 pstack 與「一堆寫得漂亮的 prompt」的根本分別。

README 對這套東西的用途有一個準確的詞：「fearless parallelism」——當你可以信任一個 agent 深入工作、寫出可驗證的代碼，並行才真正安全。這也解釋了為什麼這套方法論的細節如此偏執：它設計給多 agent 並行、甚至通宵無人值守的場景，任何一環沒有驗證，並行只會放大錯誤。

2 三層結構：一張圖看懂

pstack 本體是一疊純文字檔（Agent Skills 格式，skills/<name>/SKILL.md，想認識這個格式可以先讀 Addy Osmani agent-skills 開源項目深度解析），以 Cursor plugin 形式發佈，不依賴 Cursor 專有機制——對 Cursor 本身不熟的讀者可以先看 Cursor 是什麼：住在你編輯器裡的 AI 編程工具。它的結構可以概括成三層加兩個執行體：

三層的分工值得說清楚。原則層管判斷力：何時該懷疑前提、何時該親自驗證、何時不該等人。流程層管執行：bug fix、perf、shipping、overnight run 等任務各有固定步驟。支援層是工具箱：how／why 做理解，architect／arena／swarm／interrogate 做設計與對抗審查，unslop／no-comments／tdd 做清理與紀律。poteto-mode 是唯一入口，README 說得明白：其他 skills「are situational, and the mode skill uses them for you as needed」（README.md）。agents 與 automations 則是把方法論延伸到委派與無人值守場景。

3 原則層：24 條具名原則

24 條原則分為五組：Core 十條、Architecture 六條、Verification 五條、Delegation 兩條、Meta 一條（分組見 skills/poteto-mode/SKILL.md 的 Principles index，全名見附錄）。每條都是獨立檔案，格式一致：一段 description 說明「何時套用」，正文給理由與模式。這個「何時套用」的設計是關鍵——原則不是格言，是觸發條件。

深講三條。

attack-the-premise（skills/principle-attack-the-premise/SKILL.md）。原文開宗明義：「When two or more fixes that share one premise have failed the same gate, suspect the premise, not the fixes.」——兩個以上共用同一前提的修法，在同一關卡失敗，該懷疑的是前提，不是修法。它甚至設了硬性停止規則：「Do not start the next fix before the premise is written down and tested.」寫下前提、直接檢驗它，才准開始下一個修法。這條原則精準對準 AI agent 最常見的失敗模式：同一招撞牆三次，每次只換參數。它還自我界定了與 redesign-from-first-principles 的分別：後者圍繞新需求重建設計，前者質疑現有設計所假設的一個事實。

prove-it-works（skills/principle-prove-it-works/SKILL.md）。原文：「Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or 'it compiles.'」驗證要對準真實產物——跑功能、讀實際值、看 diff——而不是代理訊號。這條原則有兩處特別成熟。一是把懷疑方向寫死了：「When verification fails, suspect the observation method before suspecting the system」——驗證失敗時先懷疑觀察方法，再懷疑系統，避免 agent 把「量測錯了」當成「系統錯了」亂修。二是要求把驗證變成可重跑的腳本：「The strongest proof is a deterministic script that re-runs the same comparison」——最強的證明是一個確定性的、可重跑同一比較的腳本，而非一次性目測。

never-block-on-the-human（skills/principle-never-block-on-the-human/SKILL.md）。原文第一句就是世界觀：「The human supervises asynchronously. Agents must stay unblocked.」——人類是異步監督者，agent 必須保持不被阻塞。它的成本收益分析寫得很直白：「a wrong decision usually costs less than blocking」——代碼改動可逆、可審，錯誤決定通常比等待便宜。邊界同樣清晰：不可逆動作（force-push、刪生產數據、發外部訊息）仍需確認；產品方向由人定，執行不該等人。

這三條合起來，就是 pstack 的靈魂：懷疑該懷疑的，證明該證明的，其餘的自己走。

其餘二十一條按組讀，可以讀成一條完整的決策鏈。Core 組管「怎樣動手」：laziness-protocol 要求偏向刪除與最小改動；build-the-lever 要求任何非平凡工作都先造工具——codemod、腳本、生成器——理由在原則索引裡寫明：「The tool is the artifact a reviewer can rerun」（skills/poteto-mode/SKILL.md）——工具才是 reviewer 可以重跑的產物。Architecture 組管「怎樣設計」：type-system-discipline 要非法狀態無法表示；make-operations-idempotent 要求操作在崩潰與重試中收斂到同一終態。Verification 組管「怎樣收尾」：explain-the-number 要求在信任任何量測數字前，先找出限制它的因素；fix-root-causes 規定「A guard is a fix only when the state it handles is legitimate」（skills/principle-fix-root-causes/SKILL.md）——防禦式檢查只有在所處理的狀態本身合法時，才算修復，否則只是掩蓋症狀。Delegation 組管「怎樣分身」：guard-the-context-window 把批量工作路由給子代理，主線程只留摘要。Meta 組只有一條 encode-lessons-in-structure，值得每個團隊抄走：同一條指令要寫第二次時，把它變成 lint、元數據標記、運行時檢查或腳本，而不是更多文字。

4 Playbook 層：23 個具名流程

poteto-mode 內置 23 個 playbook（skills/poteto-mode/playbooks/）。倉庫本身是平鋪列表，下表的五類分組是本文的分析，方便對照：

每類舉幾個實際用法。

診斷類。 investigation（playbooks/investigation.md）值得先講：它是唯一定位為「只讀」的主流流程，產出是帶引用的解釋或建議，不是代碼改動；回覆格式固定為 how 技能的結構（Overview / Key Concepts / How It Works / Where Things Live / Gotchas），而且明文要求「Push back if the premise is wrong」——問題本身問錯了，要直說，不准硬答。README 給的用例是：「/how do we cancel runs? do we have an n+1 when we look up every run to cancel?」。bug-fix（playbooks/bug-fix.md）第一步就是親手重現：「Reproduce it yourself on the matching surface … even when a debug or instrumentation protocol says to ask the user to reproduce」——不許把重現推給用戶。其鐵律是「Every shipped line traces to runtime evidence」，每一行落地的代碼都要能追溯到運行時證據；提交順序也有規定：失敗重現先於修復進 git 歷史，讓 reviewer 看到「先紅後綠」。hillclimb（playbooks/hillclimb.md）是對單一指標的持續科學改進，紀律是「one change, one measurement, keep or revert」，配一本 decision.tsv 決策日誌，連停止條件都要求「a target with a floor on attempts」——防止一次僥倖早贏就收工。

交付類。 shipping（playbooks/shipping.md）的第一句是「Green is not safe.」——CI 全綠不等於安全。它要求每個 PR 由一個獨立驗證 agent 以用戶方式實跑，並寫明「Only a verdict from an agent that did not write the code counts」，因為作者會按自己的意圖驗收；落地順序必須是自底向上、只落「連續已驗證段」。autopilot-full 則是一列獨立 PR 各自帶一個 owner 推到 merged，root 端 swarm 在每個 merge 前再驗一次。

設計／建構類。 prototype（playbooks/prototype.md）是 never-block-on-the-human 的流程化：遇到「該用哪個方案」的分岔，如果答案可以靠跑一次就觀察到，就不許問人，畫個 sketch 讓結果說話。visual-parity 處理像素級 UI 等價，常見於遷移樣式系統。

協作／會話類。 session-pickup 從 transcript、雲端 agent URL 或已推分支接手上一個 agent 的在途工作；pause-safely 是它的補集——乾淨掛起以便恢復，觸發時機包括上下文即將被壓縮。實際用法：接手一個通宵 agent 留下的半成品，用 session-pickup 從 transcript 重建狀態再決定走向；下班前用 pause-safely 掛起，確保明天還能準確續上。

治理類。 eval（playbooks/eval.md）測試「改一個 SKILL.md 會如何影響 agent 行為」，而且要盲測——方法論連自己的改動都要做對照實驗。worktree-cleanup 回收磁碟，全程帶安全閘。

5 poteto-mode：操作系統，不是單一技能

把 poteto-mode（SKILL.md 約千行規則）讀完，你會發現它不是一個 skill，而是一個小型操作系統。四個部件：

Non-negotiables（不可讓步項）。 一組觸發規則，把情境硬綁到技能或原則：任何代碼先講 data shape、跨函數邊界先過 architect、任何文字表面（包括給用戶的回覆）過 unslop、review 前過 no-comments、跑 benchmark 報數字前過 benchmark-checklist、PR 狀態請求一律走 babysit。開頭第一條最重要：「In your reply, name each principle that shaped a decision and the specific choice it changed. Cite only principles whose leaf SKILL.md you read this session.」（skills/poteto-mode/SKILL.md）——回覆中要具名每條影響了決定的原則，以及它改變了哪個具體選擇；而且只准引用本次會話真正讀過全文的原則。這是防「口頭引用」的機制：沒讀過檔案就沒有引用權。

回覆風格（Writing the reply）。 短陳述句、一句一個想法、全文禁用長破折號、禁止句中冒號；「Frame impact for the consumer and the maintainer」——先講對使用者與維護者各意味著什麼，再談實現；還有一條對 AI 輸出最致命的約束：「Every claim carries its evidence or its label in the same sentence. Measured, inferred, or guess.」——每個主張在同一句裡自帶證據或標籤：量測的、推斷的、還是猜的。不准把猜測包裝成結論，不准交給人類一個自己能跑的檢查。

Autonomy（自主權）。 預設是「Just do it.」：可逆工作與外部動作（團隊聊天、工單更新、啟動 eval）不問自做。硬邊界只有一條：「Always pause」留給不可逆寫入：對共享分支 force-push、部署、刪數據、發客戶訊息。最有趣的是態度條款：「No is an acceptable answer.」——被邀請擴範圍時，真實判斷優先於順從：「candor over sycophancy」。同意不是預設值。

Subagents（委派）。 playbook 內 spawn 的任何子代理都用 poteto-agent 類型；模型按角色分工：代碼委派預設 grok-4.7-xhigh-fast，最難的改動與文字、判斷走 claude-opus-5-5-xhigh（README 說 /setup-pstack 可改）。還有一條容易忽視的紀律：「Fresh subagents by default」——新工作預設開新 agent 並帶上合併後的完整上下文，只在狀態難以搬遷時才復用舊 agent，因為「Interrupt-chained resumes silently drop directives」——中斷式續用會悄悄丟指令。

6 動手驗證：三十行 Python 檢查「具名原則」紀律

poteto-mode 的第一條 Non-negotiable 要求每個決策具名引用原則。按照 encode-lessons-in-structure 的精神，這條紀律本身就可以變成一個可重跑的腳本：檢查一段 agent 回覆裡的每個決策，是否都附有已登記的原則名。以下腳本只用標準庫，輸出確定，可以直接重跑：

#!/usr/bin/env python3
"""pstack 紀律檢查器：每個決策都要具名引用一條原則。

模擬 poteto-mode 的第一條 Non-negotiable：
"In your reply, name each principle that shaped a decision
 and the specific choice it changed."
"""
import re
import sys

# 24 條已登記原則（與 pstack skills/principle-*/ 檔名一致）
PRINCIPLES = {
    "laziness-protocol", "foundational-thinking",
    "redesign-from-first-principles", "attack-the-premise",
    "subtract-before-you-add", "minimize-reader-load",
    "outcome-oriented-execution", "experience-first",
    "exhaust-the-design-space", "build-the-lever",
    "model-the-domain", "boundary-discipline",
    "type-system-discipline", "make-operations-idempotent",
    "migrate-callers-then-delete-legacy-apis",
    "separate-before-serializing-shared-state",
    "prove-it-works", "fix-root-causes",
    "sequence-verifiable-units", "test-behavior-not-implementation",
    "explain-the-number", "guard-the-context-window",
    "never-block-on-the-human", "encode-lessons-in-structure",
}

DECISION = re.compile(r"^Decision:\s*(.+)$", re.M)
CITED = re.compile(r"\[(?:principle:\s*)?([a-z0-9-]+)\]")

REPLY = """Decision: kept the fix to two lines instead of a new helper [principle: laziness-protocol]
Decision: wrote a repro script before touching the fix [prove-it-works]
Decision: wrote the premise down and tested it directly, after two fixes on the same assumption failed [attack-the-premise]
Decision: added a retry loop to be safe
Decision: rewrote the parser in one pass, it feels faster now [code-harder]
"""


def check(reply: str) -> int:
    problems = 0
    for i, m in enumerate(DECISION.finditer(reply), 1):
        text = m.group(1)
        cited = CITED.findall(text)
        if not cited:
            print(f"FAIL decision #{i}: no named principle -> {text[:48]}...")
            problems += 1
            continue
        for p in cited:
            if p not in PRINCIPLES:
                print(f"FAIL decision #{i}: cited unregistered principle '{p}'")
                problems += 1
            else:
                print(f"PASS decision #{i}: {p}")
    return problems


if __name__ == "__main__":
    src = open(sys.argv[1], encoding="utf-8").read() if len(sys.argv) > 1 else REPLY
    n = check(src)
    total = len(DECISION.findall(src))
    print(f"\n{total} decisions checked, {n} problem(s)")
    sys.exit(1 if n else 0)

實際執行（macOS，Python 3）輸出如下——注意第 4 個決策沒有具名原則、第 5 個引用了不存在的 code-harder，兩者都被抓出來，腳本以 exit code 1 收場：

PASS decision #1: laziness-protocol
PASS decision #2: prove-it-works
PASS decision #3: attack-the-premise
FAIL decision #4: no named principle -> added a retry loop to be safe...
FAIL decision #5: cited unregistered principle 'code-harder'

5 decisions checked, 2 problem(s)

把這類檢查接進 CI，就是「判斷被文件化，文件被機械引用，引用可被審計」的最小閉環：agent 講得出原則，機器驗得出它講沒講。

附錄：24 條原則一覽（與檔名一致）

Core（10）：laziness-protocol · foundational-thinking · redesign-from-first-principles · attack-the-premise · subtract-before-you-add · minimize-reader-load · outcome-oriented-execution · experience-first · exhaust-the-design-space · build-the-lever

Architecture（6）：model-the-domain · boundary-discipline · type-system-discipline · make-operations-idempotent · migrate-callers-then-delete-legacy-apis · separate-before-serializing-shared-state

Verification（5）：prove-it-works · fix-root-causes · sequence-verifiable-units · test-behavior-not-implementation · explain-the-number

Delegation（2）：guard-the-context-window · never-block-on-the-human

Meta（1）：encode-lessons-in-structure

下篇預告

方法論骨架講完，下篇（PStack 深讀（下）：兩個 agent、五個特別設計，與真正的落地方式）會進入「執行體」與「特別之處」：

• poteto-agent 與 comment-sicko 兩個 agent 的分工
• benny 如何把 Slack issue 變成可重現的修復
• pstack 真正特別的五個設計（原則具名、premise attack、prove-it-works、never-block、harness 可移植）
• 在 OpenClaw 與 DeepSeek Harness 是什麼：「一切皆插件」的開源 Agent 運行環境 落地的注意事項
• 這套方法論的限制與批評

資料來源與版本

• 內容事實主要出自 cursor/plugins 倉庫 pstack/ 目錄：README.md、skills/poteto-mode/SKILL.md、skills/principle-*/SKILL.md、skills/poteto-mode/playbooks/。引號內英文均為原文件原文。
• pstack 於 2026-05-23 經 PR #73 合併進 cursor/plugins；本文基於 2026-10-21 檢視的版本撰寫，24 條原則與 23 個 playbook 清單已與 README 逐項核對。
• 第 4 節的五類 playbook 分組為本文的分析（倉庫本身是平鋪列表）；第 6 節腳本為本文原創示範，輸出為實際執行結果。