pua-loop

pua-loop skill 概覽

pua-loop 是用來做什麼的

pua-loop 是一個適合長流程、多步驟實作工作的循環執行 skill；當你希望 agent 持續迭代、不用每隔幾分鐘就停下來問你問題時，它特別有用。它把自動重試循環與 repo 中 pua:pua 的行為規則結合在一起，讓 agent 能持續檢查工作結果、驗證、修正並重新執行，直到可以宣告完成。

pua-loop 最適合的使用情境

pua-loop skill 最適合用在可於本機驗證的程式開發或工作流程任務，例如修 bug、重構、補完功能、修測試，以及重複性的清理工作。對於 pua-loop for Workflow Automation 來說，當中斷成本高於少數不完美假設時，它尤其值得考慮。

使用者真正想解決的工作

多數使用者真正需要的通常不是「一個更聰明的 prompt」，而是能把一個邊界明確的任務交出去，避免每幾分鐘就得盯著 agent。pua-loop 就是為了這種交辦場景而設計。它的核心承諾是自主迭代：先檢查目前狀態、做出修改、執行驗證、診斷失敗原因，然後繼續往下跑。

pua-loop 與其他做法有什麼不同

pua-loop 最主要的差異，在於它對「持續跑下去」這件事有很明確的設計立場。這個 skill 明文禁止 agent 在 loop 模式中向使用者提問，並要求它在放棄之前先把可行替代方案盡量試完。此外，它會透過本機檔案保存 loop 狀態，因此相較於一般一次性 prompt，更能在 context 被壓縮後維持原本的行為。

導入前的重要提醒

這不是一個泛用型的「讓寫程式變更強」skill。pua-loop 最擅長的是成功條件明確、而且有可執行檢查的任務。如果你的工作本身很模糊、需要頻繁做產品決策，或依賴外部核准，那麼一般互動式 prompting 通常會更安全。

如何使用 pua-loop skill

在真正依賴 pua-loop 前，先確認安裝脈絡

目前提供的 repo 片段只看到 SKILL.md，而這個 skill 本身預期會依賴更完整的 tanweai/pua repo 支援，包括某個 setup script 路徑，以及 pua:pua 核心 skill 的行為。若要正式使用，請先查看 repo root，確認文件中提到的 loop script 與 core skill，確實存在於你已安裝的環境中。

pua-loop 是怎麼觸發的

文件中記載的觸發方式是 /pua:pua-loop "task description"。說明裡也列出自然語言觸發詞，例如 loop mode、自动循环、一直跑，但若你想更穩定、低歧義地啟用 pua-loop usage，slash command 仍是最可靠的方式。

啟動後會發生什麼事

啟動後，這個 skill 會先執行一個 setup command，建立 .claude/pua-loop.local.md。這個檔案會保存任務內容與 loop protocol。之後 stop hook 會使用該檔案，在每次迭代時把指令重新餵回 agent。實際上，這表示你不用每次重跑都重新解釋一次流程，agent 也能沿用同一套任務模式持續執行。

什麼樣的輸入能讓 pua-loop 發揮得更好

一開始就給 pua-loop 這四項資訊：

1. 任務目標結果
2. repo 或資料夾範圍
3. 驗證指令
4. 任何硬性限制

不夠好的輸入：

• 「Fix the app.」

較好的輸入：

• “Use pua-loop to fix the failing login flow in apps/web. Success means pnpm test --filter web passes and the OAuth callback no longer throws a 500. Do not change the database schema. Prefer the smallest safe fix.”

這種較完整的描述能減少無效迭代，因為 agent 會知道該在哪裡動手、怎麼驗證，以及哪些地方不能碰。

如何把模糊目標整理成完整的 pua-loop prompt

一個實用的 pua-loop guide 模板如下：

• Task：要建什麼或修什麼
• Scope：檔案、package 或 service 的邊界
• Verification：tests、lint、build、smoke check
• Constraints：不能改 schema、不能加新 deps、要維持 API 穩定
• Priority：優先最快的安全修復，還是較深度的重構

範例：

• /pua:pua-loop "Resolve TypeScript errors in packages/api only. Run pnpm --filter api build after each meaningful fix. Do not modify public endpoint contracts. Stop only when build passes and no new lint errors are introduced."

先讀哪些 repository 檔案

先從這個檔案開始：

• skills/pua-loop/SKILL.md

接著到上層 repo 檢查：

• pua:pua 的核心 skill 定義
• 是否有 scripts/setup-pua-loop.sh
• hook 文件或 Claude plugin 的 setup 檔案

這個閱讀順序很重要，因為 pua-loop install 是否可行，往往不取決於文案寫得多完整，而在於你的本機環境是否真的支援 setup script 與 stop-hook loop。

pua-loop 每一輪迭代實際上在做什麼

這個 skill 的核心規則很直接：

• 載入 pua:pua 行為
• 不要向使用者提問
• 不要太早以「cannot solve」結束
• 每次修改後都要驗證、找問題、修正，再重新驗證

因此，pua-loop 與其說像一般助理互動，不如說更接近一個自動化的修復循環。

什麼時候該用 pua-loop，而不是一般 prompt

以下情況適合用 pua-loop：

• 成功與否可以自動檢查
• 預期會有好幾輪修正與驗證
• 你想減少被中途打斷
• repo 內有可執行的命令

以下情況則建議略過：

• 任務每一步都需要產品判斷
• agent 拿不到 tests 或 runtime checks
• 一旦假設錯誤，代價會很高

第一次使用 pua-loop 的實務流程

一個合理的首次嘗試方式：

1. 先從單一、範圍明確的問題開始，不要一上來就做大型改寫。
2. 明確附上驗證指令。
3. 把範圍限縮在單一 package 或單一功能。
4. 讓 loop 自行跑完。
5. 先審查最後的修改內容，再決定是否擴大使用範圍。

這樣做能降低導入時最常見的風險：在需求描述不足的情況下，agent 過度自信地做出自主修改。

取消方式與安全邊界

這個 skill 文件列出兩種停止方式：/cancel-pua-loop，或直接刪除 .claude/pua-loop.local.md。在啟用自主迭代前，請把這兩件事視為必要的操作知識。如果你的環境裡不容易檢查或移除這個檔案，那 pua-loop skill 可能就不太適合你的 setup。

pua-loop skill 常見問題

pua-loop 適合新手嗎？

適合，但前提是任務範圍要明確。新手通常能從自動化中受益，但也更容易給出模糊指令。如果你剛開始用，請從失敗的測試或 build error 著手，而不是開放式的架構需求。

pua-loop 會取代一般 prompting 嗎？

不會。pua-loop 比較適合執行型的循環，不適合拿來做協作式探索。如果你還在選方案、比較做法，或釐清需求，請先用一般 prompt；等計畫定下來後，再切換到 pua-loop。

成功完成 pua-loop install 最大的阻礙是什麼？

通常是環境不匹配。這個 skill 會引用 setup script，以及由 stop hook 驅動的 loop。如果你的本機 Claude/plugin 設定沒有提供這些組件，單靠 markdown 本身無法產生預期中的自主循環行為。

pua-loop 沒有 tests 也能用嗎？

可以，但品質通常會下降。沒有 tests、build commands 或 smoke checks 時，agent 能用來判斷每輪迭代是否真的有改善的訊號就會變少。這種情況下，pua-loop usage 會更偏向猜測，可靠度也會降低。

pua-loop 和直接說「keep trying」有什麼差別？

一般 prompt 也能要求持續嘗試，但 pua-loop 加上了更具體的操作模式：透過本機檔案保存狀態、反覆驗證、明確的不提問模式，以及完成時的訊號。這個結構，才是值得安裝它的真正原因。

什麼情況下不該把 pua-loop 用在 Workflow Automation？

當 pua-loop for Workflow Automation 面對的是需要人工核准關卡、外部憑證、模糊商業規則，或「完成與否」本身帶有主觀判斷的任務時，就不適合使用。自主循環只有在完成條件可被檢查時才真正有幫助。

如何改進 pua-loop skill 的使用效果

替 pua-loop 設定可衡量的完成線

想提升 pua-loop 成效，最快的方法就是把完成條件定義成機器可檢查的形式。「Make it work」太弱；「所有 auth tests 通過、build 成功，而且 /login/callback 回傳 200」就很強。這個 skill 是圍繞迭代運作的，因此一定要有它能自行驗證的目標。

縮小範圍，降低 pua-loop 做出錯誤自主決策的機率

因為 pua-loop 會避免追問後續問題，所以任務越大，風險通常越高。與其說「refactor payments」，不如明確指定「fix duplicate retry handling in services/payments/retry.ts without changing webhook payloads`」。範圍越窄，通常速度與安全性都會更好。

提供限制條件，避免出現破壞性修法

好的限制不是多餘資訊，而是避免 loop 解錯題的關鍵。實用例子包括：

• 不要新增 dependencies
• 不要修改 schema
• API responses 要維持 backward compatible
• 優先做最小修補，不要直接重寫

這些限制會直接提升 pua-loop 產出的品質。

使用你手上最有力的驗證指令

如果有多種檢查方式，請選最相關的，不是選最吵、最廣的。像是 UI bug，比起整個 monorepo 全跑，對應的 targeted test suite 通常更好；若是型別問題，針對受影響 package 跑 tsc，可能就比大範圍 lint 更有效。驗證越準，loop 的決策品質通常越高。

預期 pua-loop 會因為缺少脈絡而失敗

常見的 pua-loop 失敗模式其實很可預測：

• 任務描述太模糊
• 缺少 repo 路徑或 module 範圍
• 沒有驗證指令
• 存在未明說的非技術需求
• 自主修改發生在錯誤的 package

這些問題大多不是靠原樣重跑就能解決，而是要把第一次的 prompt 補完整。

第一次跑完後，要用更精準的指令再迭代

如果第一次 pua-loop 已經接近目標，但還沒完全做到，不要只說一句「再試一次」。請補上缺失的訊號：

• 哪些地方還是失敗
• 哪些檔案被錯誤修改
• 應該偏好哪種取捨
• 哪一個驗證結果最重要

這樣第二輪才會是有方向的修正，而不是再次盲目循環。

透過閱讀核心依賴，提升對 pua-loop 的信任判斷

由於 pua-loop 的行為是繼承自 pua:pua，進階使用者在導入前應先檢查這個 core skill。如果你不喜歡它的施壓風格或決策規則，那你可能從一開始就不會想用這個 loop wrapper。這也是做出有依據的 install decision 時，最值得優先閱讀的 repo 細節之一。

先從有邊界的自動化開始，再逐步擴大

對多數團隊來說，最實用的 pua-loop guide 是循序導入：先拿來處理有明確檢查條件的修復任務，再用於小型功能補完，最後才考慮更大的自動化流程。這樣的順序能讓你逐步驗證這套 loop 行為，是否真的符合你的 repo 特性與風險承受度。