English Version →

Project 08. 把你的工作流畫成一張圖

相關講義：L14. 從單循環到圖工程

你要做什麼

這是從 "Loop" 到 "Graph" 的躍遷專案。上一講你搭了一個 maker-checker loop——實作、驗證、回饋、再實作，所有決策都發生在同一個 agent 的上下文視窗裡。這一講你要做的，是把藏在循環裡的結構顯式地畫出來：節點、邊、共享狀態、路由規則，一個字一個字地寫清楚。

你會做三個遞進的實驗：先把 P07 的 maker-checker loop 畫成一張顯式圖，再給圖加一個平行 fan-out/fan-in 節點，最後加一條條件回退邊和一個人工審批節點。做完你會親身感受到一件事：圖不是新發明，是當你的 loop 複雜到一定程度後，它自己變成的樣子。

用什麼工具

• Claude Code 或 Codex
• Git
• 你在 P07 搭好的 maker-checker loop（或任何一個你能反覆跑的 agent 工作流）
• 一個文字編輯器或繪圖工具（畫圖不是為了好看，是為了把結構寫清楚；mermaid 或手寫 graph.md 都行）

具體步驟

準備工作

1. 從 P07 完成後的儲存庫出發，或者直接用你正在跑的任何 agent 工作流。
2. 建立三個分支：p08-explicit-graph、p08-parallel、p08-human-in-the-loop。
3. 準備一個 state.md 作為共享狀態檔案：需求、進度、驗證結果都寫在這裡。這是圖的「公共工作台」。

實驗一：把 Loop 畫成顯式圖

切到 p08-explicit-graph 分支。

1. 列出所有節點：把 P07 maker-checker loop 裡的每一步寫成一個節點。每個節點寫清楚：它的職責、它的輸入、它的輸出、它是 agent 還是確定性程式碼。
2. 畫出所有邊：列出節點之間的每一條邊。重點標註兩條特殊邊：
   • 條件邊：驗證通過/失敗，走哪條
   • 回退邊：失敗回到哪個節點
3. 寫共享狀態：明確列出狀態裡有哪些欄位（需求、程式碼、測試結果、審查結論），誰讀誰寫。
4. 寫路由規則：用最簡單的 if-then 語言寫下「下一步去哪」的規則，比如：

   if 驗證通過 → 合併節點
   if 驗證失敗 → 實作節點
   if 實作節點資訊不足 → 研究節點

5. 寫成 graph.md：把以上內容整理成一份文件。用 mermaid 畫一張圖，附上節點表和路由規則。
6. 回答這個問題：畫完之後，找出至少一條原來是隱式的邊——以前藏在 agent 上下文裡、你自己都不知道它存在的決策路徑。

實驗二：加一個平行 Fan-out / Fan-in 節點

切到 p08-parallel 分支。

1. 選一個可以並行的點：找任務裡一個可以拆成兩個獨立部分的地方。比如：
   • 實作拆成兩個獨立模組，兩個 agent 平行寫
   • 驗證拆成兩個獨立審查：一個跑測試和 lint，一個做程式碼審查（不同的指令、不同的關注點）
   • 研究拆成兩個方向，兩個 agent 各查一路
2. 寫 fan-out 規則：共享狀態裡記錄「這個任務被拆成 N 個平行子任務」，每個子任務一個獨立的 context、一個獨立的節點。
3. 寫 fan-in 規則：所有子任務完成後，誰來合併結果？合併的標準是什麼（比如：兩個審查都通過才合併，還是有一個通過就行）？
4. 用 worktree 隔離：每個平行子任務在獨立的 git worktree 裡跑，物理上避免檔案碰撞（回顧第十三講的 Worktree 原語）。
5. 跑一次並記錄：記錄平行前後 wall-clock 時間、token 消耗、結果品質。平行真的更快嗎？還是協調開銷吃掉了省下的時間？

實驗三：加一條回退邊和一個人工審批節點

切到 p08-human-in-the-loop 分支。

這是三個實驗裡最重要的一個。你要在圖上加兩種節點：

1. 條件回退邊：給驗證節點加一條「部分通過」的路徑——不是全盤打回實作節點，而是帶著具體回饋回到產生問題的那個節點。比如：測試全過但程式碼審查發現需求理解有誤，回退到研究節點而不是實作節點。這要求你的共享狀態裡記錄「問題出在哪一層」。
2. 人工審批節點（Human-in-the-loop）：在合併節點之前加一個人工節點。走到這裡，圖停下來，等你在 state.md 裡寫「批准」或「打回」。審批節點可以有一個超時規則：N 小時後沒回應，自動打回或自動升級。
3. 寫 interrupt 的格式：審批請求怎麼寫清楚——發生了什麼、改了什麼、為什麼需要人、批准/打回的後果各是什麼。
4. 跑至少 2 輪完整流程：每一輪都走到人工審批節點，你自己批准或打回一次。記錄：你的審批決策和驗證節點的判斷一致嗎？審批節點攔住過什麼驗證節點沒攔住的嗎？

怎麼衡量結果

指標	實驗一（顯式圖）	實驗二（平行）	實驗三（人機協同）
結構可見性	找出了幾條隱式邊？	共享狀態能否支撐平行子任務？	回退邊能否精確定位問題層？
失敗定位	失敗時能否直接指出是哪條邊錯了？	平行子任務失敗時，能定位到哪一個？	審批打回時，能指出是哪一層的問題嗎？
協作開銷	寫圖花了多久？	平行省下的時間 vs 協調開銷	審批等待時間 vs 攔住的問題價值
可觀測性	每一步發生了什麼，現在看得見了嗎？	每個平行子任務的狀態可見嗎？	審批請求寫得夠清楚嗎？
可靠性	圖描述和實際運行一致嗎？	fan-in 合併標準靠譜嗎？	超時/升級規則真的會觸發嗎？

要交什麼

• graph.md（實驗一的完整圖描述：mermaid 圖 + 節點表 + 邊表 + 共享狀態欄位 + 路由規則）
• 實驗一發現的隱式邊清單（至少一條）
• 實驗二的 fan-out/fan-in 規則和一次平行運行記錄（時間/成本/品質對比）
• 實驗三的回退邊規則、審批節點格式和 2 輪人機協同記錄
• 最終複盤：從 loop 到 graph，你的工作方式發生了什麼變化？哪些任務值得畫圖，哪些不值得？

對應講義

• Lecture 14 — 從單循環到圖工程
• Lecture 13 — 從手動驅動到自動循環（你的 loop 就是圖裡的一個節點；這個專案是把節點的內部結構攤開）
• Lecture 09 — 為什麼 agent 會提前宣告完成（驗證節點為什麼必須獨立於實作節點，在圖中是結構問題）
• Lecture 11 — 為什麼可觀測性屬於 harness 的一部分（圖越複雜，越需要看到每個節點在做什麼）