Communitygithub.com

mytler/ultraloop

Agent 技能:任務唯有在驗證並實際運作時才算完成。能評估工作規模、探查你的儲存庫,並交付經過驗證的程式碼,或附上誠實的執行計畫。適用於 Claude Code、Codex、Cursor 及其他 Agent。

ultraloop 是什麼?

Ultraloop 是一個專為 AI Agent(如 Claude Code、Codex、Cursor)設計的技能,它顛覆了「程式碼寫完就算完成」的預設行為,強制要求任務必須在實際驗證成功後才能標記為完成。其核心機制是根據任務規模動態調整驗證流程:輕量任務(如單一函式或腳本)只需簡短檢查與假設說明;而大型任務(如專案功能、多階段流程)則需要完整的「完成定義 (Definition of Done)」,包括單元測試、建置、型別檢查、CI/CD 通過及實際運行驗證。技能運作分為三個階段:第零階段進行規模評估,區分輕量或大型任務;第一階段(僅大型任務)先探查儲存庫以解答自身疑問,再提出真正無法從程式碼中得知的問題;第二階段則自主執行,嚴格按照計畫迭代修改與驗證,不中斷詢問使用者。Ultraloop 也內建了防止偽造驗證結果的機制,要求所有驗證標準都必須有可觀察的證據(如指令輸出、測試結果),同時規範了輕量與大型任務的溝通與報告方式,確保使用者能「離開後回來直接看到結果」,而不會被無謂的問題或程序卡住。

相容平台✓Claude Code✓Codex CLI✓Cursor
npx skills add mytler/ultraloop

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

ultraloop 是做什麼的?

你的預設是把程式碼寫完就當作任務完成。**這是錯的,而且在此處已被停用。**在 ultraloop 模式下,任務唯有在結果經過實際驗證並運作時才算完成——「程式碼看起來正確」不是證據;證據是實際執行的觀察結果。所謂「驗證」的要求會隨著任務規模調整:對於一段程式碼片段,可能只需針對幾個案例執行;對於實際專案中的一個功能,則需要測試通過、建置乾淨、即時檢查,以及一個能通過 CI/CD 的 Pull Request。

**根據任務規模校驗流程。**流程強度與錯誤的成本及任務大小成正比。一個單檔函式和一個 50 個 Agent 的工作流程絕對不該有相同的繁文縟節——對小任務套用繁重儀式是此技能最常見的失敗,而且這是真正的失敗:它同時也打破了 ultraloop 的整體承諾(「離開後回來看結果」),因為在你回來回答 20 個問題之前,什麼都無法開始。因此,在開始任何事之前,請先評估任務(第零階段)並選擇適當的流程強度。只問足夠避免走向明顯錯誤路徑的問題,不要多問。


第零階段——規模評估(務必優先執行,在任何提問之前)

在問任何問題之前,先分類任務並選擇一個模式。

輕量任務——信號(符合任一):

  • 一個自包含的程式碼片段 / 單一函式 / 小型模組;
  • 與現有儲存庫、測試或 CI 無關(或這些都不存在);
  • 沒有需要即時驗證的 UI,錯誤成本低,且可輕易復原。

大型任務——信號(符合任一):

  • 在一個包含儲存庫、測試、CI/CD 的實際專案中新增功能/進行異動;
  • 一個工作流程、多個階段、許多 Agent、長時間執行的作業;
  • 需要透過 Playwright / Computer Use 進行即時檢查;
  • 錯誤成本高、有外部相依性、牽涉 PR 流程。

如果確實不明確,則問一個簡短的問題來確定規模——不要在你進行分類之前就展開完整訪談。然後選擇對應路徑:輕量模式(見下方),或完整的兩階段 大型模式(第一階段 → 第二階段)。


輕量模式(快速路徑)

基礎模型在處理小型、自包含的任務時表現已經很好——讓它自己處理時,它會寫出一個正確的 RFC-4180 CSV 狀態機,而不是一個天真的 split(',')。你的工作在於不要礙事:快速交付那個好的結果,並陳述假設,而不是用儀式來阻擋它。

  • 不要執行大型的釐清階段,也不要要求最大輪數。
  • 最多問 1–3 個問題,而且只問那些真正昂貴的分岔點——也就是預設值錯誤會導致需要整個重做的情況(對於 CSV:要嚴格的 RFC 4180 還是簡單 split?允許外部函式庫嗎?程式碼應該放在哪裡?)。其他所有情況:採取合理的預設值,不要問。
  • 立即根據這些預設值撰寫解決方案,然後簡短列出你所做的假設,並邀請修正。將分岔點表述為「除非你另有說明,否則我將採用 X」,而不是使用者必須回來回答的阻塞性問題。
  • 不要引入重型機制——正式的 DoD 合約、最大輪數、PR + CI/CD、ScheduleWakeup——當沒有儲存庫/測試/CI,且任務也不需要這些時。足夠的狀態是:可運作的程式碼 + 幾個基本檢查/測試 + 簡短的注意事項。
  • 從完整模式中仍然保留的一件事:**實際驗證你能驗證的部分,且絕不偽造。**在宣告完成之前,至少在幾個案例上執行函式(或快速測試);如果某些東西無法驗證,請明確說出來。輕量流程不代表未經驗證。

**範例(正確執行的輕量任務)。**提示:"Напиши на TypeScript функцію, яка приймає рядок CSV і повертає масив об'єктів, де ключі беруться з першого рядка-заголовка." → 分類為 LIGHT → 立即寫出正確的解析器(RFC-4180 狀態機:引號、""、引號內的逗號和換行、\n/\r\n),預設值為字串 → 然後簡短列出假設(RFC 4180、分隔符 ,、無外部函式庫、無型別轉換)並邀請修正。不要傾倒 20 個問題,也不要要求最大輪數。


大型模式 · 第一階段——探查,然後釐清(互動)

從這裡開始的所有內容(第一至二階段、完整 DoD、執行迴圈、ScheduleWakeup、Workflow、PR 完成)都是大型路徑——當第零階段將任務分類為大型時使用。對於輕量任務,請改用上方的輕量模式。

要避免的失敗:在一行程式碼都還沒寫之前就傾倒約 20 個問題,而其中一半已經可以從儲存庫本身找到答案。這會要求使用者提供已經在 package.json 中的資訊,並將 100% 的工作阻塞在等待他們回覆上——這就打破了「離開後回來看結果」的承諾。因此,先探查程式碼,然後只問程式碼無法告訴你的問題。

1. 完整重讀原始提示——問了什麼、為什麼問、以及從使用者角度來看「完成」的樣子。

**2. 在問任何事之前,先靜默探查儲存庫。**如果任務觸及一個現有專案,請閱讀程式碼,並盡可能回答你自己的問題:

  • 框架 / 語言 / 執行環境 / 版本——package.json、lock 檔、tsconfig、設定檔;
  • 套件管理器——從 lock 檔判斷(pnpm-lock.yaml / package-lock.json / yarn.lock);
  • 資料庫與資料存取層——相依性、設定、遷移、現有模型/綱要;
  • 測試執行器以及測試的執行方式——scripts、測試設定;
  • CI/CD——.github/workflows/、.gitlab-ci.yml 等;
  • 現有模式——類似的路由/處理器/驗證是如何撰寫的;遵循該風格,而不是自創一套。
  • 建置一致性(一個便宜的檢查——在寫任何執行計畫前先做): package.json 是否與 lock 檔(pnpm-lock.yaml / package-lock.json / yarn.lock)一致?每個相依性都存在於 lock 中;沒有在 package.json 中新增但 lock 中缺少的——僅僅這個不一致就會導致 pnpm install --frozen-lockfile(以及 CI 工作)失敗,無論你的變更是什麼。另外,你在執行計畫中會引用的腳本(lint / typecheck / test / build / db:*)是否真的存在於 package.json 中?

任何你從程式碼中學到的東西,都不要問。探查是預設行為;只有在確實沒有專案可讀時才跳過(那麼這些項目才會變成真正的問題)。

如果探查發現一個預先存在的問題——lock 與 package.json 不一致,或執行計畫中的腳本不存在——請將其作為單獨的旗標提出,標示為「預先存在的儲存庫問題,會導致 CI 失敗」,並附上修正指令(例如 pnpm install + 提交更新的 lock)。這不會阻礙你交付程式碼——只是在執行計畫旁放一個誠實的備註,這樣使用者就不會把一個原本就存在的問題歸咎於你的變更。

3. 只問那些真正無法解決的問題——不在程式碼中且無法安全地給出預設值的產品/政策決策。(例如「建立使用者」:是公開註冊還是僅管理員?是否有密碼,我們用什麼來 hash?確切的回應合約和狀態碼?重複的 email 會發生什麼事?)所有你從儲存庫推斷出來或可以合理預設的東西都不是問題——將它們記錄為陳述的假設。只有在您即將在此環境中進入自主驗證迴圈時,才在同一簡短區塊中詢問最大輪數預算;如果環境無法執行該迴圈(無安裝 / 無資料庫 / 無網路——請參閱步驟 5 和「當驗證迴圈無法在此執行時」),則跳過最大輪數的詢問,因為還沒有迴圈需要限制。

4. 在探查後才形成完成定義(見下方),使其立基於你找到的實際技術棧,而不是猜測。展示它,並取得關於那些是真正決策的部分的「ok」。

**5. 進度規則——建置-驗證-標記,不要硬性阻塞。**大型模式的預設是:採取合理的假設(來自儲存庫 + 常識)→ 建置 → 在環境允許的範圍內驗證 → 然後在你的報告中明確列出你所做的假設以及仍需要確認的內容。不要為了等待答案而凍結所有工作,也不要保留成果不交付。

**考量環境限制的預設值。**一個有合理零成本因應對策的阻塞點不是問題——將該因應對策作為已標記的預設值,然後繼續進行。例如:你需要密碼 hash 但 bcrypt/argon2 不在相依性中,且沒有網路可以安裝它們 → 使用 node:crypto 的 scrypt,標記為「bcrypt/argon2 只需一行函式即可切換」。環境限制會影響預設值;它們不會停止工作。

只有在確實是沒有安全預設值且錯誤成本很高的產品/政策分岔點時,才硬性阻塞(在開始之前停止並詢問)——例如,當程式碼沒有說明時,詢問「這個端點是公開註冊還是僅管理員?」。此外,在會造成破壞或不可逆的操作之前也要停止:生產環境 / 共享資料庫、不可逆的遷移、刪除資料、對外發布。

在其他所有情況下,根據假設繼續前進並交付。目標是最多只有一個真正的阻塞性問題;其他所有問題都變成已標記的假設。如果使用者在那裡,問一個政策問題是可以的——但同時繼續產出不受阻塞的程式碼,而不是閒置。


大型模式 · 第二階段——執行(自主)

一旦所有事項都達成一致,就完全獨立運作,嚴格按照計畫,不再向使用者提問。他們應該能夠離開並回來看到一個完成的結果。

只有在真正的阻塞點時才允許提問——也就是在沒有答案的情況下,物理上不可能繼續進行(無法存取機密、任務自相矛盾、外部服務掛掉)。在這種情況下:陳述阻塞點並使用 ScheduleWakeup(見下方),這樣你就不會在等待中閒置,也不會在空檢查上消耗上下文。

所有其他決定都由你自己根據已同意的 DoD 和常識來做出。當一個次要的分岔點出現,且有一個明顯的預設值時,就採用該預設值並在疊代日誌中註記,而不是停下來詢問。


報告(大型模式):信號,而非方法論

簡潔報告,絕不再解釋 ultraloop 的運作方式。每個更新只攜帶新的、實質的資訊——什麼已驗證、什麼失敗了、還剩下什麼。

  • 不要逐輪敘述方法:沒有「收集了資料」、「驗證 Agent 失敗了,所以我正在自己檢查」、「沒有證據就不算通過」等等。如果你必須自己驗證某件事,而不是透過預期的工具,請僅註記一次,簡短說明——然後停止重複。
  • 陳述結果,而非過程:「測試通過(42 項通過)」、「typecheck 在 foo.ts:10 失敗,正在修復」、「POST 回傳 201,重複 → 409 已確認」。跳過逐回合的細節。
  • 如果一個輪次沒有新內容可說,就什麼都不用說。沉默勝過一段重新陳述計畫的文字。

完成定義(大型模式)

這個完整的 DoD 合約是為大型任務設計的。輕量任務不會獲得這個——它只會得到可運作的程式碼 + 幾個基本檢查 + 陳述的假設(請參閱輕量模式)。

在開始之前,列出一個具體的、可驗證的完成標準清單。從兩個來源提取:提示中的明確要求,以及對於此類任務明顯隱含的要求。使用者經常留下那些「不言而喻」的部分不說——你的工作是將它們重建出來。

預設情況下,即使未明確說明,DoD 也包含以下事項:

  • 為新邏輯撰寫單元/整合測試並通過;
  • 在需要時為外部相依性(網路、資料庫、付款、時間)建立模擬;
  • 專案建置無錯誤(build 通過);
  • linter 和型別檢查通過;
  • 功能已即時驗證——Playwright(網頁)或 Computer Use / 呼叫 API/CLI,而不是「透過查看程式碼」;
  • 無回歸:現有測試持續通過;
  • 程式碼/日誌/前端中無機密;伺服器端驗證無法繞過(請參閱使用者的全域安全規則);
  • 只有在所有建置和測試都通過,且保證能通過 CI/CD 時,才開啟一個乾淨的 PR。

根據任務調整清單:刪除不適用的項目(無 UI → 無 Playwright),新增特定的項目(資料庫遷移 → 測試復原機制;一個函式庫 → 測試發布的 API 表面)。每個技術棧和每個 CI 的如何驗證的食譜存在 references/verification-recipes.md 中。

在將任何標準標記為「已滿足」之前,你必須擁有可觀察的證據:指令輸出、一次綠色執行、一個頁面截圖/快照。相信「我寫對了」不是證據。


執行迴圈

以短疊代的方式工作,而不是用一個大的「全部寫完 → 最後檢查」的作法。越早發現失敗,修復成本就越低。

一個疊代:

  1. 變更——向著下一個 DoD 專案的最小可行步驟。
  2. 檢查——執行相關的檢查:測試 → 建置 → lint/型別 → 即時檢查。實際執行它們,讀取輸出,不要依賴「應該可以」。
  3. 診斷——如果有東西是紅色的,找出根本原因,不要修補症狀。對於非平凡的錯誤,引入 debugger 子 Agent;新邏輯的測試可以交給 test-engineer。
  4. **修復 → 重複。**在 ALL DoD 項目都變綠之前,不要離開迴圈。

保持簡短的疊代日誌——這樣你就不會繞圈子或修復同一個問題兩次。每個疊代一行或兩行:

#N | 檢查:<你執行的項目> | 失敗:<什麼和為什麼> | 修復:<你做了什麼> | DoD 狀態:X/Y

**最大輪數限制。**將每一個驗證→修復週期計入已同意的限制。當你快接近時——停下來,不要默默地超過它。顯示:哪些是綠色的,哪些仍然是紅色的以及為什麼,你嘗試了什麼。然後排程一個 ScheduleWakeup(如果正在等待長時間執行)或等待使用者。此限制關乎修復週期的數量,而非總工作量;在限制範圍內的生產性工作不受其限制。


絕不偽造綠色狀態(兩種模式皆適用)

這是此技能的核心,且在輕量模式中也適用。ultraloop 的全部重點在於達到一個真正能運作的結果;偽造的綠色破壞了這個重點,且比誠實的「未完成」更糟。

區分「已驗證」與「已產出」——這是最常被誤讀的部分。「不要偽造綠色」的意思是:永遠不要聲稱某件事是經過驗證的,除非你確實親眼看到了它運作的結果。信任「我寫了測試所以它必須通過」不算——你必須實際執行測試並看到輸出。如果你無法驗證一個標準(無法執行測試、無法建置專案、無法執行應用程式),請明確說出哪個標準未經驗證,以及為什麼。不要把它標記為透過。信任轉移不是驗證。

相關技能