AI Workflow Conduction

繁體中文

Home
English

繁體中文

Home
English

Appearance

Harness Engineering 線控工程 ​

本提案將 harness engineering（線控工程） 引入為 AI Workflow Conduction 框架中的一級學科。Harness（線控）是 LLM 之外的一切：可呼叫的工具、決定何時停止的迴圈、跨步驟保留的記憶、阻擋危險動作的護欄，以及驗證輸出的感測器。核心身份為：

Agent = Model + Harness

核心洞察： 隨著前沿模型在原始能力上逐步收斂，其外圍的 harness 才是真正的差異化。一顆強模型若 harness 設計不佳，會卡死迴圈、選錯工具，或越過權限邊界。設計良好的 harness 會讓同一顆模型在相同任務上獲得顯著更高的可靠度。

相關提案： Claude Skills 採用、AI 代理友善知識庫、AI 優先脈絡基礎建設、持續脈絡清理

問題陳述 ​

「更多脈絡」的天花板 ​

第 1.2 節「脈絡」 已說明規格混亂、審查速度落差與角色混淆如何限制 AI 效能。AI 優先脈絡基礎建設 與 AI 代理友善知識庫 的回應是給 agent 更好的脈絡。

更好的脈絡會抬高下限，卻無法修復所有失敗模式。

一顆能力充足、脈絡完整且整理良好的模型，仍會在脈絡無法觸及的層面上失敗：

失敗模式症狀為何脈絡無法單獨解決
Agent 卡死迴圈無法終止；agent 重複同一個工具呼叫迴圈終止由 harness 控制，非脈絡控制
選錯工具存在專用工具時 agent 仍挑通用工具工具粒度是 harness 的設計決定
權限越界Agent 未經確認執行破壞性動作權限邊界位於 harness，不在 prompt
靜默飄移輸出看似合理；無人發現回歸Sensors（測試、reviewers）屬於 harness 範疇
單次會話過長任務執行中途耗盡 context window記憶管理與摘要是 harness 的功能

三個典範，而非一個 ​

提示詞工程、上下文工程、線控工程處理三種不同的失敗面。它們疊加，而彼此不會取代。

知識在各層之間疊加。昨日的 prompt 技巧活在今日的 SDK 內部；今日的脈絡經驗形塑明日的 harness 設計。跳過脈絡層直接採用 harness engineering 的團隊，會在脈絡工程提案原本要解決的問題上再摔一次。

定義 ​

Agent = Model + Harness ​

Martin Fowler 在 Harness engineering for coding agent users 裡直接給出此身份：

「Harness engineering 指的是 AI coding agent 中除了模型本身以外的一切。」

Parallel Web Systems 將定義延伸到 coding 以外：

「Harness 是連接 AI 模型與外部世界的介面，讓模型能使用工具、在步驟間保留資訊、與複雜環境互動。」

Harness 有五個可觀察的組件：

  1. Tools（工具） — 模型可呼叫的表面。粗粒度或細粒度、通用或領域專用。
  2. Loop control（迴圈控制） — 停止條件、升級觸發、預算上限、多 agent 協調。
  3. Memory and state（記憶與狀態） — 工作脈絡、session log、長期記憶、摘要與檢索。
  4. Guardrails（護欄） — 權限邊界、schema 驗證、安全過濾。
  5. Sensors（感測器） — 測試、linter、type checker、review agent、runtime monitor，在 agent 行動後觀測輸出。

Guides 與 Sensors ​

Fowler 依控制「作用時機」將 harness 切為兩類：

Guides 在 agent 行動「之前」塑形輸出。它們提高首次嘗試就產出正確結果的機率。

Sensors 在 agent 行動「之後」觀測輸出。它們捕捉失敗嘗試，並把訊號回饋到迴圈。

Computational 與 Inferential 控制 ​

第二個正交軸：控制本身如何執行。

類型延遲成本決定性範例
Computational（計算型）毫秒到秒接近零決定性Linter、type checker、單元測試、schema 驗證器
Inferential（推論型）秒到分鐘LLM 呼叫非決定性Review agents、LLM-as-judge、語意飄移偵測

計算型控制穩定抓出機械性問題。推論型控制補上機械規則無法表達的語意判斷。成熟的 harness 兩者並用。

作業系統類比 ​

KodeLAB 中文分析常見的框架：

  • 模型是 CPU — 原始計算。
  • Context window 是 RAM — 工作記憶，有邊界。
  • Harness 是 作業系統 — 排程工作、管理資源、中介工具與記憶的存取。

裸 LLM 是一顆沒有 OS 的 CPU。它能計算。它無法自主完成有用的工作。

提案解法 ​

在模型上方疊出一套 共用組織 harness。共三層：

Layer 1：基礎 Harness ​

跨團隊共用的標準 agent runtime 設定。

元素建議預設
Agent runtimeClaude Code（或具備 skills、hooks、MCP 支援的等效方案）
權限預設最小化 — 未經 allow-list 不得寫入或執行
Hooks透過 pre-tool-use hook 強制執行專案 AGENTS.md 邊界
設定檔每個專案提交 .claude/settings.json
模型最新 GA 前沿模型，除非專案另行鎖定

Layer 1 的重點不是選一次 runtime 就結束。重點是讓選擇變得明確、讓設定被共用，讓每個團隊都繼承相同預設，差異僅在有正當理由時才出現。

Layer 2：組織的 Guides 與 Sensors ​

本章既有提案就是組織的 guides 與 sensors。Harness engineering 是把它們串起來的框架。

角色元件既有提案
GuideAI 可存取的脈絡面AI 優先脈絡基礎建設
GuideMarkdown 知識庫AI 代理友善知識庫
Guide共用 Claude SkillsClaude Skills 採用
Guide規格檢索內部規格平台
Guide術語約束統一語言
Guide既存事實規格規格萃取
Guide需求單一事實來源全域需求倉儲
Guide元件盤點設計系統
Guide元件擁有權模式shadcn/ui 基礎
Guide規格階層多產品規格管理
Guide文件圖譜Frontmatter 規格協調
Guide專案 AI 引導檔CLAUDE.md 標準（規劃中）
SensorLinter 與 type checker工具基線
Sensor持續清理審查持續脈絡清理
Sensor技術堆疊對齊Tech Radar 與路線圖
Loop ControlAI 優先決策點AI 優先決策
Loop ControlElaboration 會議AI-DLC Mob Elaboration

Layer 3：Steering Loop（引導迴圈） ​

相同失敗模式再次出現時，迭代的是 harness，不是 prompt。

診斷對照表：

症狀可能層級
輸出形狀錯誤、格式飄移Prompt
事實缺漏、引用過時脈絡
Agent 卡死、選錯工具、權限越界、靜默回歸Harness

Steering loop 需要掛名負責人。Harness 變更走輕量審查流程，與其他基礎建設變更一致。

實施路線圖 ​

四個階段，避免「harness 出貨了沒人用」的失敗。

Phase 1：建立 Harness 基線 ​

交付：

  • 參考 repo 提交標準 .claude/settings.json。
  • 發布 AGENTS.md 範本。
  • 權限 hook 擋掉未授權的寫入或執行動作。
  • 每位工程師一份「你機器上跑的是什麼」說明文。

退出條件：

  • 每個活躍專案都有 AGENTS.md。
  • 預設權限邊界由 pre-tool-use hook 強制執行。

Phase 2：佈建 Guides ​

交付：

退出條件：

  • 兩個以上團隊在消費共用 skills。
  • Agent 能取得領域知識而不需人工貼上。

Phase 3：佈建 Sensors ​

交付：

  • 每個 repository 上 CI 整合的 linter 與 type checker。
  • 超過規模門檻的 PR 走 LLM-as-judge 審查流程。
  • 持續脈絡清理流程運作中（見 持續脈絡清理）。

退出條件：

  • Sensor 訊號會寫回 agent 迴圈（而非僅呈現在人類儀表板上）。
  • 至少一類回歸已在合併前被 sensors 擋下。

Phase 4：制度化 Steering Loop ​

交付：

  • 組織 harness 有掛名負責人。
  • 每月 harness 回顧審視反覆出現的失敗模式。
  • 文件化的週期時間目標：問題觀察到 harness 更新完成。

退出條件：

  • Harness 變更與產品工作進同一個 backlog。
  • 命名失敗模式的復發率逐月下降。

成功指標 ​

指標目標量測方式
命名失敗模式的復發率逐月下降依失敗類別追蹤標記 issue
跨團隊 skill 重用率活躍 skills 有 > 50% 被多於一個團隊使用Skill 呼叫日誌
需要人類救援的 agent session每週 < 10%Session telemetry 或自報
問題到 harness 更新的週期時間中位數 < 1 sprintIssue 開啟到 harness 變更合併的時間戳
共用 AGENTS.md 採用率活躍專案 100%CI 做檔案存在檢查

反模式 ​

以下是缺少 harness 紀律的團隊在採用 agent 框架時觀察到的失敗模式。

反模式外觀為何反效果
Prompt 塞填每次新失敗就在 system prompt 加更多文字Prompt 變得難讀；脈絡預算壓縮；根因通常是缺少工具或 sensor
脈絡膨脹每次新失敗就把更多文件灌進脈絡訊噪比下降；模型輸出品質變差
Harness 蔓生多個職責重疊的 skills、hooks、MCP servers 並存Agent 挑錯那一個；維護負擔複合成長
孤兒 harnessHarness 存在，沒有掛名負責人，沒人更新飄移靜默累積；團隊悄悄停用
單層思考把 harness 當作脈絡工程的替代品缺失的知識仍會產出錯誤程式碼；三層疊加，彼此不取代

CLAUDE.md 整合 ​

專案的 CLAUDE.md（或 AGENTS.md）是專案層級的首要 Guide。最少需宣告：

  • 本專案可用的 skills 範圍。
  • Agent 可在無確認下呼叫的工具。
  • 專案規格、設計系統、知識庫的位置。
  • Steering-loop 負責人希望被通知的事項。

完整 schema 見 CLAUDE.md 標準（規劃中）。

相關提案 ​

Harness 角色提案
GuideAI 優先脈絡基礎建設
GuideAI 代理友善知識庫
GuideClaude Skills 採用
Guide內部規格平台
Guide統一語言
Guide規格萃取
Guide全域需求倉儲
Guide設計系統
Guideshadcn/ui 基礎
Guide多產品規格管理
GuideFrontmatter 規格協調
Sensor持續脈絡清理
SensorTech Radar 與路線圖
Loop ControlAI 優先決策
Loop ControlAI-DLC Mob Elaboration

參考資料 ​