Harness Writing

> 🌐 English version · 繁體中文（正本 / canonical）

Harness Writing — 為專案生成專屬的契約驅動開發流程

Overview

Harness = 一台會自我改寫的有限狀態機：狀態有產出、轉移靠獨立雙審、契約是持久記憶、蒸餾是回饋邊。本 skill 的工作是生成某個專案專屬的 harness——不變核心直接套模板（harness-core-template.md），專案參數靠探勘實測填入。

核心原則：不變核心不重新發明，專案參數不憑空杜撰。 核心機制（雙審、複述確認、親驗、蒸餾）是在真實專案裡付過學費驗證過的，生成時原樣保留；機械檢查指令、慣例、初始契約則必須來自對目標專案的實際觀察與實跑。

When to Use

• 新專案開張，想從第一天就有流程與契約
• 既有專案要導入 AI 開發紀律（有或沒有 CLAUDE.md 都適用）
• 不適用：只想加一條規範到既有契約（直接編輯契約檔）；目標專案已有 harness（去改它，不要重生成）

生成流程

1. 探勘（唯讀，杜絕杜撰）

• 既有專案：目錄結構、build/test/lint 指令（每個指令實跑一次驗證可用，記下耗時與現有失敗數當基線）、CI 設定、CLAUDE.md/README 既有慣例、git log 風格與痛點、可用的 reviewer subagent 類型、環境可用的 skills 清單（brainstorming/spec/plan/TDD/code-review/debugging/verify 類——用來填模板的「Skill 活用對照表」，讓生成的 harness 各階段套用既有 skill 而非裸 prompt）
• 新專案：問用戶 stack/測試框架/品質要求（一次問完），先把最小工具鏈建起來（linter + test runner 能跑空測試），才有東西給機械檢查用
• 查無的項目明確記「無」——「這專案沒有 CI」本身就是 AI 必須知道的事實

2. 填模板生成 SKILL.md

讀 harness-core-template.md，填入所有 {{SLOT}}。鐵律：

• 機械檢查指令沒實跑過不得寫入（寫了跑不動的指令，整個閘門形同虛設）
• 不變核心條文（雙審、鐵律、三檔分流、蒸餾格式）不得刪減，只能追加專案特定內容；覺得某條不適用 → 在生成報告中列出理由給用戶裁決，不要默默拿掉

3. 初始契約引導

• 既有專案：從 CLAUDE.md/README/git log/程式碼慣例蒸餾 3–8 條初始契約，每條必須能指出「從哪個檔案/現象歸納」；分檔依領域（如 style/testing/domain 各一檔）+ README 索引
• 新專案：只建 README 索引與維護規則（含條目格式、修剪義務），契約讓實戰蒸餾去長——第一天塞滿想像中的規則是反模式
• 契約條目一律用模板內的四段格式（規則／為什麼+日期／可執行的檢查方式／硬化狀態）

4. 接線（沒接就不會被用）

• 生成的 harness SKILL.md 的 description 寫成自動觸發條款（「涉及新功能/修 bug/功能改動即必須載入」+ 例外通道「快速改/不用流程」）
• 專案 CLAUDE.md 加強制段落（指向契約索引 + harness + 收尾蒸餾義務）
• 驗證：確認 skill 出現在可用清單（新開對話或檢查 .claude/skills/ 路徑正確）

5. 驗證交付

• 派 2 個獨立 reviewer 審生成物（甲：流程完整性與可操作性；乙：專案參數正確性——指令可跑？契約有據？）——吃自己的狗糧
• 用一個瑣事檔小任務冒煙走一遍（真實任務或演練均可），確認模板欄位合用、閘門無卡點
• 交付報告：生成檔案清單、探勘發現、初始契約依據、用戶待辦（如有）

常見錯誤

| 錯誤 | 後果 / 修正 | |---|---| | 直接複製來源專案的指令與路徑 | 機械檢查跑不動，閘門空轉。指令必須在目標專案實跑驗證 | | 契約第一天塞滿通用最佳實踐 | AI 拿理想值對抗既有慣例。契約只收「從現狀歸納」與「實戰蒸餾」的規則 | | 砍掉雙審/複述確認「因為專案小」 | 這些機制的價值恰恰在你以為不需要時。規模考量走三檔分流，不是砍機制 | | 只建檔案不接 CLAUDE.md/description 觸發 | harness 躺在那沒人載入。接線是交付條件 | | 跳過冒煙測試 | 沒走過一遍的流程文件必有卡點（欄位不合用、指令寫錯） | | review 只做一輪就宣告完成 | verdict 要落檔，REJECT 是自迴圈；生成物本身也要過雙審 |

Red Flags — 出現這些念頭就停

• 「這專案很簡單，不用雙審」→ 分檔解決重量問題，不是砍冗餘
• 「指令看起來就是這樣，不用跑」→ 沒實跑 = 杜撰
• 「先把契約寫齊全一點」→ 過度特化的契約是雜訊，讓蒸餾去長
• 「模板這條好像不適用，拿掉」→ 列給用戶裁決，不默刪

模板

不變核心全文：harness-core-template.md（同目錄）。生成時整檔讀入、填 slot、依第 2 步規則調整。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tienenwu
• Source: tienenwu/fables
• License: MIT

Install and usage instructions live in the source repository linked above.