AI Coding Harness

它是什麼

AI coding harness（AI 編碼框架）是你在編碼 agent 周圍搭建的強制執行與驗證腳手架，讓它能夠自主執行而不至於把事情搞砸。如果說護欄（guardrail）是一種你必須靠記憶去遵守的習慣（跑測試、看 diff），那麼 harness 就是一臺替你記住這些的機器：它位於 agent 的意圖與真實世界之間，在每一個危險步驟上進行記錄、警告或攔截。dancinlab/harness 是一個與具體專案無關的參考引擎——一個共享的 TypeScript 核心，每個倉庫的差異僅在於一份 harness.config.json 加上幾個 .harness/*.json 資料檔案。

優勢

把你的護欄從可有可無的習慣變成由程式碼強制執行的規則——agent 無法跳過它們。
對整個工具生命週期進行把關：命令執行之前、檔案寫入之前、在 prompt 上、在 commit 時、在 push 時。
這裡說的賬本，就像一個只往後新增新行、永不擦除舊行的筆記本。這些賬本以 JSONL（ Lines——每行一個 JSON 物件）寫成，提供了 agent 一切行為的防篡改記錄。寫入成本極低，審計也輕而易舉。
可嵌入任何倉庫：行為由配置和資料決定，而非分叉的程式碼。
設計上在一切正常時保持安靜，因此警告出現時仍然有分量。

取捨

它是管道工程，不是魔法：harness 讓錯誤易於被廉價地捕獲，但它並不能讓 AI 變得正確。
需要初始設定，以及一份針對你專案危險區調校過的配置。
過於嚴格的規則會帶來摩擦；"bitter-gate"（苦閘）紀律——在新增規則之前先退役一條休眠規則——正是為了對抗這一點而存在。
在有真實使用者的真實專案上最有價值——對於一次性的原型來說則是殺雞用牛刀。

最適合

認真的 vibe coding：你讓一個 agent 在基本無人監督的情況下進行多檔案改動並執行命令，同時你需要把一次糟糕操作的代價維持在接近於零。

五項原則（H1–H5）

H1 成功安靜、失敗響亮——不製造你遲早會學會忽略的噪音。
H2 永不自動修復——提出建議、攔截或警告；由人類或知情的 agent 來決定。
H3 Bitter-gate——在新增規則之前先退役一條休眠規則。
H4 配置驅動——一個引擎，每個專案一份 harness.config.json。
H5 AI 原生——僅追加的 JSONL 賬本，無法被悄然改寫。

它長什麼樣

一份最簡配置草圖：

// harness.config.json
{
  "lockedPaths": ["src/auth/**", "infra/**", ".github/**"],
  "blockCommands": ["rm -rf", "git push --force", "curl * | sh"],
  "verify": ["npm run lint", "npm run typecheck", "npm test"],
  "ledger": ".harness/ledger.jsonl"
}

以及圍繞單次 agent 操作的前置/後置鉤子（hook）流程：

agent intends an action
        │
   ┌────▼─────────────┐
   │ pre  (PreToolUse) │  block dangerous? warn? → else allow
   └────┬─────────────┘
        │  command runs / file is written
   ┌────▼──────────────┐
   │ post (PostToolUse) │  record to JSONL · warn if a locked file was touched
   └────┬──────────────┘
        │  at commit / push
   ┌────▼─────┐
   │  verify  │  lint · typecheck · tests (parallel) → green or stop
   └──────────┘

agent 永遠無法繞過這道閘門——這正是整件事的關鍵所在。