你有沒有遇過這種情境：跑測試，紅了三個，修好一個又冒出兩個，來回切 terminal 切到懷疑人生？

Ralph Loop 解決的就是這件事。它是 Claude Code 的自動迭代套件，概念很直接——讓 Claude 在同一個 session 裡反覆執行同一個 prompt，每一輪看到前一輪改過的檔案繼續修，直到條件滿足或者跑到你設定的上限為止。

Stop Hook 攔截機制

背後的原理不複雜。Ralph Loop 用的是 Claude Code 的 Stop Hook——Claude 每次想結束的時候，Hook 會攔截這個動作，檢查輸出裡有沒有出現你預設的完成標記 <promise>TAG</promise>。沒看到？同一個 prompt 再餵一次。看到了或者跑到最大次數？放行，結束。

等效的概念大概是這樣：

1
2
3
while :; do
  cat PROMPT.md | claude-code --continue
done

但它不是真的 bash 迴圈。狀態會寫在 .claude/ralph-loop.local.md 裡面，用 YAML frontmatter 記錄目前跑到第幾輪、session ID、完成條件。

指令一覽

啟動迴圈：

1
/ralph-loop "<你的 prompt>" --max-iterations 20 --completion-promise "DONE"

取消：

1
/cancel-ralph

查看進度：

1
head -10 .claude/ralph-loop.local.md

兩個參數值得記住。--max-iterations 設定跑幾輪就強制停，建議永遠加上去——不然就是無限迴圈，API 額度燒到乾也不會停。--completion-promise 設定 Claude 輸出什麼文字代表「做完了」。

六種實戰場景

TDD 迴圈

跑測試 → 修 code → 再跑，直到全綠。這是 Ralph Loop 最對味的場景，因為 pass/fail 是客觀的，Claude 沒辦法作弊。

1
2
3
/ralph-loop "執行 pnpm test，失敗就修實作，反覆到全部通過。\
完成後輸出 <promise>ALL TESTS PASS</promise>" \
--completion-promise "ALL TESTS PASS" --max-iterations 20

逐步消化 Task List

讀取 .spec/tasks.md，找到下一個未完成的項目實作，做完打勾，直到清單清空。

1
2
3
/ralph-loop "讀 .spec/tasks.md，實作下一個未完成任務，完成打勾。\
全部做完輸出 <promise>DONE</promise>" \
--completion-promise "DONE" --max-iterations 30

Lint 修到零錯誤

1
2
3
/ralph-loop "執行 pnpm lint，修復所有報錯，重複直到零錯誤。\
完成後輸出 <promise>CLEAN</promise>" \
--completion-promise "CLEAN" --max-iterations 10

Code Review 迭代

用 reviewer agent 掃一遍、修完再掃，直到沒有 CRITICAL 和 HIGH。

1
2
3
4
/ralph-loop "用 code-reviewer agent 審查 src/ 變更，\
修復所有 CRITICAL 和 HIGH 問題。\
全部修完輸出 <promise>REVIEWED</promise>" \
--completion-promise "REVIEWED" --max-iterations 15

自動修 CI

CI 紅了就分析 log、修 code、push，直到全綠。

1
2
3
4
/ralph-loop "檢查 gh run list 最新結果，\
失敗就分析日誌修復程式碼並推送。\
CI 全綠後輸出 <promise>CI GREEN</promise>" \
--completion-promise "CI GREEN" --max-iterations 10

漸進式重構

找到下一個用舊版 API 的檔案，改成新版，確認編譯，下一個。

1
2
3
/ralph-loop "找到下一個使用舊版 API 的檔案，重構為新版 API，\
確認編譯通過。全部遷移完成後輸出 <promise>MIGRATED</promise>" \
--completion-promise "MIGRATED" --max-iterations 50

什麼時候不該用

Ralph Loop 的核心限制在一個字：客觀性。

有自動驗證的任務（測試結果、lint 輸出、CI status）非常適合。但需要主觀判斷的事情——「UI 調到好看」「文案寫到滿意」——Claude 可能會提前輸出 <promise> 來脫離迴圈。它不是故意騙你，是它真的覺得「差不多了」，而你可能不同意。

場景 適合？ 原因
TDD / lint 零錯誤 非常適合 有明確的自動驗證
逐步實作 task list 適合 有 checkbox 當進度指標
自動修 CI 適合 CI status 可驗證
UI 調整到「好看」 不適合 主觀判斷，Claude 會提前逃跑
生產環境 debug 不適合 需要人類即時決策

Prompt 撰寫要點

三個原則。第一，完成條件要寫清楚——在 prompt 裡明確告訴 Claude 什麼時候該輸出 <promise>TAG</promise>。第二，安全出口要設好——--max-iterations 永遠加，然後在 prompt 裡寫「如果卡住就記錄 blocker」。第三，分階段拆解——複雜任務拆成 Phase 1/2/3，最後一個 phase 才輸出 promise。

另外一個值得注意的：Ralph Loop 只影響啟動它的 session。同專案開了其他 Claude Code 視窗不會被攔截，可以安心繼續做別的事。

Ralph Loop 把「人盯著 terminal 等結果再手動重跑」的迴圈自動化掉了。TDD、lint、CI 這些本來就是機械式重複的流程，交給 Hook 處理剛好。下次跑測試跑到天荒地老的時候，不妨試試看。

參考來源：Claude Code in Action - Anthropic Academy