當我用 AI Agent 開發遊戲：我如何為自己的專案打造「韁繩系統」

作者：個人獨立開發者 ｜ 專案：3KLife（三國題材策略遊戲，Cocos Creator 3.8）
關鍵字：Harness Engineering、AI Agent、Coding Agent、自動化驗證、小模型友善設計

回首頁 ｜ 回文章列表 ｜ English version

前言：AI Agent 寫出來的程式碼，誰來負責品質？

過去一年，我幾乎把自己的遊戲開發流程全面轉向 AI Agent 驅動。GitHub Copilot、Claude，還有各種自動化腳本，輪番上陣。效率確實大幅提升——但隨之而來的問題是：Agent 會犯錯，而且犯的錯都是無聲的。

它不會跳錯，不會報警，只會安靜地在你的 JSON 裡塞入一個結構錯的欄位，或者把一個模組的 import 悄悄指向它不該碰的地方。等你發現的時候，可能已經是三天後的 code review。

直到我讀到 Martin Fowler 的 Harness Engineering for Coding Agent Users，才意識到這件事有個正式的名字，而且有系統的解法。

本文是我的盤點與反思——我已經做了哪些「韁繩（Harness）」？哪些還缺？以及我打算怎麼補。

一、什麼是 Harness？用一句話說清楚

Harness = AI Agent 中除了模型本身以外的一切。

分兩種：

好的外部韁繩能做到兩件事：

  1. 提高 Agent 第一次就做對的機率（事前引導）
  2. 讓 Agent 在人眼看到之前自我發現並修正問題（事後感測）

二、韁繩的兩個維度：時機 × 執行方式

維度一：時機（何時介入）

⬆️ Feedforward（前饋）── 行動之前
  • 系統提示詞
  • Instructions 規則集
  • 任務卡契約
  • 共識文件
  • Skill 路由
⬇️ Feedback（回饋）── 行動之後
  • Linter 報錯
  • 型別檢查失敗
  • 資料驗證腳本
  • 截圖回歸比對
  • 模組邊界守衛
⚠️ 關鍵陷阱：只有前饋沒有回饋 → Agent 永遠不知道規則有沒有生效。只有回饋沒有前饋 → Agent 不斷重蹈覆轍、浪費 tokens。兩者缺一不可。

維度二：執行方式（誰來判斷）

執行方式 特性 典型範例 建議使用頻率
Computational（計算型） 確定性、快速、CPU 驅動 tsc、ESLint、JSON Schema 驗證 每次變更都跑
Inferential（推論型） 非確定性、較慢、GPU/LLM AI Code Review、語意分析 選擇性使用
核心原則：能用計算型解決的判斷，絕對不要讓 LLM 去做。計算型快十倍、便宜一百倍、而且結果是確定的。

三、三大治理類別

可維護性（Maintainability） 架構適配性（Architecture Fitness） 行為正確性（Behaviour）
重複碼偵測 效能基線測試 功能規格驗證
複雜度分析 模組邊界守衛 AI 生成測試
覆蓋率檢查 API 品質檢查 Approved Fixtures

四、盤點：我的專案做了什麼？

① Instructions 規則集（10 份）

在 .github/instructions/ 下維護了 10 份針對不同場景的引導規則，包含 token 預算控制、UI 框架遵守規則、圖片讀取節流等。每份都有 applyTo 路徑過濾，只在相關檔案被編輯時自動載入。

② Skills 定義（29 個）

把常見工作流程封裝成可調用的 Skill，例如：

Skill 的價值在於：把「人類專家的執行記憶」形式化了，不是靠 Agent 自行推理，而是讀到 Skill 就知道標準作業流程。

③ 任務卡系統（142 張）

每張任務卡包含：

這讓 Agent 不需要「理解整個系統」就能執行局部任務——只需讀卡片、按契約做、跑驗證、通過就完成。

④ 共識文件（keep.md + 分片索引）

所有設計決策都留有記錄，並拆成四個分片按需讀取，避免每次載入全文浪費 tokens。

Pre-flight 標準程序
1
讀 keep.summary.md（精簡索引，快速掌握所有已知共識）
2
若需修改共識 → 才讀對應分片全文（按需載入，不整份讀）
3
新決策 → 補回 keep → 同步交叉索引（確保共識持續更新）

⑤ Context Budget 管控

維護了 check-context-budget.js，可在任務中途主動檢查 token 使用量，並在接近上限時觸發壓縮。這個設計很關鍵——LLM 的品質在 context 過滿時會嚴重下降，而大多數人根本不知道自己已撞上這個問題。

五、現有計算型感測器盤點

工具守護對象狀態
check-encoding-touched.jsUTF-8 BOM / 亂碼防災✅ 有
validate-ui-specs.jsUI 規格結構完整性✅ 有
validate-skin-contracts.js皮膚家族資產契約✅ 有
validate-generals-data.js武將資料 JSON Schema✅ 有
validate-bloodline-integrity.js血脈圖資料一致性✅ 有
ucuf-screenshot-regression.js截圖回歸比對✅ 有
ESLint / TSLint編碼規範自動強制❌ 無
自動化單元測試套件功能邏輯正確性❌ 無
check-import-boundaries.js模組間交叉耦合防護❌ 無
Approved Fixtures 機制行為快照自動比對❌ 無

六、核心問題：我讓 LLM 做了太多「它不該做的判斷」

目前的品質保障幾乎完全依賴 Agent 的「推論能力」——讓它去「判斷」這段程式碼對不對。這恰恰是 Harness Engineering 最警告的反模式。

現狀（依賴 LLM 判斷）目標（計算型工具判斷）
LLM 判斷「這個 import 違反架構嗎？」 check-import-boundaries.js 用 AST 直接判定
LLM 判斷「JSON 格式正確嗎？」 JSON Schema 驗證腳本
LLM 判斷「UI 元件尺寸符合規格嗎？」 validate-ui-specs.js 數值比對
LLM 判斷「型別是否正確？」 tsc --noEmit 告訴你哪行有錯
LLM 判斷「這個功能輸出對嗎？」 Approved Fixtures 預設答案比對
一句話原則：把你目前讓 LLM 做的「判斷」，能用腳本做的就用腳本做。LLM 只負責「寫新東西」和「讀懂人話」。

七、改進方案：計算型閘門（Compute Gate）架構

7.1 整體執行迴圈

Agent 執行迴圈（改進後）
1
人類：複雜需求 → 拆解成 Milestone → 拆成原子任務卡 每張卡含 INPUT_CONTRACT / OUTPUT_CONTRACT / VALIDATION_CMD
2
Agent 讀取任務卡 確認前置條件（INPUT_CONTRACT），明確完成定義（OUTPUT_CONTRACT）
3
Agent 執行程式碼修改 只做「寫新東西」，不做「判斷是否正確」
4
計算型閘門（Compute Gate）自動執行
  1. tsc --noEmit：型別與語法檢查
  2. check-encoding-touched.js：UTF-8 完整性
  3. validate-*.js：資料 / UI 結構驗證
  4. check-import-boundaries.js：模組邊界守衛
✗
若閘門失敗 → 錯誤訊息直接成為下一輪 Prompt Agent 根據確定的錯誤訊息修正，最多 3 輪自動迴圈（不靠猜測）
✓
若閘門全部通過 → 輸出成果摘要 → 下一張任務卡 人類只需選擇性語意審查，不做例行性核查

7.2 模組邊界守衛規則

模組可以 import禁止 import
shared/（無，不可依賴任何業務模組）core、ui、battle
core/shared/ui/、battle/
ui/shared/、core/battle/
battle/shared/、core/ui/（單向）

用 AST 靜態分析每個 .ts 檔的 import 路徑，違規直接報錯。純計算型，不需要 LLM。

八、為什麼這對「小模型」特別友善？

當計算型工具承擔了所有「判斷」工作，LLM 只需要做最簡單的迴圈：

小模型也能穩定運作的迴圈
1
讀任務卡——明確的 INPUT / OUTPUT 契約，不需理解整個系統
2
寫程式碼——只做「寫新東西」，不做「判斷是否正確」
3
讀錯誤訊息——計算型工具給出確定性的具體錯誤（不是模糊的推測）
4
修正——根據具體錯誤定點修正，不靠推理猜測 → 回到步驟 2

即使是 1.5B 的小型模型，只要給它「明確的任務卡」＋「確定性的錯誤訊息」，就能穩定完成複雜功能。這不是因為小模型變聰明了，而是因為我們把「判斷」的工作從模型身上移走了。

九、韁繩健康評估與補強路線圖

當前狀態

類別分數說明
Feedforward Guides 80% Instructions、Skills、任務卡、共識文件均完整
Computational Sensors 30% 資料驗證充分，但缺 Linter、單元測試、邊界守衛
Behaviour Harness 40% 截圖回歸配置中，Approved Fixtures 尚未建立
整體評分 ~55 / 100 前饋強，計算型回饋嚴重不足

補強優先順序

P0tsc --noEmit 整合進 compute-gate（0.5 天）── 消滅型別錯誤回溯
P0ESLint 基礎設定（0.5 天）── 編碼規範從記憶改為工具強制執行
P1check-import-boundaries.js（1 天）── 模組交叉耦合自動偵測
P1compute-gate.js 統一閘門（1 天）── 自動修正迴圈整合
P2approved-fixture-check.js（1.5 天）── 行為驗證自動化
P3harness-health-report.js（1 天）── 韁繩覆蓋率可視化儀表板

十、給其他開發者的五條建議

  1. 從「前饋」開始，因為它最便宜。
    Instructions 和 Skill 不需要任何工具，只需要你把「你的經驗」寫成文字。
  2. 計算型感測器 > 推論型感測器。
    每次你讓 LLM 去「判斷某件事對不對」，問問自己：「我能不能寫一個腳本？」答案是肯定的，就去寫腳本。
  3. 錯誤訊息就是最好的 Prompt。
    計算型工具的失敗訊息，直接成為 Agent 下一輪的 prompt。錯誤在哪行、什麼問題，一清二楚，不需要人工轉述。
  4. 共識文件是最被低估的前饋工具。
    把你所有「不想讓 Agent 每次重新發現」的設計決策，全部寫進共識文件。
  5. Greenfield 專案天生有優勢，現在就開始。
    Legacy 程式碼最需要韁繩，但最難建構。如果你的專案是新開始的，從第一天就讓每個模組有驗證腳本。

結語

Harness Engineering 的本質，是把你身為開發者的「隱性知識」外顯化、形式化，讓 AI Agent 能夠在沒有你的情況下，也盡量按照你的意圖行事。

我的專案在前饋層已經做得很好——29 個 Skill、10 份 Instructions、142 張任務卡。但計算型回饋感測器嚴重不足，這是今後最需要補強的方向。

一句話行動指南：把你目前讓 LLM 做的「判斷」，能用腳本做的就用腳本做。LLM 只負責「寫新東西」和「讀懂人話」。

本文基於 Martin Fowler《Harness Engineering for Coding Agent Users》(2026-04-02) 的核心框架，結合個人 Cocos Creator 遊戲專案（3KLife）的實際工程經驗撰寫。