| name | harness-writing |
| description | Use when creating, regenerating, or auditing a repository-specific development harness, contract system, risk router, evidence gate, or project workflow policy. |
🌐 English version · 繁體中文(正本 / canonical)
Harness Writing — 生成專案專屬的證據驅動流程
核心模型
Harness 是唯一的 orchestration kernel:狀態轉移靠風險路由與 claim→evidence 閘門;profile 選擇所需狀態;adapter 描述環境能力;契約保存專案判準;domain playbook 提供階段內技術方法。
不變核心不重造,專案參數不杜撰。檔案數只能當輔助訊號;主要依可逆性、爆炸半徑、歧義、外部副作用與可驗證性路由。
何時用
- 新專案需要 Harness、契約索引與機械檢查基線。
- 既有專案要導入或重新校準 AI 開發流程。
- 稽核現有 Harness 是否有雙真相、假證據、過度審查或契約污染。
- 不適用:只新增一條已確定的專案契約;直接依既有生命週期修改。
生成流程
1. 探勘(唯讀)
- 盤點目錄、CI、既有規範、架構整合點、公開介面、正式資源與 release 路徑。
- build/test/lint 指令先判斷副作用;安全者各實跑一次,記耗時、輸出與基線失敗。不確定是否寫正式資源就不跑並明記。
- 盤點能力而非產品名:能否隔離寫入、執行 shell、跑測試、啟動 fresh reviewer、保留 artifact、取得第二模型家族。
- 從真實專案推導五個風險訊號與絕對升級條件;查無就寫「無」。
- 已有 harness 時修改它,不重新生成第二套。
2. 生成 Kernel/Profiles/Adapters
完整讀 harness-core-template.md 並填完所有 {{SLOT}}。以下不變量不得默刪:
- 契約先行與指令優先序。
- 機械檢查先於 AI review。
- PASS 必須附 claim→evidence;reviewer 自述不是證據。
- 只在高成本歧義、不可逆選擇或外部副作用消耗使用者注意力。
- 回歸基線與範圍檢查。
- 契約
candidate → active → hardened → deprecated 生命週期。
- 無法取得獨立 reviewer 時誠實降級,不假裝雙審。
覺得某項不適用時,在生成報告列出理由交給使用者裁決。
參數先寫成 JSON,再用 scripts/render_harness.py --template harness-core-template.md --config <config.json> --output <target-repo> 產生三個 artifact。renderer 只保證欄位完整、slot 全數解析與不覆寫既有檔案;參數真實性仍必須由探勘證據證明。
3. 初始契約
- 現有明文規則可建為
active;必須附來源與測驗/檢查。
- 從程式碼慣例歸納的規則只能建為
candidate,不可因一次觀察直接生效。
- 新專案只建索引、schema 與維護規則;不塞想像中的最佳實務。
candidate 只有在再次觀察、使用者明確裁決或明確事故證據下升 active;能低成本機械化再升 hardened。
4. 接線
- 產出
.claude/skills/harness/SKILL.md、references/pipelines.md 與 docs/contracts/README.md。
- 專案規範只接到 Harness 這個 orchestration 入口;
feature-flow 等 process skill 作為 profile/階段策略,不建立第二狀態機。
- 產出統一落在
docs/plans/<slug>/;既有路徑可保留相容入口,但必須指定單一 canonical source。
5. 驗證交付
- 用 quick、standard、high-risk 各一個情境冒煙路由,核對分檔理由與所需證據。
- 對 renderer 產物執行
rg '\{\{[^}]+\}\}' .claude/skills/harness docs/contracts;任何殘留 slot 都阻擋交付。
- 驗證所有機械命令安全且可跑,adapter 沒引用不存在的能力。
- 有獨立 reviewer 能力時:semantic 與 executable 分開審;高風險再加 adversarial。沒有時以 fresh read-back/實跑補足並列出限制。
- 交付:檔案清單、探勘證據、基線、risk router、adapter 能力、初始契約狀態、未驗證項目。
紅線
- ❌ 用檔案數當唯一風險判準;單檔 migration 仍可能是 high-risk。
- ❌ 兩個相同 prompt/相同證據路徑就宣稱獨立雙審;相關錯誤不會因票數消失。
- ❌ 只有 PASS/REJECT、沒有 claim→evidence 的 verdict。
- ❌ 把一次性現象直接寫成 active 契約。
- ❌ 為了遵守流程同時保留 Harness 與另一套完整 process source of truth。
references 索引
harness-core-template.md:生成前全文讀取;不可只靠本檔摘要自行重建。
references/evaluation-protocol.md:換模型、校準路由或評估流程成本/成效時讀。
references/evaluation-scenarios.json:行為 gate 的 canonical scenario ID/★ mapping。
references/test-scenarios.md:換模型、修改 risk router/evidence/契約生命週期後,以 fresh session 回歸。
scripts/render_harness.py:驗證 slot 並安全產生三個 canonical artifact。
scripts/evaluate_runs.py:驗證 JSONL 行為紀錄、彙總成效指標並執行 gate。