# Harness Writing

> Use when 要為新專案或既有專案建立專屬的 harness 開發流程（階段化閘門 + 專案契約制度），或用戶說「建 harness」「導入開發流程框架」「幫這個專案定契約」。適用於任何語言/stack 的 repo。

- **Type:** Skill
- **Install:** `agentstack add skill-tienenwu-fables-harness-writing`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tienenwu](https://agentstack.voostack.com/s/tienenwu)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tienenwu](https://github.com/tienenwu)
- **Source:** https://github.com/tienenwu/fables/tree/main/harness-writing

## Install

```sh
agentstack add skill-tienenwu-fables-harness-writing
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> 🌐 [English version](https://github.com/tienenwu/fables/blob/main/en/harness-writing/SKILL.md) · 繁體中文（正本 / 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](https://github.com/tienenwu)
- **Source:** [tienenwu/fables](https://github.com/tienenwu/fables)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tienenwu-fables-harness-writing
- Seller: https://agentstack.voostack.com/s/tienenwu
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.