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

3KProject Engineering Notes

我如何使用 Harness Engineering 讓 3KProject 變得更穩定

這篇文章是我整理 3KProject 內部工程做法的一份筆記。專案裡本來就有 instructions、skills、任務卡、doc-id registry、context budget guard、UI 契約驗證、runtime smoke check 這些基礎設施，但真正讓 Agent 開始穩下來的，是我把工作流從「靠模型猜」慢慢改成「靠計算驗證」。

Guide 在動手前先給清楚的路徑、邊界與任務契約，降低 Agent 一開始就走歪的機率。
Sensor 在修改後立即用可執行檢查回報結果，讓錯誤在進入人工審查前先被攔住。
Loop 把失敗訊息直接回灌成下一輪修正輸入，讓小模型也能靠反覆收斂穩定交付。

一個核心觀念

Harness 不是模型本身，而是模型周邊所有讓它更不容易犯錯、犯錯後更容易被拉回來的機制總和。

如果把 Coding Agent 想成一台能高速產出程式碼的引擎，那 Harness 就是方向盤、煞車、儀表板與保險絲。我在 3KProject 的實際感受很直接：沒有這層工程韁繩，模型偶爾會很亮眼，但穩定度很差；有了這層韁繩之後，規格摘要、任務卡、驗證器、handoff 才會真的串成一條能重複執行的生產線。

在 3KProject 裡，我把 Harness 當成一套內部工程控制面板：`keep.summary` 負責導向，任務卡負責切片，編碼與契約檢查負責把錯誤擋在人工 review 前，runtime 檢查與 screenshot regression 則負責收尾驗證。

先看兩個最重要的座標軸

我在 3KProject 規劃這些工具時，最有幫助的一件事，就是先把控制手段拆成兩個簡單維度。第一個維度是「事前引導」對上「事後回饋」；第二個維度是「計算可判定」對上「需要語意推論」。這個拆法直接影響我該先投資哪種工具，而不是一直堆更多提示詞。

Harness 的四象限：先導正，再驗證；能計算的先交給工具 Feedforward Agent 動手前的引導 Feedback Agent 動手後的回饋 Computational 確定性、高頻率 Inferential 語意判斷、選擇性啟用 Computational × Feedforward 最值得先做的區塊 • 任務卡輸入/輸出契約 • 檔案路由規則與模組邊界 • 可直接執行的腳手架與模板 Computational × Feedback 品質穩定的主力 • 型別檢查、Lint、單元測試 • JSON/契約/快照驗證 • 編碼、防呆與依賴檢查 Inferential × Feedforward • 架構說明、示範案例、審稿規則 • 讓模型知道什麼叫「好答案」 Inferential × Feedback • AI Code Review、語意審查 • 價格較高，適合留在關鍵節點
圖 1：最重要的實務結論不是「四種都很重要」，而是「能用計算解決的，先不要丟給模型判斷」。

Feedforward

在 Agent 動手前先提供規格摘要、檔案範圍、任務契約與禁止事項。這些內容不是為了增加提示詞長度，而是為了減少無效嘗試。

Feedback

在修改後立刻回傳可執行驗證結果。只要失敗訊息夠短、夠具體，小模型也有機會靠局部修正快速收斂。

把韁繩分成三類，治理才不會失焦

我在 3KProject 早期也踩過同一個坑：只要覺得重要就先加規則，結果最後變成難以維護的規則堆。後來比較穩的做法，是把它拆成三個治理面向：維護性、架構適配與行為正確性。

Harness Engineering Maintainability • 重複碼與複雜度分析 • 型別健康度與測試覆蓋 • 編碼一致性與死碼掃描 目的：讓系統在頻繁修改下， 仍然能被人和 Agent 安全維護。 Architecture Fitness • 模組邊界與依賴限制 • 效能、記憶體、載入基線 • 可觀測性與 API 品質守衛 目的：把架構原則變成 可執行、可違規警示的規則。 Behaviour • 功能規格驗證 • Approved fixtures / golden cases • 回歸快照與互動 smoke checks 目的：驗證系統做出的事情， 是否真的符合產品期望。
圖 2：當團隊把 Harness 明確分區之後，討論就會從「要不要加檢查」變成「這是哪一類風險，該用哪種感測器攔」。

這個拆法對 3KProject 很重要，因為它把「品質」從抽象概念拆回實際責任。維護性管的是日常可改性；架構適配管的是長期演化時不走樣；行為管的是輸出結果有沒有做對。三者混在一起時，規則會越堆越多，但閉環反而越來越弱。

3KProject 目前的強項與缺口

回頭看 3KProject 目前的內部流程，我覺得 Feedforward 其實做得不差：instructions、workflow skills、任務卡、共識文件、doc-id registry、context budget guard 都已經在運作。真正薄弱的地方，反而是 Computational Feedback 還沒有完全補齊。

3KProject 目前的 Harness 能力盤點 引導層已成熟 • keep.summary、Instructions、Skills、任務卡、doc-id registry 都已經在運作 • Agent 開始前大致知道路徑、禁區、命名與 handoff 方式 風險低，但容易誤以為這樣就夠了 結構驗證具雛形 • 已有編碼檢查、UI contract 驗證、runtime smoke check、screenshot regression、資料驗證 • 代表 3KProject 已經知道哪些地方不能只靠肉眼 還缺整合式 gate，把結果回灌給 Agent Lint 與測試不足 • 缺少高頻執行的 linter、單元測試與 type-check pipeline • 品質仍偏向依賴模型記憶與人工 code review 這是最主要的穩定性缺口 模組邊界未工具化 • 我們知道哪些依賴不應該發生，但沒有完整的自動守衛 • 架構原則還是有一部分停留在文件與資深成員口頭提醒 長期會演變成耦合擴散 Approved fixtures 缺位 • 很多內部流程有 expected output，但沒有被保存成可回歸比對的基準 • 每次驗證都要重新靠人判斷，成本會一直堆上去 行為正確性無法穩定複用 整體判斷 • 3KProject 不是沒有規則，而是 Feedback 還不夠便宜、密集與自動化 • 我下一步不是加更多提示詞，而是補齊計算型感測器 這會直接決定 Agent 能否穩定擴張
圖 3：很多團隊不是沒有規則，而是規則沒有變成可以頻繁執行的檢查，於是品質仍然卡在人工審查。

3KProject 已經做對的事情

把經驗寫成 instructions、技能流程、任務卡、摘要卡與規格索引，是我把外部韁繩落到專案裡的第一步。這些機制確實讓 Agent 第一次就做對的機率提升很多。

我現在最想補的地方

如果沒有高頻率、低成本的計算型回饋，Agent 最後還是只能靠猜。表面上像是在做工程化，實際上只是把人工審查往後挪而已。

我想在 3KProject 裡落地的小模型工作流

這套方法對我來說最有價值的地方，是它不只服務最強的模型。3KProject 內部規格、UI、資料與工具鏈都很多，只要我把任務拆成原子步驟，並讓每一步都有明確的輸入、輸出與驗證命令，中型甚至小型模型也能穩定完成複雜功能。

複雜需求與里程碑拆解 原子任務卡 每張卡片都定義 INPUT_CONTRACT、OUTPUT_CONTRACT、VALIDATION_CMD 與 ROLLBACK_CMD Agent 修改 模型只專注在當前卡片的局部代碼與已知上下文，不必一次理解整個系統 計算型驗證 Type、Lint、Test、Schema 失敗：自動修正 直接把錯誤訊息回灌給 Agent 成功：輸出摘要 更新狀態，進入下一張任務卡 FAIL PASS
圖 4：對小模型最友善的不是更長的提示詞，而是更短的任務切片，以及更確定的驗證訊號。

把工作流設計成上圖之後，LLM 在 3KProject 裡的職責會變得非常單純：讀任務卡、修改局部、讀失敗訊息、修正局部。所有「這樣到底算不算正確」的判斷，我都盡量交給型別系統、規格驗證器、邊界檢查器與 fixtures 比對。

範例 1：任務原子化拆解器

node tools/task-decomposer.js \
        --feature "UI 契約閘門整併" \
        --spec "docs/ui/UI技術規格書.md" \
  --output-dir "docs/tasks/"

範例 2：計算型閘門設定

{
  "gates": [
    {
      "name": "syntax-check",
      "cmd": "npx tsc --noEmit --project tsconfig.json",
      "priority": 1
    },
    {
      "name": "encoding-check",
      "cmd": "node tools_node/check-encoding-touched.js",
      "priority": 2
    },
    {
      "name": "domain-data",
      "cmd": "node tools_node/validate-generals-data.js",
      "priority": 3
    },
    {
      "name": "ui-contract",
      "cmd": "node tools_node/validate-ui-specs.js",
      "priority": 4
    },
    {
      "name": "runtime-registry",
      "cmd": "node tools_node/check-ui-runtime-state-registry.js",
      "priority": 5
    },
    {
      "name": "import-boundary",
      "cmd": "node tools_node/check-import-boundaries.js",
      "priority": 5
    }
  ]
}
真正的關鍵不是 gate 名稱，而是失敗訊息要夠局部、夠可執行。只要 Agent 看得懂哪個檔案、哪一條規則、哪一個欄位出錯，修正成功率就會明顯上升。這也是我在 3KProject 裡一直強調「錯誤訊息本身也是 prompt」的原因。

我接下來最想補的五個工具

3KProject 其實不缺流程文件，缺的是能天天跑、跑完還能直接回灌給 Agent 的 Feedback 閘門。所以對我來說，最有效率的做法不是再寫更多規範，而是補齊幾個會每天被用到的工具。

  1. compute-gate.js：把型別、編碼、資料驗證、契約驗證整合成單一入口。
  2. check-import-boundaries.js：用自動檢查把模組邊界從口頭約定變成工具守衛。
  3. approved-fixture-check.js：把「人類已核可的預期輸出」保存成可比對基準。
  4. task-decomposer.js：把大型需求切成可序列執行的原子任務卡。
  5. harness-health-report.js：用固定報表看目前哪些 Guide 與 Sensor 還是空洞。

這五個工具的共同特徵，是它們都在把抽象知識翻譯成可重複執行的流程。對 3KProject 來說，只要規則能執行，Agent 才會真正受控；只要結果能量測，我才能跟團隊討論提升，而不是只討論感覺。

實施順序：先補便宜、穩定、每天都會跑的感測器

我在 3KProject 排這個導入順序時，看的是哪一些東西最便宜、最穩定、而且每天都會跑。最有效的策略，是先做低成本高頻率檢查，再補行為與架構層的守衛，最後才處理昂貴的語意審查。

導入優先順序：先穩住 Feedback 主鏈，再擴張語意層與治理層 P0 型別檢查整合 基礎 Lint 與編碼檢查 先消滅最常見、最便宜可攔的錯誤 立即提升穩定性 P1 匯入邊界檢查 任務卡原子化工具 讓架構原則與任務切片可被機器執行 降低長期耦合 P2 Approved fixtures Health report 把行為驗證與治理覆蓋率制度化 建立可持續回歸 P3 AI 語意審查 高成本 inferential sensors 留在高價值節點，而不是每次都跑 控制成本與延遲
圖 5：順序錯了，團隊很容易花很多成本做昂貴審查，卻仍然沒補上每天都會踩到的基礎錯誤。

用一句話總結我在 3KProject 的優先順序：先讓機器做它擅長的確定性判定，再讓模型做它擅長的新內容生成與語意理解。

最後的判斷準則

回到 3KProject，我現在的判斷準則很簡單：如果某個品質判斷可以由腳本、型別系統、Schema、快照或 fixtures 決定，就不要把它留給 LLM 猜。模型最有價值的地方，是生成新東西、讀懂曖昧需求、補齊缺漏脈絡；而不是反覆充當一個昂貴又不穩定的 if/else 引擎。

適合交給模型

需求拆解、程式碼撰寫、重構建議、文件整合、語意差異判讀與高階設計取捨。

適合交給工具

型別正確性、命名規則、模組邊界、資料格式、固定輸出比對與編碼完整性。

在 3KProject，我現在的原則就是：把讓 LLM 做的「判斷」盡量改成腳本，把 LLM 留給真正需要理解與創造的地方。