Communitygithub.com

zehuichan/vibe-harness

在設計或審查失敗、復原、重試、背景任務以及使用者可見的錯誤報告時,套用錯誤處理原則。

vibe-harness 是什麼?

這個技能旨在幫助開發者建立一套嚴謹且具一致性的錯誤處理策略,將其應用於程式碼設計與審查流程中。它強調使用型別化、結構化的方式來定義預期失敗,避免依賴錯誤訊息解析進行決策,並確保每一個失敗都有明確的擁有者、復原策略以及安全保證。該技能支援多種平台與 AI 代理(如 Claude Code、Cursor、Codex),通過提供清晰的指導方針(如「捕獲、復原或停止」的決策樹),協助工程師在背景任務、重試邏輯以及使用者錯誤報告中做出正確的權衡。其實踐基礎來自經典軟體工程文獻(Meyer 的契約與不變量、Sutter 的異常安全保證、Armstrong 的隔離與監督),讓開發者能夠設計出更具彈性與可觀察性的系統。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zehuichan/vibe-harness/tree/HEAD/skills/error-handling

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

錯誤處理

定義失敗、其擁有者,以及失敗後仍保持安全的項目。此為指導方針,非檢查清單。

型別化、結構化的失敗

預期的失敗需要宣告的型別、穩定的判別式,以及與處理相關的細節。重複使用專案的錯誤慣例,保留原因鏈,並將機器識別資訊與顯示文字分開。絕不要透過解析訊息來進行處理路由。非預期的缺陷(例如窮舉檢查失敗)可以保持為單純的錯誤;但封裝絕對不能將其轉變為成功。

捕獲、復原或停止

對於每個失敗,定義處理與報告的擁有者、封裝方式,以及在擁有 API 文件中的保證:哪些不變量仍然有效,副作用是缺席、部分、已提交或未知,以及誰負責清理。背景工作也需承擔這些義務。

捕獲限制了異常的傳播,而非副作用。只有受影響狀態的擁有者才能建立安全的繼續執行。否則,應停止依賴的任務、丟棄無效的狀態或實例,或升級問題。僅記錄日誌並非復原。重試需要安全的重複執行、取消機制以及明確的擁有者;有限次數的操作需要預算,而持續的監督則需要生命週期的擁有權與可觀察的降級。

在地化、可操作、可見的報告

每份最終報告都需要可讀的摘要、受影響的操作,以及安全的下一步行動。若接收的應用程式存在在地化機制,則透過該機制進行在地化;其他診斷則使用其既有的輸出語言。將敏感的內部細節排除在使用者可見的文字之外。

不可信的狀態或未知的結果,必須透過 UI 或預設啟用、可存取的日誌顯示:報告影響、不確定性、系統做了什麼,以及安全的下一步。持續存在的無效狀態需要持續的可見性。如果在背後沒有相應的保證,絕不能聲稱成功、回滾或安全重試。報告失敗本身需要獨立的備援機制。

驗證最終的狀態與可見的結果,而不僅僅是異常是否被捕獲。

基礎

Meyer,《物件導向軟體建構》(1997):契約與不變量。Sutter,《Exceptional C++》(1999):異常安全保證。Armstrong,〈在軟體錯誤存在的情況下建立可靠的分散式系統〉(https://www.erlang.org/download/armstrong_thesis_2003.pdf)(2003):隔離與監督。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能