| 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。
