Harness、Loop、Graph Engineering 差在哪？

我實際用 Coding Agent 修改 Level UP 官網時，遇過幾種看起來很像，實際原因卻不一樣的問題。

有時候它為了修正一個手機版問題，順手修改了其他元件。 有時候它一直重試同一個方向，執行了好幾輪，結果沒有真的改善。 還有時候它回報「已經完成」，但沒有跑測試，也沒有實際打開網頁確認。

以前遇到這些情況，我最直接的反應通常是重新下指令，或換一個模型再試一次。

後來我開始把問題拆開看，模型能力只是其中一部分。

有些問題是 Agent 的工作環境沒有設計好，有些是缺少檢查與停止條件，也有些是整個任務路徑沒有被整理清楚。

這正好可以用三個近期常被放在一起討論的概念理解：

1. Harness Engineering
2. Loop Engineering
3. Graph Engineering

這三個名稱來自不同脈絡，並沒有共同的官方規格。本文把它們整理成一套實務上的理解框架：

Harness 是工作環境，Loop 是回饋循環，Graph 是工作路徑。

當 Coding Agent 出問題時，這個框架可以幫助我們先判斷問題在哪一層，再決定該改權限、驗證方式，還是任務流程。

先用一句話分清楚三層

這三層通常會一起運作。Graph 在 Harness 提供的環境裡執行，Graph 裡的部分步驟再透過 Loop 檢查與修正。

Harness Engineering：先讓 Agent 有正確的工作環境

Harness 可以理解成模型周圍的整套工作系統。

模型本身負責理解、推理與產生下一步行動，但它能讀哪些檔案、使用哪些工具、保留什麼狀態、執行哪些指令，以及哪些動作需要先問人，都是 Harness 的一部分。

以 Coding Agent 修改網站來說，Harness 可能包含：

• 專案檔案與網站文件
• CLAUDE.md、AGENTS.md 或其他工作規則
• Git、終端機、瀏覽器與測試工具
• 沙盒或獨立 worktree
• 檔案讀寫與網路存取權限
• 任務進度與修改紀錄
• 指令執行結果、日誌與變更差異
• 提交、推送與部署前的人工確認

OpenAI 在 Harness Engineering 的實作分享中，也把程式碼庫結構、文件、CI、測試、工具與可觀測性納入 Agent 的工作環境。當 Agent 表現不好時，團隊會先找出缺少的工具、規則、文件或保護措施。

Anthropic 在長時間 Coding Agent 的研究中則發現，只依靠對話內容壓縮仍然不夠。Agent 需要進度檔、Git 紀錄，以及能交接給下一個工作階段的明確產物，否則新的工作階段很容易不知道前面做了什麼。

權限太大，是 Harness 問題

例如我只想修正 Level UP 官網文章卡片在手機上的寬度，但 Agent 擁有整個專案的寫入權限，也沒有被限制只能修改特定元件。

它可能順手調整：

• 全站共用的容器寬度
• 首頁的卡片樣式
• 共用字體大小
• 其他頁面的 RWD 規則
• 原本沒有問題的 CSS 類別

這時候，就算 Prompt 寫得更客氣或更詳細，也無法真正限制它的行動。

比較有效的做法是調整 Harness：

1. 先讓 Agent 唯讀檢查相關檔案。
2. 要求它列出預計修改的檔案。
3. 只開放必要範圍的寫入權限。
4. 安裝套件、修改全域設定或刪除檔案前必須詢問。
5. 使用 Git 或獨立工作區，確保修改可以復原。
6. 保留完整 diff，讓人可以檢查它實際動了什麼。

Harness 解決的是：

Agent 有沒有在一個範圍清楚、狀態可追蹤，而且出錯後能恢復的環境裡工作？

Loop Engineering：不要只讓 Agent 重試，要讓它根據證據修正

Loop Engineering 處理每一輪工作完成後的檢查、回饋與下一步。

一個最基本的 Agent Loop 可能是：

讀取任務
→ 採取行動
→ 觀察結果
→ 決定下一步

但這還不代表它是一個設計良好的 Loop。

如果 Agent 每次失敗都只是重新執行相同修改，它雖然一直在循環，卻沒有真的學到任何東西。

一直重試但沒有改善，是 Loop 問題

假設文章卡片在 390px 畫面上仍然超出螢幕。

Agent 第一次修改卡片寬度，問題沒有解決。 第二次又調整同一個寬度數值，問題還是存在。 第三次繼續改相同位置，只是把數字再縮小一點。

這樣只是把相同行為重複三次，沒有根據新的證據改變方法。

好的 Loop 每一輪都應該包含：

1. 明確目標 例如 390px、768px 與 1440px 都不能出現水平捲動。
2. 完成證據 例如建置成功、瀏覽器截圖、畫面寬度檢查與 Git diff。
3. 失敗回饋 例如檢查後發現，真正把畫面撐出去的，是外層容器左右預留的空間。
4. 下一輪調整 根據新的錯誤原因改變方法，而不是再次執行相同操作。
5. 停止條件 同一方向最多嘗試兩次，仍無法解決就停止並交給人判斷。

Anthropic 在建立有效 Agent 的實務整理中指出，Coding Agent 適合透過自動化測試取得客觀回饋，再依測試輸出繼續調整。不過，測試涵蓋不到的系統需求仍需要人工審查。

說完成卻沒有測試，也是 Loop 問題

Agent 回報「修改完成」，只能證明它停止輸出了，不能證明任務真的完成。

以 Level UP 官網修改為例，我認為至少要取得這些證據：

• npm run build 成功
• 沒有新增不必要的依賴
• Git diff 只包含任務相關修改
• 390px、768px 與 1440px 畫面正常
• 圖片沒有被壓縮變形
• 原本正常的桌機版沒有受到影響
• Agent 清楚列出沒有驗證的部分

Loop 的停止條件要綁定外部證據，不能只看 Agent 是否回報完成。

這也是為什麼驗證、回饋與停止條件必須一起設計。只加入「請自行檢查」仍然太模糊，必須寫清楚要檢查什麼，以及什麼結果才算通過。

Graph Engineering：把複雜任務的工作路徑整理清楚

Graph Engineering 處理任務的執行路徑：

現在完成這一步後，接下來應該執行哪一步？

在 Graph 裡，可以先用三個簡單概念理解：

• State：目前任務的狀態與資料
• Node：實際執行工作的節點
• Edge：決定下一個節點的路徑

LangGraph 官方文件使用 State、Nodes 與 Edges 建立 Agent Workflow。Node 負責執行工作，Edge 根據目前狀態決定接下來執行哪個 Node，也可以建立固定順序、條件分支與平行處理。

以修改 Level UP 官網為例，簡單的 Graph 可能長這樣：

確認需求
↓
檢查相關檔案
↓
提出修改計畫
↓
執行修改
↓
自動化檢查
├─ 未通過 → 回到執行修改
└─ 已通過 → 視覺檢查
                 ├─ 畫面異常 → 回到修改
                 └─ 畫面正常 → 人工確認
                                      ↓
                                   合併變更

Graph 的價值，是把原本藏在 Agent 推理裡的工作順序變得明確。

你可以清楚知道：

• 哪些步驟一定要先完成
• 哪些工作可以同時進行
• 測試失敗後要退回哪裡
• 哪些結果需要交給另一個 Agent 檢查
• 哪些高風險動作必須等待人工同意
• 中斷後應該從哪個狀態恢復

什麼情況才需要 Graph？

如果任務只是修改一個按鈕顏色，通常不需要建立 Graph。

直接讓一個 Agent：

1. 讀檔
2. 修改
3. 執行檢查
4. 回報結果

就已經足夠。

Graph 比較適合以下情境：

• 多個 Agent 分別負責研究、實作、測試與審查
• 任務會依檢查結果走不同分支
• 部分工作可以平行執行
• 過程中有多個人工確認點
• 失敗後需要回到指定步驟
• 任務可能中斷，之後需要恢復

Anthropic 也建議從最簡單的解法開始，只有在單次模型呼叫或簡單 Workflow 無法滿足需求時，才逐步增加 Agent 系統的複雜度。預先定義的 Workflow 適合路徑清楚的工作，需要動態決策時才值得讓 Agent 擁有更多自主性。

三層怎麼一起工作？

Harness、Loop 與 Graph 比較接近巢狀關係。

Harness：提供整體工作環境
│
└─ Graph：定義任務的工作路徑
   │
   ├─ 需求確認
   ├─ 檔案分析
   ├─ 程式修改
   ├─ 測試 Loop
   │  ├─ 執行測試
   │  ├─ 取得錯誤證據
   │  ├─ 修正
   │  └─ 達標或停止
   │
   └─ 人工確認

以 Level UP 官網為例：

Harness 提供專案檔案、Git、瀏覽器、測試工具、修改權限與任務紀錄。

Graph 定義先檢查需求、再分析檔案、接著修改、測試、檢查畫面，最後交給人確認的工作順序。

Loop 則存在於測試與修正階段，讓 Agent 根據實際錯誤調整，直到通過驗收標準或達到停止條件。

三層一起運作後，Agent 會在範圍清楚的環境與路徑中，依照證據完成工作。

Coding Agent 出問題，要先檢查哪一層？

實際使用時，可以從症狀回推問題，先調整最接近原因的那一層。

我會怎麼設計 Level UP 官網修改任務？

假設任務是：

修正文章卡片在 390px 手機畫面下超出螢幕的問題。

我會從三層分別設定。

Harness：限制工作環境

• 先讀取文章卡片元件與文章列表頁 CSS
• 未經同意不要修改全站 Layout
• 不要安裝新套件
• 不要修改正式環境
• 提交與推送前必須詢問
• 保留完整 Git diff
• 提供瀏覽器或截圖工具

Loop：定義驗證與停止

每次修改後執行：

1. 執行建置
2. 檢查 390px、768px 與 1440px
3. 確認沒有水平捲動
4. 確認圖片比例正常
5. 確認桌機版沒有退化
6. 未通過時，先說明錯誤原因再修改
7. 同一方向最多嘗試兩次

通過所有條件後停止。

兩次仍未解決時，也要停止，整理目前證據與需要人工決定的地方。

Graph：定義執行路徑

理解需求
→ 唯讀檢查
→ 列出修改計畫
→ 人工確認範圍
→ 執行修改
→ 自動化檢查
→ 視覺檢查
→ 人工確認
→ 提交

如果建置失敗，回到程式修改。 如果建置成功但手機畫面異常，回到 CSS 或元件檢查。 如果所有條件通過，再交給人決定是否合併。

這樣 Agent 可以依照既定路徑往下執行，高風險動作仍會停下來等我確認。

不要一開始就把所有任務做成 Graph

看到 Harness、Loop 與 Graph 之後，很容易覺得三層全部建好才算完整。

實際上，複雜度也會帶來成本。

工具越多，Agent 越可能選錯。 Loop 越長，Token 與時間成本越高。 Graph 節點越多，流程越難維護。 規則越滿，真正重要的限制反而越不明顯。

如果只是一次性的簡單任務，可以直接使用 Prompt。

如果任務會重複，可以整理成 Workflow。

如果結果需要檢查與修正，再加入 Loop。

只有當流程出現明確分支、分工、平行處理或人工關卡時，才需要把 Graph 做得更清楚。

總結

如果只記得一件事：

Harness 決定 Agent 在哪裡、用什麼方式工作；Loop 決定它怎麼根據證據修正與停止；Graph 決定整個任務接下來走哪一條路。

當 Coding Agent 修改了不該改的檔案，先檢查 Harness。

當它一直重試、沒有進展，或沒測試就宣布完成，先檢查 Loop。

當任務分工混亂、步驟互相等待，或失敗後不知道該回到哪裡，才需要檢查 Graph。

下一次 Agent 出問題時，可以先問自己：

壞掉的是工作環境、回饋循環，還是工作路徑？

這個問題能幫我們縮小檢查範圍，再決定要調整權限、驗證方式或工作路徑。

參考資料與查核範圍

本文查核日期為 2026 年 7 月 28 日。

主要參考資料：

• OpenAI，Harness engineering: leveraging Codex in an agent-first world
• Anthropic，Effective harnesses for long-running agents
• Anthropic，Building effective agents
• LangChain，LangGraph Graph API overview
• Level UP 既有 Harness、Loop、Graph Engineering 學習筆記