English Version →

Project 07. 搭建你的第一個自動循環

相關講義：L13. 從手動驅動到自動循環

你要做什麼

這是從 "Harness" 到 "Loop" 的躍遷專案。你已經知道怎麼給 agent 配好一套環境、一套指令、一套回饋——現在你要把這套東西變成一個能自己跑的循環。

你會做三個遞進的實驗：先把一個任務從手動跑變成 /goal 自動跑，再把一個巡檢任務變成 /loop 定時跑，最後做一個帶 maker-checker 分離的完整循環，體驗「人退到循環外面」是什麼感覺。

使用倉庫裡的專案

倉庫路徑：projects/project-07/

目錄	裡面有什麼	做什麼
starter/	一個帶有完整 harness 的小型知識庫專案（P06 完成態），包含 AGENTS.md、feature_list.json、init.sh、session-handoff.md、clean-state-checklist.md。	把這套 harness 改造成能自動循環的版本。
solution/	三個循環的完整實作：goal loop、loop timer loop、maker-checker loop，加上 loop 狀態檔案和驗證腳本。	參考 loop 的設計方式和狀態管理模式。

用什麼工具

• Claude Code 或 Codex
• Git
• 你在 P06 搭建好的完整 harness
• 一個你常用的終端複用工具（tmux 或 screen，用於觀察長時間運行的 loop）
• 可選：GitHub Actions 或 cron（用於事件驅動/定時驅動的進階實驗）

具體步驟

準備工作

1. 基於 P06 完成後的程式碼，從同一個 commit 出發。
2. 建立三個分支：p07-goal-loop、p07-timer-loop、p07-maker-checker。
3. 確認你的 harness 是工作的：跑一次 init.sh，確認狀態檔案、feature list、交接文件都在。
4. 選一個你要讓 loop 反覆做的目標任務。建議選一個中等大小、有明確完成標準的任務，比如：「給所有模組補充單元測試，覆蓋率達到 80%」或「把所有 API 端點加上輸入驗證」。

實驗一：Goal Loop —— 從手動跑到自動跑

切到 p07-goal-loop 分支。

1. 寫目標描述：把你選的任務寫成一份 goal.md，包含：

   • 明確的目標（「完成什麼算做完」）
   • 驗證方式（「怎麼確認做完了」——跑測試？跑 lint？檢查覆蓋率？）
   • 停止條件（「什麼時候應該停下」——最大回合數？時間上限？預算上限？）
   • 約束（「不能碰什麼」——生產設定、資料庫 schema 等）

2. 第一次手動跑：你自己手動給 agent 發指令，完成一次這個任務。記錄用了多少回合、你介入了多少次、結果品質如何。這是你的基線。

3. 用 /goal 跑：用同一份 goal.md 作為輸入，用 /goal 模式跑一次。agent 自己循環直達成目標或觸發停止條件。

4. 對比結果：

   • 回合數差異
   • 你介入的次數差異
   • 結果品質差異（用同樣的驗證標準）
   • 你花的時間差異

5. 迭代 goal.md：如果結果不好，改 goal 描述，再跑一次。直到你對結果滿意，或者確認 goal loop 在這個任務上的極限在哪裡。

實驗二：Timer Loop —— 把巡檢變成心跳

切到 p07-timer-loop 分支。

1. 選一個巡檢任務：找一個你平時手動做的、重複性的檢查工作。比如：

   • 每小時跑一次測試，有失敗就修
   • 每天早上檢查依賴有沒有安全更新
   • 每次提交後檢查程式碼有沒有違反編碼規範
   • 定期掃描 TODO 註解，看哪些已經過期了

2. 寫巡檢腳本/prompt：把巡檢的步驟寫清楚——檢查什麼、發現問題了怎麼辦、什麼時候需要叫人。

3. 用 /loop（或 Codex 的對話執行緒自動化）跑：

   • 設定合理的間隔（建議 10-30 分鐘，太短你會被打擾，太長看不出效果）
   • 讓它跑至少 2 小時（或者你去幹別的事，過一會兒回來看）

4. 記錄結果：

   • 它發現了多少問題？
   • 它自己修了多少？
   • 有多少是誤報？
   • 有多少是它修壞了的？
   • 你花了多少時間跟進它的結果？

5. 思考：這個巡檢任務值得自動化嗎？節省的時間和你跟進它花的時間比，哪個多？如果不划算，是任務選錯了還是 loop 設計得不好？

實驗三：Maker-Checker Loop —— 把你從循環裡拿出來

切到 p07-maker-checker 分支。

這是三個實驗裡最重要的一個。你要做一個完整的、你不需要在場的循環：

1. 設計循環結構：

   • Maker agent：負責實作，寫程式碼，改檔案
   • Checker agent：負責驗證，跑測試，做程式碼審查，打通過/不通過
   • 狀態檔案（loop-state.md）：記錄當前輪次、做了什麼、驗證結果、下一輪要做什麼
   • 停止條件：連續 N 輪通過，或者達到最大輪次

2. 寫三份 prompt：

   • Maker 的指令（做什麼、怎麼做、什麼不能碰）
   • Checker 的指令（驗證什麼、怎麼驗證、什麼算通過、發現問題了怎麼回饋）
   • 循環控制邏輯（誰先跑、跑完了怎麼交接、下一輪怎麼啟動）

3. 跑至少 5 輪循環：

   • 第一輪：Maker 實作 → Checker 驗證 → 不通過 → 回饋給 Maker
   • 第二輪：Maker 根據回饋修改 → Checker 再驗證 → ...
   • ...
   • 直到連續通過，或者你叫停

4. 記錄每一輪的狀態：

   • 輪次
   • Maker 做了什麼
   • Checker 發現了什麼問題
   • 通過/不通過
   • 你有沒有介入（如果介入了，為什麼）

5. 最後覆盤：

   • 你一共介入了幾次？為什麼介入？
   • 如果沒有介入，結果會怎麼樣？
   • Checker 有没有漏過問題？
   • Maker 有没有在同一個問題上反覆犯錯？
   • 這個循環的品質天花板在哪裡？是 Maker 的能力還是 Checker 的能力？

怎麼衡量結果

指標	實驗一（Goal）	實驗二（Timer）	實驗三（Maker-Checker）
任務完成率	目標達成了嗎？	巡檢了多少次？	多少輪後通過？
人類介入次數	你插手了幾次？	你跟進花了多久？	你介入了幾次？
結果品質	和手動比怎麼樣？	誤報率多少？漏檢率多少？	Checker 發現了多少你沒發現的問題？
時間節省	你省了多少時間？	值得自動化嗎？	你花在設計循環上的時間 vs 你省下來的時間
可靠性	停止條件靠譜嗎？	有没有跑飛了？	循環會不會卡死在同一個地方？

要交什麼

• goal.md（實驗一的目標描述，至少迭代了兩個版本）
• 實驗一的對比記錄：手動 vs goal loop
• 實驗二的巡檢 prompt 和 2 小時運行日誌
• 實驗三的三份 prompt（Maker / Checker / 循環控制）
• 實驗三的 loop-state.md（至少 5 輪記錄）
• 最終覆盤：三個實驗的收穫、你對 loop engineering 的理解變化、哪些事情適合 loop 化、哪些不適合

對應講義

• Lecture 13 — 從手動驅動到自動循環
• Lecture 12 — 為什麼每次會話都必須留下乾淨狀態（loop 的每一輪都需要 clean state）
• Lecture 11 — 為什麼可觀測性屬於 harness 的一部分（你需要看到 loop 內部在發生什麼）
• Lecture 05 — 為什麼狀態檔案是跨會話連續性的核心（loop 狀態檔案是 state file 的延伸）