這一課會完成什麼
- 把業務需求拆成輸入、狀態、執行者、允許與禁止效果，以及可觀察驗收
- 用固定測試資料將成功、拒絕、重試、未知結果與超出範圍寫成測試案例
- 讓控制器分清完成、受阻、預算用盡與待審查，並決定允許的下一步
- 建立變更流程，避免看到候選結果後才放寬驗收答案
開始前先準備
- • 模組 00 的原始任務文字、基準驗收憑證與主要 harness 缺口
- • 可修改課程程式庫的 `.harness` 資料夾，並能執行測試資料執行器
先把定義說清楚
可驗收的任務契約
可執行的任務契約，把程式與審查者共同使用的工作邊界寫清楚：執行者、起始狀態、輸入、允許路徑、受保護資源、必要效果、禁止效果、驗收案例、預算、證據、停止原因與版本。重點是讓完成與拒絕都有可觀察的判準。篇幅再長的需求，若沒有驗收方式，仍無法約束工作。Agent 應依固定契約交付，遇到缺資料或無權執行時回報相應結果，不能自行改寫成功定義。
模糊任務常把重要決策藏在一句『把功能做好』裡。程式撰寫 agent 可能自行挑選狀態轉換、略過未授權角色、修改相鄰 schema，或把逾時後的未知效果當成安全重試。審查者到最後才補規則，便無法知道候選到底通過原需求，還是通過事後修改的答案。
合約把意圖接到後續 harness：程式庫地圖告訴 agent 去哪裡找，初始化程序建立固定起點，功能台帳保存狀態，工具回傳合約需要的證據，由程式強制執行的規則擋禁止範圍，評測則建立 verified。每個下游產物都引用同一個契約版本，避免各自理解不同版本的完成。
現場情境
一句請求變更的九種解讀
角色、請求、狀態、原因、逾時、效果與預期輸出都是Release Desk 合成測試資料。
- 負責人
- 你是負責把產品摘要轉成程式撰寫 agent 任務的負責人工程師。
- 要做的決策
- 哪些條件屬於任務本身，哪些屬於實作選擇，哪一筆證據足以建立 verified？
- 目前狀態
- 產品摘要只有『reviewer 可以要求修改並留下原因』。程式庫有 open、resolved、changes_requested 三種狀態與稽核表，但沒有說誰能操作、哪些轉換合法、逾時後是否重試。
- 預期成果
- 一份版本 1.0.0 合約與固定案例表，能在寫程式前判斷成功、拒絕、unknown 與超出範圍。
限制條件
- • 合約要能由無舊聊天紀錄的審查者執行
- • 所有寫入操作必須綁執行者、請求版本與冪等鍵
- • 關鍵權限與重複效果失敗不能被平均分數蓋掉
實作範例
逾時案例揭露隱藏的效果合約
證據類型: 具名模擬情境初稿只檢查回應為 200、頁面顯示變更 requested。故障測試資料在稽核寫入後讓客戶端逾時；agent 看到錯誤便重送。最終畫面正確，稽核卻多出兩筆。原本的正常流程案例完全看不出問題。
合約新增邏輯操作效果識別碼、完成狀態未知狀態與結果核對要求。驗收判準指定同一執行者、請求版本與原因只能產生一個邏輯稽核效果；逾時後必須讀正式可信的台帳，確認結果再決定是否派送執行。
案例表分開記 API 傳輸方式、領域狀態轉移、瀏覽器持久保存與操作效果次數。候選版本即使畫面正確，只要重複操作效果就是關鍵 fail。這項要求後面會直接成為工具結果碼與評測門檻。
主張限制
課程契約只適用合成請求狀態轉移。實際產品仍要由領域負責人、安全與營運人員確認資料保留、通知、法規、稽核與復原責任。
做法
照著做，每一步都有檢查點
現場情境
哪些條件屬於任務本身，哪些屬於實作選擇，哪一筆證據足以建立 verified？
- 01寫清執行者、狀態與效果
- 02鎖定範圍與禁止事項
- 03建立案例與驗收判準
驗收條件
同一份合約可驅動 agent 計畫、工具輸出、驗收與審查者判斷，並且在證據不足或權限來源缺失時誠實停下。
- 01
寫清執行者、狀態與效果
列出由可信系統確認的執行者、起始請求版本、合法轉換、原因格式、資料持久化與稽核寫入。把產品要求和暫定實作分欄，未確定事項交由負責人決定，不留給 Agent 自行填補。
檢查點 · 契約能拒絕角色不符、狀態不符、版本過期、原因格式錯誤和不存在的請求，每種拒絕都有穩定代號。
- 02
鎖定範圍與禁止事項
宣告可修改路徑、受保護路徑、允許工具、網路及資料邊界、檔案數上限，以及禁止的重構和破壞性操作。明列正式環境存取與其他本機專案都不在授權內。
檢查點 · 一個功能正確但修改未授權 schema 的樣本差異會被判 fail，理由能連回合約欄位。
- 03
建立案例與驗收判準
至少寫十個案例，涵蓋成功、拒絕、持久化、逾時、操作結果未知、略過必要檢查與超出修改範圍。先填預期終止狀態、邏輯效果次數、證據及嚴重程度，再交給執行器驗證 schema。
檢查點 · 答案在候選執行前鎖定；關鍵驗收不會被其他通過案例抵銷。
- 04
做未參與開發的審查與版本變更
讓另一位審查者用合約評三個差異與驗收憑證，記錄不一致。若問題是合約缺欄位，建立 1.0.1 並說明影響；若只是候選版本失敗，不修改驗收判準。
檢查點 · 審查者能獨立說明 pass、fail、blocked 與缺漏證據，版本差異有負責人與理由。
實務脈絡
展示版之後
從效果與權限反推
先寫執行者能做與不能做的事情，再寫 UI 或 API。Release Desk 的審查者可以對 open 請求提出變更，必須附 20 到 500 字元原因，狀態要持久化並寫一筆稽核。非審查者、非 open 狀態、過期版本與未知請求都要有各自終止碼。
模型提出的租戶、角色、請求負責人或環境 ID 不能當授權依據。這些欄位由登入工作階段與正式可信的儲存區取得。合約同時寫清禁止外部網路、正式環境資料、未列出的 schema 重構、廣泛刪除與停止其他專案程序。
先寫驗收判準再跑候選
每個案例列出測試資料、操作、預期狀態、邏輯效果次數、可修改路徑、必要證據與嚴重程度。正常流程以外，也測原因格式錯誤、角色不符、版本過期、派送前逾時、操作生效後逾時、瀏覽器檢查遭略過、重新整理後資料遺失，以及修改無關檔案。
合約變更要有負責人、理由、版本與受影響案例。若產品需求真的改變，建立新版本並重跑基準版本，不在候選失敗後直接把門檻刪掉。這是保護評測可信度，也讓未來工作階段知道哪個版本才是目前程式庫正式事實。
交付補強
交付契約時附欄位責任表。執行者、角色、請求版本、目前狀態與既有操作由可信儲存區提供，原因與操作意圖才來自使用者。Agent 可以提議方案，不能自行填權限。前端傳入角色、後端只驗格式便採信，是要測的漏洞；即使按鈕只對審查者顯示，也須直接呼叫執行器，證明它使用可信身分並拒絕模型自行提供的權限。
把停止原因當成合約輸出，不要只做 pass 和 fail。輸入格式錯誤是不合法；執行者無權限是 denied；需要產品負責人決定新轉換是 blocked；預算先用完是 budget_exhausted；寫入結果不明是 unknown_effect；證據完整才是 verified。每個狀態都要對應操作手冊與允許下一步，才能防止 agent 遇到任何非成功狀態就一律重試，或用自然語言把 denied 說成暫時性問題。
審查契約時，請一位沒參與需求討論的人只看測試資料與 schema，逐題回答：誰能做、起點是什麼、哪個效果算一次、哪些檔案可改、缺哪筆證據就不能完成。回答若需要回頭問口頭背景，表示那個決策尚未進正式紀錄。修正後保留審查者原本的誤解，因為它就是未來全新工作階段可能採用的錯誤路徑，也應成為回歸測試案例。
動手實作
把基準任務改寫成可執行合約
從原始摘要與基準版本失敗建立 JSON 任務契約、十個案例、禁止效果清單與驗收憑證 schema，再故意送入模糊與越權版本。
準備項目
- • 凍結原始任務文字與模組 00 驗收憑證，不直接覆寫證據
- • 邀請一位未參與基準的審查者只靠合約判斷三個樣本差異
本課產出
有版本的任務契約、十個測試案例、主張與檢查的對照表、禁止操作及修改範圍、驗收憑證 schema、變更紀錄，以及獨立審查者的判斷差異。
起始模板: Task contract
JSON# Task contract: request changes
## Goal
## Actor and object
## Starting state
## In scope
## Non-goals
## Permissions
## Acceptance cases
| id | starting fixture | action | expected outcome | prohibited effect | evidence |
|---|---|---|---|---|---|
## Stop and escalate
## Evidence receipt
## Owners and approval可下載的實作檔
Task contract
TASK_CONTRACT.md · Markdown
An editable course fixture for the main lab. Save it inside the Release Desk repository before running the acceptance command.
Run receipt template
he-01-receipt.json · JSON
A compact evidence record for the check, environment, result, and limits that another reviewer must be able to inspect.
驗收指令
npm run harness:contract -- --file TASK_CONTRACT.md預期 receipt
PASS he-01 executable-contract
cases>=6 softCriteria=0 evidenceCoverage=100%
reviewedBeforeExecution=true預期結果
同一份合約可驅動 agent 計畫、工具輸出、驗收與審查者判斷，並且在證據不足或權限來源缺失時誠實停下。
留給下一課
將 task-contract.json 與案例集合視為後續各模組的正式紀錄。程式庫地圖、初始化程序、台帳、工具、規則、評測與總整專案驗收憑證都要記錄契約版本。
驗收條件
- 01契約 schema 驗證執行者、狀態、輸入、效果、範圍、預算、證據與終止原因
- 02十個案例在執行前就有驗收判準與關鍵程度
- 03未知寫入完成只能走結果核對，不能直接重試
- 04未參與開發的審查者判斷能對到合約欄位；任何版本變更有理由與負責人
常見故障
故障診間
F1合約很長，卻仍無法判斷頁面是否真的完成。
- 先檢查
- 找每個需求對應的驗收判準、測試資料、使用者操作與證據。
- 可能原因
- 內容只描述目標與實作建議，沒有可觀察行為與權威判準。
- 修復方式
- 補主張與檢查的對應表，把畫面、持久化、權限與效果分開驗。
- 下次怎麼避免
- 沒有驗收判準與驗收憑證欄位的要求不得標為可驗收。
F2候選失敗後，團隊把案例答案改成目前實作。
- 先檢查
- 比對契約歷史紀錄、案例差異、執行時間與變更負責人。
- 可能原因
- 產品變更與降低評測門檻沒有分開。
- 修復方式
- 恢復固定集合；真的需求變更另開版本並重跑基準。
- 下次怎麼避免
- 所有驗收判準變更都要在候選之外審核，保留舊版本結果。
F3Agent 把自己產生的角色欄位當成授權。
- 先檢查
- 追查執行者、租戶範圍、登入工作階段、資料庫規則與工具執行器採用的身分來源。
- 可能原因
- 契約只規定欄位格式，沒有指定哪些系統能提供可信的值。
- 修復方式
- 由可信的執行環境派生身份，拒絕模型自行提供的權限來源。
- 下次怎麼避免
- 每個會影響授權的欄位都標明可信來源，並加入偽造欄位的測試案例。
展示版之後
正式上線前的邊界
- 01合約有版本、負責人、適用任務類型、起始提交版本與變更紀錄
- 02執行者、身份、狀態、版本與權限來源都標示可信來源
- 03成功、拒絕、blocked、unknown、預算已用盡與需求審查有不同終止碼
- 04允許路徑、保護資源、禁止效果、預算與破壞性邊界能被驗證器執行
- 05案例在候選前鎖定，關鍵權限、機密、操作效果與範圍驗收門檻不做平均
- 06驗收憑證綁契約、提交版本、環境、測試資料、檢查、操作效果與審查者決策
證據類型
資料來源與主張限制
資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。
- [1]長時間應用程式開發的 harness 設計planner、generator、evaluator · 可測合約 · 簡化 harness · 成本取捨
Anthropic · 已發表研究 · 2026-08-26
- [2]打造有效的 agent採用能通過需求的最簡架構 · workflow 模式 · 環境回饋 · 停止條件
Anthropic · 官方文件 · 2026-08-26
- [3]Harness engineering：在 agent-first 開發環境中運用 Codex知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
OpenAI · 公開案例 · 2026-08-26
- [4]Andrej Karpathy 的 AI Engineering PlaybookSoftware 3.0 觀點 · spec、diff、eval 實作 · 平行 session · repository 指令
AI Builder Club · 公開案例 · 2026-08-26
- [5]Learn Harness Engineering專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程
Walking Labs · 公開案例 · 2026-08-26
延伸的 Tenten 資源