loop-engineering：把 AI 編碼代理從「提示詞」變成「可設計的循環」
Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
秒懂
- 它是什麼？
- 這是一個 TypeScript 寫成的模式庫與 CLI 工具集，目標是讓開發者設計一套系統來發現工作、交給代理、驗證結果並保存狀態，而不是每次手打提示詞。文章拆解其機制、上手方式、成本模型與適用邊界。
- 適合誰用？
- 這個專案適合已經在用 AI 編碼代理、但發現「單次提示」無法維持倉庫健康的人。它提供具體的模式、CLI 與評分機制，讓你把日常維護變成可重複的循環。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決的不是「寫提示詞」的問題
多數 AI 編碼工具的使用方式是一次性對話：你丟一個任務，代理回傳程式碼，你審查，結束。loop-engineering 想改變這個模型。它的核心命題是「Stop prompting. Design the loop.」也就是說，與其每次想下一個提示詞，不如設計一套系統，讓系統自己去發現工作、分配給代理、驗證結果、保存狀態。這套系統的目標讀者是已經在用 Claude Code、Codex、Grok 或類似代理的工程師，尤其是那些維護多個倉庫、每天要處理 issue、CI 失敗、依賴更新的人。它不是給你一個「重構這個模組」的按鈕，而是一組模式與工具，讓你把這些例行工作變成可排程、可審計的循環。
核心機制：STATE.md 與 Loop Ready 評分
整個設計圍繞一個狀態檔案 STATE.md。循環的運作方式是：代理讀取 STATE.md 了解目前倉庫狀況，執行任務，然後把結果寫回 STATE.md。這樣一來，每次循環不是從零開始，而是接續上一次的狀態。README 特別強調，Loop Ready 評分現在「weights recent runs harder than files on disk」，意思是如果 STATE.md 已經三十天沒更新，即使檔案還在，系統也不會認為它處於 L3 等級。這是對「僵屍狀態」的防禦。評分機制分為 L1、L2、L3：L1 是 report-only，代理只產生報告，不主動改程式；L2 是 assisted，代理可以建議修改但需要人確認；L3 是 unattended，代理自動執行。文件建議只有在 verifier（驗證器）連續一週正確之後，才從 L1 升級到 L2，再升級到 L3。這個漸進式設計是整個專案最重要的安全機制。
上手：兩條指令與五分鐘承諾
README 宣稱可以在五分鐘內開始。實際指令是：npx @cobusgreyling/loop init . --pattern daily-triage --tool claude，接著執行 npx @cobusgreyling/loop doctor . 來檢查環境。--tool 參數預設是 claude，但可以換成 grok、codex 或 opencode。init 指令會根據你選擇的 pattern 產生必要的檔案，doctor 則驗證設定是否正確。另外有 cost 指令可以估算成本：npx @cobusgreyling/loop cost --pattern daily-triage --level L1。這對預算敏感的使用者很實用，因為文件明確警告 token 成本可能暴漲。第一週是 report-only，意思是系統只會產生報告，不會自動改任何程式碼。這個設計讓使用者在投入自動化之前，先觀察循環的輸出品質。
模式庫：不是一個工具，是一組工作流程
專案的核心是 patterns 目錄下的模式檔，每個模式定義了節奏、第一週行為與成本等級。例如 Daily Triage 的節奏是 1 天到 2 小時，第一週是 L1 report，成本低；PR Babysitter 的節奏是 5 到 15 分鐘，成本高；CI Sweeper 的節奏也是 5 到 15 分鐘，但第一週是 L2 cautious，成本非常高。Dependency Sweeper 每 6 小時到 1 天跑一次，第一週是 L2 patch-only。這些模式不是抽象建議，而是有具體文件說明如何設定。模式清單集中在 patterns/registry.yaml，方便程式讀取。此外還有 starters/thin-loop，這是一個「thin」的 GitHub Action 循環，不需要 STATE.md，適合事件驅動的情境。這種多樣性表示專案理解不同任務有不同風險與頻率。
真正的限制：成本、無人看守的錯誤與過度設計
文件自己承認兩個主要失敗模式：token 成本可以暴漲，無人看守的循環會產生無人看守的錯誤。這不是空話，而是操作層面的現實。如果你把一個循環設成 L3 unattended，而驗證器（可能是測試或建置）不夠嚴格，代理可能會提交壞程式碼。另一個限制是 STATE.md 的維護成本。如果循環沒有持續更新 STATE.md，Loop Ready 評分會下降，但這也代表你需要一個穩定的排程環境（例如 GitHub Actions 或 cron）來確保循環真的在跑。還有一個潛在問題是過度設計：README 列出了一堆 companion repos，像是 memory-engineering、harness-foundry、outerloop，但它們明確標註「Do not add them until a loop has actually run」。換句話說，這個生態系很容易讓人一開始就導入過多元件，反而忽略了最基本的循環。
替代方案與差異：自己寫腳本或使用其他代理框架
最直接的替代方案是不要用任何框架，自己寫 cron job 或 GitHub Action 來呼叫 Claude Code 或 Codex，並手動管理狀態。這種做法的差異在於：你沒有模式庫可參考，也沒有 Loop Ready 評分來告訴你循環是否健康。另一個替代方案是使用其他代理編排框架，例如微軟的 AutoGen 或 LangChain 的 agent 工具，但它們通常專注於多代理對話與複雜任務分解，而不是「每日倉庫維護」這種例行公事。loop-engineering 的差異在於它把焦點放在操作層面：不是讓代理寫更多程式，而是讓代理維持倉庫的日常健康。如果你只需要跑一次性的重構，任何代理工具都能做到，但如果你需要一個可以持續運作、有安全等級、可以估算成本的系統，loop-engineering 提供了現成的模式。
維護與升級成本：活躍開發但需自行驗證
專案最後一次 push 是 2026 年 9 月，最近釋出 v1.6.0（2026 年 7 月）與 v1.5.0（2026 年 6 月），顯示開發節奏大約一個月一個 minor 版本。License 是 MIT，商用沒有障礙。CLI 的統一入口是 @cobusgreyling/loop，但舊的獨立套件如 loop-init、loop-audit 仍然支援，這表示升級路徑是向後相容的。文件提到「Help wanted」且保證 48 小時內回應第一個 PR，但這不保證所有 issue 都會被處理。採用前你應該自己檢查 docs/failure-modes.md 和 docs/safety.md，因為 README 只提供了連結，沒有摘要內容。另外，由於這是一個以文件為主的專案，實際的循環行為取決於你選擇的代理工具（Claude Code、Codex 等），CLI 只是產生設定與檢查環境，真正的執行是在代理那邊。因此升級 CLI 版本時，要確認模式檔與代理工具的相容性。
編輯結論
這個專案適合已經在用 AI 編碼代理、但發現「單次提示」無法維持倉庫健康的人。它提供具體的模式、CLI 與評分機制，讓你把日常維護變成可重複的循環。不適合只想按一個按鈕就重構整個模組的人，README 明說這不是「rewrite the module」按鈕。也不適合對代理輸出完全沒有審查能力的新手，因為文件警告「unattended loops make unattended mistakes」。採用前應先確認三件事：你願意承擔 token 成本（文件明說成本可能暴漲）、你能接受第一週只跑 L1 report-only 的節奏、以及你的 CI 或排程環境能支援 STATE.md 的持續更新。若你的工作流程是事件驅動且不想維護狀態檔，可考慮 starters/thin-loop 的輕量方案。最後，這是一個以文件與模式為主體的專案，版本 1.6.0 仍活躍，但採用前應自行檢查 docs/failure-modes.md 與 docs/safety.md，確認你理解循環失敗時的後果。
社群筆記