把需求鎖成 executable task contract：實作與驗收指南

本課內容

01先把定義說清楚
02現場情境
03實作範例
04照著做，每一步都有檢查點
05實務脈絡
06動手實作
07故障診間
08正式上線前的邊界
09資料來源與主張限制

這一課會完成什麼

把業務需求拆成輸入、狀態、actor、允許與禁止效果，以及可觀察驗收
用固定 fixture 將成功、拒絕、重試、未知結果與超出範圍寫成測試案例
把完成、blocked、budget exhausted 與 need review 等終止狀態交給 controller 判定
建立變更流程，避免看到候選結果後才放寬驗收答案

開始前先準備

• 模組 00 的原始任務文字、基準 receipt 與主要 harness 缺口
• 可修改課程 repository 的 `.harness` 資料夾，並能執行 fixture runner

先把定義說清楚

可執行任務合約

Executable task contract 是能由程式與 reviewer 共同執行的工作邊界。它明列 actor、起始狀態、輸入、允許路徑、保護資源、必要效果、禁止效果、驗收案例、預算、證據、終止原因與版本。合約不是把需求寫得很長，而是讓完成與拒絕都有可觀察的判準，讓 agent 無法靠漂亮摘要自行改寫成功定義。

模糊任務常把重要決策藏在一句『把功能做好』裡。Coding agent 可能自行挑選狀態轉換、略過未授權角色、修改相鄰 schema，或把逾時後的未知效果當成安全重試。Reviewer 到最後才補規則，便無法知道候選到底通過原需求，還是通過事後修改的答案。

合約把意圖接到後續 harness：repository map 告訴 agent 去哪裡找，initializer 建立固定起點，feature ledger 保存狀態，工具回傳合約需要的證據，mechanical rules 擋禁止範圍，eval 則建立 verified。每個下游產物都引用同一個 contract version，避免各自理解不同版本的完成。

現場情境

一句 request changes 的九種解讀

角色、request、狀態、reason、timeout、效果與預期輸出都是 Release Desk 合成 fixture。

負責人: 你是負責把產品 brief 轉成 coding agent 任務的 lead engineer。
要做的決策: 哪些條件屬於任務本身，哪些屬於實作選擇，哪一筆證據足以建立 verified？
目前狀態: 產品 brief 只有『reviewer 可以要求修改並留下原因』。Repository 有 open、resolved、changes_requested 三種狀態與 audit table，但沒有說誰能操作、哪些轉換合法、逾時後是否重試。
預期成果: 一份 version 1.0.0 合約與固定案例表，能在寫程式前判斷成功、拒絕、unknown 與超出範圍。

限制條件

• 合約要能由無舊聊天紀錄的 reviewer 執行
• 所有 writes 必須綁 actor、request version 與 idempotency key
• critical 權限與重複效果失敗不能被平均分數蓋掉

實作範例

逾時案例揭露隱藏的效果合約

證據類型: 具名模擬情境

初稿只檢查回應為 200、頁面顯示 changes requested。Fault fixture 在 audit insert 後讓 client timeout；agent 看到錯誤便重送。最終畫面正確，audit 卻多出兩筆。原本的 happy-path case 完全看不出問題。

合約新增 logical effect identifier、unknown completion 狀態與 reconciliation 要求。Oracle 指定同一 actor、request version 與 reason 只能產生一個邏輯 audit 效果；timeout 後必須讀 authoritative ledger，確認結果再決定是否 dispatch。

案例表分開記 API transport、domain transition、browser persistence 與 effect count。Candidate 即使畫面正確，只要 duplicated effect 就是 critical fail。這項要求後面會直接成為工具結果碼與 eval gate。

主張限制

課程 contract 只適用合成 request transition。實際產品仍要由 domain owner、security 與營運人員確認資料保留、通知、法規、稽核與復原責任。

做法

照著做，每一步都有檢查點

現場情境

哪些條件屬於任務本身，哪些屬於實作選擇，哪一筆證據足以建立 verified？

01寫清 actor、狀態與效果
02鎖定範圍與禁止事項
03建立案例與 oracle

驗收條件

同一份合約可驅動 agent 計畫、工具輸出、驗收與 reviewer 判斷，並且在證據不足或 authority 缺失時誠實停下。

這張圖要幫你看懂什麼Task contract 的欄位要一路連到 tool、rule、eval 與 receipt，圖比散落文字更容易檢查缺口。

01
寫清 actor、狀態與效果
列出 authoritative actor、起始 request version、合法轉換、reason 規格、持久化與 audit 效果。把 product requirement 和暫定實作分欄，讓未確定事項不會偷偷變成 agent 自由裁量。
檢查點 · 合約能拒 wrong role、wrong state、stale version、invalid reason 與 unknown request，且每種拒絕都有穩定代碼。
02
鎖定範圍與禁止事項
宣告可修改路徑、保護路徑、允許工具、網路與資料邊界、最大檔案數、禁止重構與 destructive action。明列 production access 和其他本機專案都不在授權內。
檢查點 · 一個功能正確但修改未授權 schema 的 sample diff 會被判 fail，理由能連回合約欄位。
03
建立案例與 oracle
至少寫十個成功、拒絕、持久化、逾時、unknown effect、skipped check 與 scope 案例。先填 expected terminal、logical effect、evidence、criticality，再交給 runner 驗 schema。
檢查點 · 答案在候選執行前鎖定；critical gate 不會被其他通過案例抵銷。
04
做 blind review 與版本變更
讓另一位 reviewer 用合約評三個 diff 與 receipt，記錄不一致。若問題是合約缺欄位，建立 1.0.1 並說明影響；若只是 candidate 失敗，不修改 oracle。
檢查點 · Reviewer 能獨立說明 pass、fail、blocked 與 missing evidence，版本差異有 owner 與理由。

實務脈絡

展示版之後

從效果與權限反推

先寫 actor 能做與不能做的事情，再寫 UI 或 API。Release Desk 的 reviewer 可以對 open request 提出 changes，必須附 20 到 500 字元原因，狀態要持久化並寫一筆 audit。非 reviewer、非 open 狀態、過期 version 與未知 request 都要有各自終止碼。

模型提出的 tenant、role、request owner 或 environment ID 不能當授權依據。這些欄位由登入 session 與 authoritative store 取得。合約同時寫清禁止外部網路、production 資料、未列出的 schema 重構、廣泛刪除與停止其他專案程序。

先寫 oracle 再跑候選

每個案例列 fixture、操作、預期狀態、邏輯效果次數、可接受修改路徑、必要 evidence 與 criticality。Happy path 之外還要放 invalid reason、wrong role、stale version、timeout before dispatch、timeout after effect、browser skipped、refresh loss 與 unrelated diff。

合約變更要有 owner、理由、版本與受影響案例。若產品需求真的改變，建立新版本並重跑 baseline，不在候選失敗後直接把門檻刪掉。這是保護評測可信度，也讓未來 session 知道哪個版本才是目前 repository truth。

交付補強

合約交付時，另做一張欄位責任表。Actor、角色、request version、目前狀態與既有效果由可信儲存區提供；reason 與操作意圖才來自使用者輸入。Agent 可以提議執行方案，卻不能自行補上權限欄位。這張表能抓出一個常見漏洞：前端把角色放進 request body，後端驗格式後便直接採信。即使 UI 只讓 reviewer 看見按鈕，偽造 request 仍可能越權。Fixture 應直接呼叫 executor，證明 trusted identity 會覆蓋或拒絕 model-supplied authority。

把 terminal reason 當成合約輸出，不要只做 pass 和 fail。輸入格式錯誤是 invalid；actor 無權限是 denied；需要產品 owner 決定新轉換是 blocked；預算先用完是 budget_exhausted；write 結果不明是 unknown_effect；證據完整才是 verified。每個狀態都要對應操作手冊與允許下一步，才能防止 agent 遇到任何非成功狀態就一律 retry，或用自然語言把 denied 說成暫時性問題。

Review contract 時，請一位沒參與需求討論的人只看 fixture 與 schema，逐題回答：誰能做、起點是什麼、哪個效果算一次、哪些檔案可改、缺哪筆證據就不能完成。回答若需要回頭問口頭背景，表示那個決策尚未進 system of record。修正後保留 reviewer 原本的誤解，因為它就是未來 cold session 可能採用的錯誤路徑，也應成為 regression case。

動手實作

把基準任務改寫成可執行合約

從原始 brief 與 baseline failure 建立 JSON task contract、十個案例、禁止效果清單與 receipt schema，再故意送入模糊與越權版本。

準備項目

• 凍結原始 task text 與模組 00 receipt，不直接覆寫證據
• 邀請一位未參與基準的 reviewer 只靠合約判斷三個 sample diff

本課產出

Versioned task contract、十個 fixture、claim-to-check 表、禁止效果與修改範圍、receipt schema、變更紀錄，以及 blind reviewer 的判斷差異。

起始模板: 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 計畫、工具輸出、驗收與 reviewer 判斷，並且在證據不足或 authority 缺失時誠實停下。

留給下一課

將 task-contract.json 與 case set 視為後續各模組的 source of truth。Repository map、initializer、ledger、tools、rules、eval 與 capstone receipt 都要記錄 contract version。

驗收條件

01Contract schema 驗證 actor、狀態、輸入、效果、範圍、預算、證據與終止原因
02十個案例在執行前就有 oracle 與 criticality
03未知 write completion 只能走 reconciliation，不能直接 retry
04Blind reviewer 判斷能對到合約欄位；任何版本變更有理由與 owner

常見故障

故障診間

F1合約很長，卻仍無法判斷頁面是否真的完成。

先檢查: 找每個需求對應的 oracle、fixture、使用者操作與 evidence。
可能原因: 內容只描述目標與實作建議，沒有可觀察行為與權威判準。
修復方式: 補 claim-to-check 表，把畫面、持久化、權限與效果分開驗。
下次怎麼避免: 沒有 oracle 與 receipt 欄位的要求不得標為可驗收。

F2候選失敗後，團隊把案例答案改成目前實作。

先檢查: 比對 contract history、case diff、執行時間與變更 owner。
可能原因: 產品變更與降低評測門檻沒有分開。
修復方式: 恢復 locked set；真的需求變更另開版本並重跑基準。
下次怎麼避免: 所有 oracle 變更都要在候選之外審核，保留舊版本結果。

F3Agent 把自己產生的 role 欄位當成授權。

先檢查: 追 actor、tenant-like scope、session、database policy 與 tool executor 的來源。
可能原因: 合約寫了欄位形狀，卻沒寫 authoritative owner。
修復方式: 由 trusted runtime 派生身份，拒絕 model-supplied authority。
下次怎麼避免: 每個 consequential 欄位都標 source of truth，並加入 forged-field fixture。

展示版之後

正式上線前的邊界

01合約有版本、owner、適用 task class、起始 commit 與變更紀錄
02Actor、身份、狀態、version 與 authority 都標示可信來源
03成功、拒絕、blocked、unknown、budget exhausted 與 need review 有不同終止碼
04允許路徑、保護資源、禁止效果、預算與 destructive boundary 能被 verifier 執行
05案例在候選前鎖定，critical permission、secret、effect 與 scope gate 不做平均
06Receipt 綁 contract、commit、environment、fixture、check、effect 與 reviewer decision

證據類型

資料來源與主張限制

資料來源只支撐本課標示的主張，不代表換一個系統也會得到相同結果。

[1]
長時間應用程式開發的 harness 設計
Anthropic · 已發表研究 · 2026-08-26
planner、generator、evaluator · 可測合約 · 簡化 harness · 成本取捨
[2]
打造有效的 agent
Anthropic · 官方文件 · 2026-08-26
採用能通過需求的最簡架構 · workflow 模式 · 環境回饋 · 停止條件
[3]
Harness engineering：在 agent-first 開發環境中運用 Codex
OpenAI · 公開案例 · 2026-08-26
知識留在 repository · 讓系統對 agent 可讀 · 機械式規則 · 處理 repository entropy
[4]
Andrej Karpathy 的 AI Engineering Playbook
AI Builder Club · 公開案例 · 2026-08-26
Software 3.0 觀點 · spec、diff、eval 實作 · 平行 session · repository 指令
[5]
Learn Harness Engineering
Walking Labs · 公開案例 · 2026-08-26
專案式學習順序 · 五個 harness 子系統 · 迴圈工程 · 工作圖工程