在我的上一篇文章中，我向你展示了為什麼驗證是我與 Agent 合作的一切基礎，以及如何開始建立你自己的驗證技能。關鍵的教訓是，如果一個 Agent 無法驗證自己的工作，那麼其他一切都無關緊要。你仍然是瓶頸，你的整個一天都將花在監督你的 Agent 上。
https://x.com/poteto/status/2094457600259842065
但一旦你有了驗證機制，接下來的問題是：你實際上要如何弄清楚該建立什麼？
https://x.ai/bot/plugin/9717366
在這篇文章中，我將帶你了解我如何使用 pstack 進行研究、規劃、原型設計和架構設計。正是這個工作流程讓我能每個月將數千個 PR 部署到生產環境，同時保持極高的程式碼品質。
八月底，生產環境中有 2,462 個 PR
監督比你聰明的人的藝術
回到 2024 年的舊時代，要對系統進行任何更改，你首先需要閱讀足夠多的程式碼，以建立一個關於系統運作的心理模型。根據程式碼庫的大小和複雜度，這可能需要你花費數小時，甚至數天或數月的時間。對於一個小改動，你可能只需要對一個小子系統有局部的理解。然而，如果你要重構核心部分，你可能需要對整個系統的運作方式有一個心理模型，才能正確且有效地進行重構。
Agent 顯然消除了這個障礙。你可以非常輕鬆地透過提示你的 Agent 來對系統進行更改，它就會執行，無論你對程式碼了解多少。但是，保持程式碼和使用者體驗的高品質仍然很困難，特別是如果你還不是一個知道該尋找什麼和詢問什麼的領域專家。
儘管前沿模型已經變得非常強大，但我仍然經常觀察到兩種失敗模式：
- 它們無法完全理解你的意圖，因為意圖的說明不足或說明不當。
- 它們沒有足夠的上下文來正確地完成工作。
這兩個問題是相關的。善用 Agent 歸結於你能否很好地用高品質的上下文來填充 Agent 的上下文視窗。你當然可以在不這樣做的情況下寫出能運作的程式碼，但我發現，當我花費心力為我的 Agent 提供它們完成高品質工作所需的一切時，結果和品質會好得多。
用你自己的話來說
前沿模型是非常有能力的程式設計師。雖然對於較舊的模型，我可能會非常具體地提示我想要它做什麼，幾乎是微觀管理它們，但最新的模型能夠寫出比你或我更好的程式碼。因此，我想要在告訴 Agent 我希望它達成什麼目標，同時給予它用我可能沒想到的方式來解決問題的自由之間，取得一個良好的平衡。
這就是監督比你聰明的人的藝術，監督的對象是一個你沒有親自編寫的程式碼庫，而且人類已經無法在腦中容納整個程式碼庫的心理模型。
我喜歡使用的一種技巧是間接提示。我不是直接告訴 Agent 我確切想要什麼，而是試著引導 Agent 自己說出來——用它自己的話。
例如，當有人在 Slack 中回報一個問題時，我經常會先要求 Agent 閱讀整個討論串，並用自己的話重新陳述問題，然後再進行其他操作。
例如，我可能會說：
/poteto-mode 閱讀這個 Slack 討論串。用你自己的話，以簡單明瞭的英文，重新陳述你認為的根本問題是什麼
這達到了三個目的：
首先，它迫使 Agent 將一個雜亂的對話壓縮成一個結構化的問題陳述。其次，它讓我能立即發現誤解。如果 Agent 執著於討論串中的一個誤導性線索，我可以在它開始編寫任何程式碼之前迅速糾正它。
第三，我沒有因為陳述我自己的假設和推測而可能將它引導到錯誤的方向，這些假設和推測可能是錯誤的，或者會限制 Agent 原本可以達成的成果。
建立心理模型
要求 Agent 以你能理解的方式重新陳述，是與比你聰明的人合作的重要一環。這也是 /teach 這個技能的靈感來源，它能幫助你的 Agent 以直觀的方式向你解釋事情。每當我需要確保我的 Agent 正在做的事情對我來說合理時，我就會使用它。
/how 追蹤執行時的機制。當你問 /how 時，Agent 會評估子系統的複雜度。如果子系統跨越多個目錄或服務，它會產生並行的探索 Agent，使用像 Grok 這樣快速、高效的模型。
/how 虛擬化是如何實現的？
/why 調查動機和意圖。程式碼告訴你發生了什麼事。它很少告訴你為什麼有人會那樣寫。當你執行 /why 時，pstack 會並行查詢跨越多個來源的歷史證據：Git 歷史和 PR 審查評論、Linear 工單、Notion 設計文件、Slack 對話、Datadog 監控、Sentry 錯誤、程式碼譜系以及分析倉庫事件。
/why 我們為什麼還卡在舊版的 node.js？
每當我希望 Agent 重新陳述某些內容，以便我能更好地理解和信任它的工作時，我就會使用 /teach。
/teach 我，為什麼你用這種方式實現，而不是 <其他方式>。你做了哪些取捨，為什麼？
在實踐中，我也發現 /teach 技能所做的研究不僅對人類有用，對 Agent 也有幫助。即使是最新的前沿模型（這也取決於 harness 的品質），我通常發現它們仍然經常自信地陳述事情，卻沒有用數據來支持，或者沒有實際閱讀建立心理模型所需的程式碼。因此，這個教你它將要做什麼以及為什麼要這麼做的行為，最終也幫助了 Agent 本身。
從歷史中學習
我的許多專案都跨越多次對話。例如，幾個月前，我正在修復人們在 Cursor 中回報的虛擬化錯誤和效能問題。我意識到，每次我開始一個新的聊天時，都必須從頭開始建立我的 Agent 之前在解決類似問題時所擁有的豐富上下文。
我意識到的是，你過去的對話記錄通常是豐富上下文的金礦。pstack 內建了 /recall 技能，可以從聊天歷史中提取你最近的上下文，這樣即使是全新的 Agent 也能擁有回到良好狀態所需的正確上下文。
/recall 我昨天在虛擬化方面做的工作，然後閱讀 Slack 上的這個錯誤報告
使用 /teach、/recall、/how 和 /why 是我讓自己對程式碼庫的心理模型保持更新、並壓縮成我能輕鬆理解和記憶的形式的方法。而且，這對 Agent 也有幫助！
逆向工作
一旦你理解了問題，你要如何指定解決方案？
在我看來，大多數具有規劃模式的 harness 往往過度指定實作細節，而對其他所有方面的指定則不足。這就是為什麼在 pstack 中，我戲謔地說過「我不相信規劃」。事實是，我確實會規劃，但我是透過程式碼來規劃的。
對於某些類型的工作，例如建立供他人使用的共享程式碼或套件，我非常信奉 readme 驅動開發。如果你不熟悉它，這是一種過去很流行的開發技巧，你從精心撰寫 readme 開始。這迫使你戴上開發者體驗的帽子，從向一個假想的使用者描述 API 開始，然後逆向工作到實作和架構。
例如，當我在建立 Dune（我們用於桌面應用程式的內部客戶端框架）時，我首先為它撰寫了一個教學，這樣我就能理解用它來建立應用程式會是什麼樣子。或者至少我嘗試這麼做了。要讓 Agent 產生任何好或可讀的內容，確實是一場掙扎。所以我必須先花一些時間磨利我的刀，也就是建立 /technical-writing 技能。
沒有使用 /technical-writing 技能的第一版 readme 讀起來很痛苦，因為它混淆了不同的目標。它試圖在同一個文件中同時扮演教學、操作指南、架構解釋和 API 參考的角色，並且帶有常見的 AI 廢話和矯揉造作的文風。
/technical-writing 使用 Diátaxis 框架 將文件分為四種不同的模式：
- 教學： 從做中學。引導新手透過一系列步驟來建立可見成果的課程。
- 操作指南： 為有經驗的使用者解決特定、實際問題的步驟。
- 參考資料： 對機器、API 和配置標誌進行乾燥、完整、權威的技術描述。
- 解釋： 高層次的討論，用以釐清和闡明背景、設計選擇和取捨。
它也使用了 /unslop，因此產生的文件非常易讀。
以這種方式撰寫計劃非常有幫助，因為它也為你的 Agent 提供了一個具體的目標和目的，讓它可以根據這個目標來檢查自己的工作。當然，也更易於理解 Agent 究竟要建立什麼。
pstack 的許多技能在設計階段會在這裡疊加。例如：
(1) /recall 我過去 7 天在修復虛擬化錯誤和效能問題方面的工作。使用 /how 和 /why 來理解我們目前的虛擬化實作是如何運作的。
(2) 然後使用 /poteto-mode planning 和 /technical-writing 來提出一個全新的虛擬化引擎，能夠徹底消除閃爍和抖動。讓我們先寫一個教學，說明我將如何使用這個新套件來虛擬化一個 React 應用程式
(3) 在你寫好計劃後，/teach 我，並向我證明為什麼這個新方法優於我們目前的引擎
這裡的技巧實際上是關於提取有趣且豐富的上下文，讓你的 Agent 能夠像你一樣看待問題——而不僅僅是一個小片段：
- 提示的第一部分回顧了關於虛擬化在我的應用程式中如何實現的相關過去和現在上下文。
- 第二部分引導 Agent 使用該上下文，例如它之前修復過的錯誤，來提出一個能完全消除這些問題的新設計。
- 最後一部分是要求你的 Agent 向你證明這個新套件是更優越的。這就是像驗證技能這樣的高品質工具很重要的地方。
百般衡量，一次裁切
在規劃時，我看到最常見的兩個錯誤是：
- 接受 Agent 的第一個設計。
- 在沒有經驗證據的情況下過度規劃。
當人類編寫程式碼時，我們經常透過設計文件相互協作。這些文件討論高層次的架構、考慮過的替代方案、取捨以及任何不尋常的實作註記。在達成最終設計之前，這些文件經歷多次迭代是非常常見的。
有了 Agent，雖然我們可以跳過設計文件的繁文縟節，但我經常看到人們犯下接受 Agent 給出的第一個結果的錯誤。有了 pstack，我們可以將「百般衡量，一次裁切」的方法發揮到極致，使用並行 Agent。
我們透過使用原型設計 playbook 來做到這一點。
在 pstack 中，playbook 不是技能，而是 /poteto-mode 內部的參考文件。這些 playbook 會根據你正在處理的任務類型（為了 token 效率）有條件地載入。截至 0.15.0 版本，這 23 個 playbook 各自包含一個我在執行任務時使用的工作流程。
與技能不同，playbook 會由 Agent 作為 /poteto-mode 的一部分自動使用。例如：
/poteto-mode 為新的下拉選單原型設計幾個選項 /poteto-mode 修復這個錯誤 /poteto-mode 評估這個技能變更
原型設計是我最喜歡的 pstack playbook 之一。它為一個目標提供多次嘗試，並幫助 Agent 推理出最佳選項。這不僅對視覺原型設計有用，也對功能、錯誤修復等的不同解決方案進行原型設計很有用。
/poteto-mode 為 <功能需求> 原型設計幾個選項。使用 /control-app* 並錄製影片/截圖供我審查和選擇
\ 注意：/control-app 是我們在 [第 1 部分]([https://x.com/poteto/status/2094457600259842065](https://x.com/poteto/status/2094457600259842065)) 中建立的驗證技能*
在對視覺變更進行原型設計時，Agent 會在你的應用程式中或一個暫存目錄中建立可拋棄的草稿。如果它正在測試一個 UI 互動，它會將兩到三個變體放在一個簡單的切換器後面。然後它使用 /control-app 技能驅動互動，為每個變體截圖，並測量實際的時序或佈局。
原型設計就是規劃，但用的是程式碼。它允許 Agent 自由探索問題空間，並給它們一個機會，用你自己想不到的東西給你驚喜。原型允許 Agent 用經驗證據回答自己的問題，而不是等待我的輸入。
架構更大的變更
作為 Agent 時代的工程師，花時間在架構、選擇正確的資料結構以及思考我建立的系統將如何協同工作上變得更加重要。我的 Agent 則負責填補實作細節。
pstack 內建的另一個有用的技能是 /architect。它將設計結構化為不同、有紀律的階段：
- 立足問題。 Agent 對受影響的系統執行 /how 和 /why，以建立對現有所有權和限制的準確心理模型。
- 草擬。 Agent 進入一個架構競技場。它並行產生獨立的候選執行者，通常跨越多個模型家族。每個執行者接收立足簡報，並起草一個完整的設計套件：呼叫者的使用草稿、核心型別定義、公開函式簽名以及簡潔的 rationale。這些通常是透過僅草擬型別簽名來完成的，這些簽名源自於我們希望呼叫站點看起來的樣子。每個執行者必須評估介面深度，檢查弱模型上的失敗模式，並根據我們的設計紅旗目錄進行篩選。
- 交叉評判與綜合。 一個使用與主要 Agent 不同模型的交叉評判 Agent，根據嚴格的評分標準評估候選方案。
- 根據草稿實作。 Agent 用真實邏輯取代草稿的佔位主體。如果 Agent 在實作過程中發現某個函式需要意外的參數或額外的狀態，它會揭露這個差異。
- 設計錯誤時捨棄。 如果在實作過程中我們發現草稿是錯誤的，Agent 會全部拋棄並重新開始。
這裡的重點是給 Agent 一個自包含的小型循環，讓它可以將來自不同模型家族的多個競爭設計綜合為一個最佳方法，並且注意要嚴謹，如果根據經驗證明它提出的架構是錯誤的，不要害怕拋棄它的設計。如果相同的解決方法出現在不相關的呼叫站點，或者型別需要像 any 或強制轉換這樣的逃生艙口，這就是架構錯誤的經驗證明。
/architect 這個新的 <功能需求>
這裡的重要教訓是，使用 /poteto-mode 的原型設計和 /architect 來用程式碼規劃要有效得多。
這也是為什麼我從來不費心去對抗性地審查抽象計劃。Agent 會開始幻想起理論上的風險，並發明複雜的邊緣情況來防範永遠不會發生的問題。當你的計劃仍然是抽象的時候，不要過度規劃：讓 Agent 透過原型設計和驗證自己的工作來自行回答未解決的問題。
好吧，但我真的很想要一份規劃文件
雖然 pstack 沒有附帶規劃技能，但它確實內建了一個多階段規劃 playbook。我通常在 Agent 提出一個我滿意的設計後使用它，作為建立戰術執行計劃的一種方式。
/poteto-mode 將這個設計轉化為一個計劃
計劃中的每一個任務都圍繞著證明和驗證來建構。playbook 告訴 Agent，僅有測試是不夠的驗證。只有當它實際執行了程式碼並驗證其運作正常時，才算驗證完成。
每個計劃都由一個自動化腳本檢查，該腳本驗證其結構和格式。一旦獲得批准，計劃就會逐項執行。每個 PR 都很小、自包含且易於審查。
對於真正大型的專案（例如可能需要我整整一週的專案），我有時可能會決定將計劃暫時提交到程式碼庫中，以便其他 Agent 知道正在進行中的工作。但我通常會在完成後刪除它們，以免讓程式碼庫處於混亂狀態。我認為永久保留計劃沒有價值。
實踐中的工作流程
為了了解所有這些部分如何組合在一起，讓我們來看三個具體的例子，說明我如何提示這些工作流程。
範例 1：研究一個不明確的錯誤
當生產環境中出現一個問題，且根本原因不明時：
/poteto-mode 調查為什麼背景工作程式會定期出現超時錯誤。給我一份關於我們已知資訊、你使用的數據以及你最佳推測的詳細說明。
Agent 會並行探索程式碼、檢查指標和歷史提交，並給你關於問題可能出在哪裡的最佳推測。
範例 2：設計一個新的服務邊界
當引入一個其他模組將依賴的新子系統時：
/poteto-mode 我們需要為外部 webhook 添加速率限制。先用 /architect 進行架構設計，並用原型回答任何未解決的問題。讓我在繼續之前先審查。
Agent 會立足現有的 webhook 架構，跨多個模型啟動競爭的設計執行者，用可拋棄的原型進行基準測試，並產生一個乾淨、經過驗證的介面。
範例 3：執行一個多 PR 遷移
當跨多個檔案執行複雜的重構時：
/poteto-mode 建立一個計劃，將我們整個 UI 函式庫遷移到 StyleX。將遷移分解為小的、可驗證的 PR。每個 PR 必須有其視覺回歸測試和即時驗證步驟。我希望最終結果與原始版本 100% 相同——包括錯誤在內
Agent 將工作分解為獨立的步驟，撰寫一個可稽核的檢查清單，並準備好每個單元，以便能夠安全地建置、驗證和落地。
範例 4：修復人們在 Slack 上回報的問題
如果你曾經在 Slack 的某個問題或回饋頻道中見過我，你可能看過這些經典用法：
# 討論串已有足夠上下文
/poteto-mode 去做吧
/poteto-mode 用 /control-app 重現這個問題。如果它在 main 分支上能重現，就修復它，並錄製影片作為證明
我在這裡談到的許多技能已經被 /poteto-mode 自動使用，所以絕大多數時候你只需要使用 /poteto-mode，然後繼續你的生活！
規劃的藝術
規劃模式通常被用作說服自己 Agent 將會做正確事情的一種方式。但現實是，抽象的計劃只給你進步的錯覺。一個冗長而詳盡的計劃讓你看起來你和你的 Agent 非常有效率，但它可能缺乏實質內容。
pstack 為你提供了結合徹底調查、經驗證據和嚴格驗證的工具。當你以這種方式規劃時，使用 Agent 進行工程就不再感覺像一場賭博。它變得可預測且可重複。
https://x.ai/bot/plugin/9717366
感謝閱讀，敬請期待第 3 部分！
