eval-harness

eval-harness 技能概覽

eval-harness 是做什麼的

eval-harness 技能是一套用於 Claude Code 工作階段與以評測驅動開發的正式評估框架。它能幫你先定義在發佈前什麼叫做「好」，再實際衡量 agent、prompt 或工作流程是否真的達到那個標準。

誰適合使用它

如果你需要為 AI 輔助開發、prompt 變更或 agent 行為建立可重複檢查機制，就很適合使用 eval-harness 技能。它特別適合用來比較不同模型版本、追蹤 regression，或把模糊的任務期待轉成可通過／失敗的判準。

為什麼這很重要

eval-harness for Model Evaluation 的核心價值在於可靠性：與其憑感覺判斷結果，不如撰寫 eval 來揭露行為何時改變。這會讓你更容易除錯 agent 表現、比較不同執行結果，並避免發佈會悄悄拉低品質的 prompt 更新。

什麼情況下最適合

當任務能被表述為可觀察的成功條件、輸出結構，或有檢查點的行為時，eval-harness 最能發揮作用。若是開放式的創意工作，除非你仍然能定義可衡量的驗收條件，否則它的幫助就會比較有限。

如何使用 eval-harness 技能

安裝並啟用

進行 eval-harness install 時，先在你的 Claude Code 環境中走完 repo 提供的技能安裝流程，接著直接打開技能檔。這個技能位於 skills/eval-harness/SKILL.md，而且應該先讀這個檔案，因為它定義了何時啟用框架，以及 eval 應該怎麼組織。

先建立一個技能能評估的 prompt

要有好的 eval-harness usage，不要一開始就寫「測試我的 agent」。先從具體目標開始，例如：agent 必須完成什麼任務、什麼算成功、什麼算失敗，以及你是在檢查能力還是 regression。比較好的輸入像是：「評估 agent 能否在不破壞驗證的情況下更新 React form，並要求三個明確的成功條件。」這樣 harness 才有可以量化的內容。

先讀對的檔案

如果你要在自己的工作流程中採用 eval-harness guide 的方式，請先讀 SKILL.md，再查看任何描述評估風格、評分邏輯或輸出慣例的 repo 註記。這個 repo 沒有 helper scripts 或額外的支援資料夾，所以 skill 檔本身就是唯一的權威來源。

在實際工作流程中使用它

一個好的流程是：先定義行為，再為 happy path 寫一個 eval，接著針對已知失敗點加上一個 regression eval，最後執行 harness 並調整判準。這樣可以讓 eval 的規模保持在容易除錯的範圍，也能降低寫出過於寬泛、難以解讀的測試的機率。

eval-harness 技能 FAQ

eval-harness 只適用於 Claude Code 嗎？

不是。這個技能是圍繞 Claude Code 工作階段撰寫的，但底層方法在任何需要結構化 agent 評估的情境都適用。如果你的技術棧使用不同工具，仍然可以沿用這套 eval 格式與評分邏輯。

eval-harness 跟一般 prompt 一樣嗎？

不一樣。一般 prompt 是要一個答案；eval-harness 要的是一種可重複使用的答案判定方式。當你需要的是跨版本的一致性，而不只是單次回應漂亮，這個差異就很關鍵。

這對初學者友善嗎？

是，只要你能清楚描述任務。真正比較難的不是語法，而是寫出好的成功條件。初學者通常會在從單一、簡單的 capability eval 開始時表現最好，而不是一開始就試著一次建模整個工作流程。

什麼情況下不該用？

如果工作高度主觀、輸出無法一致檢查，或你只是需要一次性的答案，就先不要用 eval-harness。當可靠性、regression 追蹤，或模型比較才是實際目標時，它的效果最強。

如何改進 eval-harness 技能

讓判準可觀察

品質提升最大的地方，是把主觀意見轉成可檢查項。把「讓它變好一點」改成像「保留既有 API shape」、「回傳有效 JSON」或「通過三個 regression case」這類條件。判準越可觀察，eval-harness 就越容易執行，也越值得信任。

把能力與 regression 分開

如果你把新功能檢查與既有行為檢查混在一起，失敗時就會很難解讀。請讓 capability eval 專注在 Claude 能不能完成新能力，讓 regression eval 專注在既有基準是否仍然成立。

給 harness 真正的邊界案例

更強的 eval 不只包含 happy path，也要包含失敗模式。加入棘手輸入、不完整的上下文，或有歧義的指示，讓 eval-harness skill 能看出 agent 是真的穩定，還是只是剛好在乾淨案例上表現不錯。

第一次跑完後要迭代

把第一次執行當作校準，而不是證明。如果結果不夠清楚，就收緊成功條件、加入 baseline，或把一個過於寬泛的 eval 拆成更小的檢查。這通常是提升 eval-harness usage、並得到可採取行動結果的最快方式。