Harness Engineering：如何打造真正可用的 AI Agents

1使用者請求
2      |
3      v
4+-----------------------------+
5|           HARNESS           |
6|                             |
7| 合約          上下文         |
8| 工具          狀態           |
9| 策略          驗證           |
10| 追蹤紀錄       恢復機制        |
11+-----------------------------+
12      |
13      v
14     模型
15      |
16      v
17  真實環境

1objective: 降低新手引導流失率
2
3inputs:
4  - 產品簡介
5  - 分析數據
6  - 程式碼儲存庫
7
8constraints:
9  - 保留身份驗證機制
10  - 不要更改資料庫結構描述
11  - 維持目前的行動裝置行為
12
13deliverable:
14  - 可審查的 pull request
15
16done_when:
17  - 測試通過
18  - 分析事件正確觸發
19  - 桌面版流程通過審查
20  - 行動版流程通過審查
21
22approval_required:
23  - 正式環境部署

1專案地圖
2
3產品規則     -> docs/product/
4架構設計     -> docs/architecture.md
5前端        -> apps/web/
6後端        -> services/api/
7測試        -> tests/
8指令        -> docs/commands.md
9安全性       -> docs/security.md

1任務
2  |
3  v
4專案地圖
5  |
6  v
7相關系統
8  |
9  v
10確切檔案
11  |
12  v
13本地指令

1工具：edit_file
2
3輸入
4path
5patch
6
7前置條件
8path 存在
9path 位於工作區內
10
11成功
12patch 已套用
13回傳 diff
14
15失敗
16結構化錯誤
17不允許部分覆寫
18
19風險
20可逆

1模型提出方案
2      |
3      v
4閘門進行驗證
5      |
6      v
7策略授權許可
8      |
9      v
10工具執行操作
11      |
12      v
13HARNESS 記錄結果

1{
2  "task_id": "feature_042",
3  "status": "verifying",
4  "current_step": "mobile_check",
5
6  "completed": [
7    "implementation",
8    "unit_tests",
9    "desktop_check"
10  ],
11
12  "decisions": [
13    "reuse existing export endpoint",
14    "preserve current date format"
15  ],
16
17  "artifacts": [
18    "export.csv",
19    "desktop-after.png"
20  ],
21
22  "open_risks": [
23    "mobile toolbar may overflow"
24  ],
25
26  "next_action": "render mobile viewport"
27}

1事實
2穩定的知識
3
4決策
5選了什麼、為什麼這樣選
6
7狀態
8目前這次執行走到哪了
9
10教訓
11哪些失敗應該影響未來的執行

1主張                     證據
2
3「bug 已修復」            原本失敗的測試現在通過了
4
5「頁面正常運作」           瀏覽器流程跑完了
6
7「資料正確」              數值與來源相符
8
9「遷移是安全的」           模擬執行 + 回滾測試通過
10
11「任務完成」              所有驗收檢查都通過

1語法
2  |
3  v
4型別
5  |
6  v
7針對性測試
8  |
9  v
10整合測試
11  |
12  v
13視覺 / 語意審查
14  |
15  v
16人工核准

1建造者
2   |
3   v
4建立候選方案
5   |
6   v
7驗證者
8   |
9   +-- 檢查合約
10   +-- 搜尋遺漏的案例
11   +-- 測試未經支持的主張
12   +-- 嘗試破壞結果
13   |
14   +------ 通過 ------> 接受
15   |
16   +------ 失敗 ------> 回傳證據

1未經核准絕不發布
2絕不洩露機密
3絕不超出支出上限
4絕不在工作區外寫入
5除非真的跑過測試，否則絕不聲稱測試通過

1低風險
2
3讀取
4搜尋
5檢查
6
7-> 自動放行
8
9可逆操作
10
11編輯工作區
12執行測試
13建立草稿
14
15-> 自動放行 + 記錄追蹤
16
17外部影響
18
19發送
20部署
21購買
22
23-> 需要核准
24
25不可逆 / 敏感操作
26
27刪除資料
28輪替憑證
29全域發布
30
31-> 硬性阻擋或禁止

1工具逾時
2-> 採用退避機制重試
3
4參數無效
5-> 修復工具呼叫
6
7缺少上下文
8-> 取得缺失的來源
9
10測試失敗
11-> 檢查失敗的行為
12
13權限遭拒
14-> 請求核准
15
16需求互相衝突
17-> 向上回報
18
19重複失敗且狀況未變
20-> 停止

1觀察
2   |
3   v
4決策
5   |
6   v
7行動
8   |
9   v
10衡量
11   |
12   +---- 接受
13   |
14   +---- 修復
15   |
16   +---- 上報
17   |
18   +---- 停止

1說明
2      |
3      v
4檢查清單
5      |
6      v
7模板
8      |
9      v
10自動化檢查
11      |
12      v
13強制執行的政策

109:14  建立任務合約
209:15  載入 architecture.md
309:17  編輯 checkout.ts
409:18  針對性測試失敗
509:21  修復實作
609:22  針對性測試通過
709:24  整合測試通過
809:25  部署受阻：需要核准

1目標
2
3修復優惠券重複套用的問題。
4
5已變更
6
7結帳驗證
8迴歸測試
9
10已驗證
11
12lint 通過
13單元測試通過
14整合測試通過
15
16未驗證
17
18正式環境付款服務商
19
20風險
21
22舊版行動用戶端無法使用
23
24需要核准
25
26部署到 staging

1缺少上下文
2-> 改善專案地圖
3
4用錯工具
5-> 改善路由或工具合約
6
7輸出品質差
8-> 加入驗證器
9
10無限循環
11-> 加入重試上限
12
13不安全的動作
14-> 加入權限閘門
15
16決策遺失
17-> 持久化狀態
18
19未知錯誤
20-> 改善追蹤紀錄

1第 0 層
2
3提示詞
4模型
5
6第 1 層
7
8任務合約
9專案地圖
10工具
11
12第 2 層
13
14結構化狀態
15驗證
16有邊界的循環
17
18第 3 層
19
20權限
21追蹤紀錄
22恢復機制
23人工閘門

1[ ] 成功的定義是否在執行前就已確立？
2
3[ ] Agent 能否在不載入所有內容的情況下
4    找到正確的上下文？
5
6[ ] 每個工具是否都有明確的目的、
7    結構描述與失敗狀態？
8
9[ ] 重要決策是否儲存在
10    對話之外？
11
12[ ] 完成任務是否需要證據？
13
14[ ] 高風險動作是否受到政策保護？
15
16[ ] 每個循環是否有重試上限？
17
18[ ] 執行中斷後能否恢復？
19
20[ ] 你能否重建每個重要動作？
21
22[ ] 失敗是否能改進某項規則、工具、
23    測試、地圖或權限？
24
25[ ] 最終的變更能否回滾？

1提示詞
2-> 指令
3
4上下文
5-> 工作視圖
6
7HARNESS
8-> 運行環境
9
10循環
11-> 局部修正
12
13圖譜
14-> 協調合作