harness-writing

harness-writing 技能概覽

harness-writing 技能可幫助你設計 fuzzing harness，將原始位元組轉成對受測系統有意義、且可重現的測試。當你已經有目標函式庫或 API，並且需要的是能真正深入程式碼路徑的 harness，而不是只會吃進輸入再回傳的簡單包裝時，這個技能最實用。若你正在評估是否要把 harness-writing 用於 Code Generation，關鍵問題是：你需要的是結構化的 fuzz target 邏輯，還是只要一個泛泛談 fuzzing 的提示詞。

harness-writing 的用途

當你需要建立新的 fuzz target，或是改善既有 target 的覆蓋率、穩定性或找 bug 能力時，就該使用 harness-writing 技能。它聚焦於實務工作：把 fuzzed bytes 映射成可安全處理的有效呼叫、狀態轉換，以及邊界案例。

為什麼這個技能不同於一般提示詞

一般提示詞可能只會概略描述 fuzzing，但 harness-writing 技能提供的是更緊密的 harness 設計流程：如何解析輸入、如何選擇操作、如何避免非決定性，以及如何讓 crash 保持可重現。這讓它在 Code Generation 任務中特別有用，因為輸出必須能立刻拿來用。

最適合的使用者與專案

這個技能適合資安工程師、fuzzing 實作者、函式庫維護者，以及為 C/C++ 或類似底層目標生成測試基礎設施的 agent。當你在乎覆蓋率、crash 分流，以及 API 層級的正確性時，它特別合適。若你只需要高階的 fuzzing 概念介紹，且不需要撰寫程式碼，它就比較不適合。

如何使用 harness-writing 技能

安裝並打開正確的檔案

執行 harness-writing install 時，先依照 repo 原本的 skills 流程把這個技能加入你的 skills 集合，接著先開啟 SKILL.md。如果你想最快掃過上下文，可以先讀定義 harness 設計、適用時機，以及任何快速參考內容，再開始產生程式碼。在這個 repo 中，SKILL.md 是主要來源；沒有其他 helper scripts 或 reference folders 需要交叉比對。

提供具體目標，不要只給抽象目的

要讓 harness-writing usage 發揮作用，請明確描述你要 fuzz 的 API 或元件、語言，以及輸入面。好的輸入像是：「為一個 C++ parser library 寫 fuzz harness，該 library 暴露 ParseMessage(const uint8_t*, size_t)，而且必須避免 file I/O。」差的輸入像是：「幫我的 app 做 fuzz harness。」這個技能最擅長的情況，是它清楚知道 entry point 應該呼叫什麼，以及哪些行為必須保持 deterministic。

把粗略想法整理成完整提示詞

一個實用的 harness-writing guide 提示詞通常會包含：

• target 名稱與語言
• 如果已知，fuzzing engine 或 framework
• 要測試的公開函式、建構子或 protocol
• 必須禁止的副作用，例如網路存取、檔案系統寫入或全域狀態
• 已知的 edge cases、狀態式行為，或 crash 歷史
• 你希望的是單一操作還是多操作的 harness 邏輯

這些額外結構可以幫助技能選出合適的 harness 形狀，而不是瞎猜你的架構。

產出更好的實際工作流程

先要求它先產出 harness 形狀，再進一步要求修正。比方說，先要一版初稿 harness，接著再加上 determinism、輸入切分，或更深層路徑覆蓋等限制。如果第一版太淺，可以要求它重組解析邏輯、擴大可用操作覆蓋，或減少對預設狀態的假設。對 Code Generation 來說，這種兩段式流程通常比一次塞進過多要求更容易做出好 harness。

harness-writing 技能 FAQ

harness-writing 只適合 fuzzing 專家嗎？

不是。harness-writing 技能可以幫助剛入門、但已經知道目標 API，且希望有結構化 harness 的使用者；不過，當你能清楚描述受測系統時，它的價值最高。如果你連 entry point 都說不出來，也無法說明輸入應該怎麼被消耗，結果通常會弱很多。

harness-writing 和一般程式碼提示詞有什麼不同？

一般提示詞可能也會產生看起來像 harness 的片段，但 harness-writing 是針對讓 fuzzing 程式真正有用的那些問題：determinism、coverage、state handling，以及有效輸入解碼。當目標是做出真正的 fuzz target，而不是示範程式碼時，它比 harness-writing for Code Generation 更合適。

什麼情況下不該用這個技能？

如果你需要的是 fuzzing 概念的廣泛入門、你的專案還沒準備好做自動化的輸入驅動測試，或你的 target 無法透過穩定 API 來驅動，就不適合用它。當主要問題是測試環境建置，而不是 harness 設計時，它也比較幫不上忙。

我應該先讀 repo 裡的什麼？

先讀 SKILL.md，再找說明核心概念與適用時機的章節。由於這個 repository 很精簡，重點在於理解 harness-writing 的邏輯本身，而不是去翻找額外檔案。

如何改進 harness-writing 技能

先把 target 形狀與限制講清楚

品質提升最大的關鍵，是直接點出你要 fuzz 的精確函式、物件或 protocol 邊界。請包含語言、預期輸入型別，以及任何需要在多次呼叫之間保留的狀態。像「為 C++ 的 JSON parser 建構子做 fuzz，但所有測試案例都必須 deterministic 且只在記憶體內執行」這類請求，遠比泛泛地說「幫我 fuzz 一個 parser」有用得多。

要求覆蓋率，而不只是可編譯的 harness

常見失敗模式是：harness 雖然能編譯，卻只碰到一條程式碼路徑。要改進 harness-writing，可以要求它說明 harness 如何觸及多種行為、如何避免無效初始化，以及如何讓 crash 可重現。如果你已經知道哪些分支特別難碰到，請直接點出來，讓 harness 可以圍繞那些區域來設計。

針對無效輸入處理與狀態持續迭代

第一版產出後，檢查 harness 是否過度拒絕輸入、是否在迭代之間洩漏狀態，或是否依賴隱含預設值。如果有，請要求改版，在維持 determinism 的前提下擴大有效操作覆蓋。這一點對 harness-writing usage 尤其重要，特別是面對有多個 constructor、巢狀 parser 或 stateful API 的函式庫。

把第一版當成第二輪提示詞的基礎

要改善 harness-writing skill 的輸出，最好的方式是把第一版 harness 當作基準，接著針對它漏掉的部分再調整：更深的分支、更嚴格的副作用限制，或更清楚的輸入切分。如果你同時分享生成的程式碼與目標 API，下一輪通常就能減少猜測，做出更可靠的 fuzz target。