cobusgreyling/loop-engineering

Loop Engineering – 設計、執行與評分自主 AI 代理循環

是什麼 – 一個由 CLI 驅動的框架，協助您將手動提示轉換為可重複的「循環」，該循環能發現工作、交由基於 LLM 的代理（Claude、Grok、Codex、Opencode 等）處理、驗證輸出並記錄狀態。它內建一組預先準備好的 模式（每日診斷、PR 哺育者、CI 清掃者等），可輕鬆接入任何程式碼倉儲，並在本機或 GitHub Actions 中執行。

為何重要 – 建立可靠的 AI 代理流程很困難：您需要決定循環何時執行、如何評分自身工作，以及如何控制成本。Loop Engineering 提供結構化檢查清單、STATE.md 檔案以追蹤循環的知識狀態，以及 L1–L3 的評分系統，幫助您判斷何時可從「僅報告」過渡到完全無人監控的自動化。

---

核心概念

概念	說明
模式	預先定義的工作流程（例如 daily-triage），指定執行頻率、初始安全等級（L1–L3）與預期成本。
工具	代理所使用的基礎 LLM（預設為 claude，也支援 grok、codex、opencode）。
STATE.md	一個 Markdown 檔案，用於持久化循環的學習狀態；CLI 會在首次執行時引導您建立它。
循環就緒評分	一個數值評分，反映循環設計的完善程度（最近的執行權重較高）。
等級	L1 = 僅報告，L2 = 輔助，L3 = 無人監控。必須連續一周驗證正確後才能升級。

---

快速入門（5 分鐘）

# 在目前倉儲初始化一個循環
npx @cobusgreyling/loop init . --pattern daily-triage --tool claude

# 執行健康檢查
npx @cobusgreyling/loop doctor .

# 查看所選模式的成本估算
npx @cobusgreyling/loop cost --pattern daily-triage --level L1

若省略 --tool，CLI 預設使用 Claude。

此命令會建立一個 STATE.md 檔案與一組設定檔，描述循環將監控的內容（問題、CI、相依性等）。第一週結束後，您將獲得一個 L1 報告，顯示循環本應執行的操作。當驗證器持續正確時，您可以提升等級，讓循環自動執行。

---

主要模式（任選一個開始）

模式	執行頻率	第一周輸出	典型成本
每日診斷	1 天 – 2 小時	倉儲健康狀態的 L1 報告	低
PR 哺育者	5–15 分鐘	新 PR 的 L1 監控	高
CI 清掃者	5–15 分鐘	L2 謹慎修復不穩定的 CI	非常高
相依性清掃者	6 小時 – 1 天	L2 僅限補丁更新	中
變更日誌起草者	1 天 或 標籤建立時	L1 變更日誌草稿	低
合併後清理	1 天 – 6 小時	L1 非尖峰時段的維護	低
問題診斷	2 小時 – 1 天	L1 僅建議處理問題	低

每個模式位於 patterns/ 目錄中，包含 Markdown 說明與 patterns/registry.yaml 中的 YAML 條目。互動式選擇器可在展示網站上使用。

---

範例工作流程

• Claude Code – 使用 Claude 產生程式碼變更，並包含 VS Code 插件。
• Grok 每日診斷 – 在新倉儲上執行 Grok 驅動的診斷循環。
• GitHub Actions 輕量循環 – 僅需一個工作流程檔案即可加入倉儲，無需額外 STATE.md。

所有範例均在 examples/ 目錄中，可使用相同的 CLI 命令執行。

---

安全與操作指南

• 失敗模式 – 記錄於 docs/failure-modes.md（例如：令牌使用失控、幻覺修復）。
• 反模式 – 參見 docs/anti-patterns.md，了解過度自動化而無驗證等常見陷阱。
• 安全檢查清單 – docs/loop-design-checklist.md 引導您在升級到更高等級前驗證循環。
• 故事 – 真實世界中的成功與失敗案例收集於 stories/，幫助您從社群經驗中學習。

此專案強調，循環會放大人類判斷；無人監控的循環可能造成高成本錯誤，因此 L1→L2→L3 的逐步推進是強制性的。

---

社群與貢獻

• 採用者清單 – 透過「add-adopter」問題模板加入您的專案。
• 新手友善問題 – 標記為適合初學者；維護者承諾 48 小時內回應。
• 配套倉儲 – 可選擴充如 memory-engineering、outerloop 等，適用於循環證明可靠後的後續階段。

---

授權

MIT – 可自由使用、修改與分發。

---

核心要點 – Loop Engineering 是一個實用的、基於模式的工具包，可將 LLM 代理轉化為圍繞程式碼庫的可重複、可審計的自動化循環。它提供清晰的入門路徑、安全支援結構與評分系統，幫助您判斷何時可信任循環自主行動。