error-handling-patterns

error-handling-patterns skill 概覽

error-handling-patterns skill 的作用

error-handling-patterns skill 幫助代理設計更成熟的失敗處理行為，而不只是補幾個 try/catch 區塊。它聚焦在實務上的關鍵判斷，例如什麼時候該用 exceptions、什麼時候該用 Result-style returns、如何區分可恢復與不可恢復的失敗、如何傳遞足夠的上下文，以及在部分服務中斷時如何優雅降級。

誰適合使用這個 skill

這個 skill 特別適合開發者、技術主管，以及重視 Reliability 的團隊，用在 APIs、services、async workflows、integrations 或 distributed systems 上尤其有價值。當你要解決的不是單點修補，而是希望整個程式碼庫都採用一致的錯誤語意時，它會特別實用。

要完成的工作

多數使用者不是需要上一堂錯誤處理理論課，而是想快速回答這些問題：哪些情況應該 fail fast？哪些應該 retry？哪些錯誤要以結構化形式回傳給呼叫端？哪些該記錄、暴露、包裝，或刻意抑制？當這些決策會影響可維護性、除錯速度或 uptime 時，error-handling-patterns skill 的價值就很明顯。

它和一般 prompt 有什麼不同

一般 prompt 很常只給出表層建議，例如「加上 retries」或「用 try/catch」。這個 skill 更偏向決策導向。它會從處理哲學、錯誤分類與語言特定模式來組織 error handling，因此更適合拿來做架構與實作層面的指引，支撐整體 Reliability。

安裝前要先知道什麼

這是一個以文件為核心的 skill，只有一個 SKILL.md 檔案，沒有 helper scripts、references 或 example assets。好處是導入門檻低、安裝簡單；但也代表輸出品質很依賴你的 prompt 是否夠具體，以及你提供的程式碼與上下文是否完整。

如何使用 error-handling-patterns skill

error-handling-patterns 的安裝方式

可透過以下指令從 repository 安裝：

npx skills add https://github.com/wshobson/agents --skill error-handling-patterns

如果你的環境已經會自動從該 repo 同步 skills，那你可能只需要在 agent workflow 中啟用，或直接用名稱呼叫 error-handling-patterns。

安裝後第一個該讀的內容

建議先看：

• plugins/developer-essentials/skills/error-handling-patterns/SKILL.md

由於這個 skill 主要就是一份核心文件，所以不需要走很長的 onboarding 流程。先讀 "When to Use This Skill" 和 "Core Concepts"，再跳到與你技術棧相符的語言專屬段落即可。

這個 skill 需要哪些輸入才會發揮得好

error-handling-patterns skill 在你提供以下資訊時，通常表現最好：

• 使用的語言與 framework
• 執行型態：CLI、API、worker、UI、service、library
• 你關心的 failure modes
• 呼叫端是 user-facing、internal，還是 machine-to-machine
• 既有約束，例如 backward compatibility、latency budgets 或 logging standards

弱輸入範例："Improve error handling in this service."

強輸入範例："Review this Go HTTP service. Separate validation errors from dependency failures, recommend retry boundaries, define what should be returned to clients vs logged internally, and suggest error wrapping patterns that preserve root cause."

把模糊目標改寫成強 prompt

你可以用這種結構來寫 prompt：

1. 先說明系統與語言。
2. 指出失敗情境。
3. 描述你希望呼叫端與維運人員看到的行為。
4. 要求具體模式，而不是泛泛原則。
5. 如果能提供原始碼，就要求 code-level recommendations。

範例：

Use the error-handling-patterns skill for a Python background worker that calls a rate-limited API and writes to Postgres. I need recommendations for transient vs permanent error handling, retry policy boundaries, idempotency concerns, logging fields, and what errors should stop the job versus be skipped and reported.

適合實務使用的 error-handling-patterns 工作流程

你可以把這個 skill 用在三種模式：

• Design mode： 在實作前先定義 error contracts 與 recovery behavior
• Refactor mode： 當程式碼庫中的 exceptions、return values 或 logging 風格不一致時
• Incident mode： 線上出事之後，根據實際 failure classes 重新設計處理方式

對大多數團隊來說，最有價值的 workflow 通常是：先分類錯誤 -> 再選擇 propagation model -> 定義 caller-facing behavior -> 補上 observability -> 測試 failure paths。

error-handling-patterns skill 最擅長的地方

這個 skill 最強的場景包括：

• Exceptions 與 Result types 的取捨
• 可恢復與不可恢復錯誤的區分
• Retry 與 circuit breaker 的思考方式
• Async 與 concurrent 失敗處理
• 提升除錯品質與 operator context
• 在重視 Reliability 的系統中做 graceful degradation

相較之下，它更適合協助你制定 policy 與 pattern 決策，而不是單純產生 framework-specific boilerplate。

更快評估是否採用的 repository 閱讀路徑

如果你正在判斷是否要採用 error-handling-patterns skill，建議用這個順序快速瀏覽 repository：

1. SKILL.md 的 heading list
2. "When to Use This Skill"
3. "Core Concepts"
4. 語言特定模式的各段落
5. 任何展示 retries、propagation、graceful failure 的範例

這樣能很快看出它是否符合你的技術棧，以及它是否真的比一般 prompt 更有結構。

能提升輸出品質的實用技巧

請要求 skill 把 tradeoffs 說清楚。好的 prompts 會包含這類問題：

• 哪些失敗是可預期的業務結果，哪些才是真正的 exceptions？
• retries 應該放在哪一層，才能避免重複執行工作？
• 在 rethrow 或 return 之前，應該附帶哪些上下文？
• 哪些錯誤應該讓使用者看見、哪些要清洗、哪些只能內部可見？
• 什麼情況下系統應該降級，而不是直接中止？

這些細節通常比單純要求「best practices」更重要。

限制與不適用情境

不要期待這個 skill 可以取代深入的 framework 文件、SRE playbooks 或語言 runtime references。它不提供可直接執行的 tooling，也沒有 lint rules。如果你只是想查一個語言結構的語法，直接下精準 prompt 可能更快。error-handling-patterns usage 最有價值的情境，是你真正要解的是失敗下的設計一致性，以及 Reliability 表現。

error-handling-patterns skill 常見問題

error-handling-patterns 適合初學者嗎？

可以，但前提是你已經理解基本控制流程，並且希望有一個結構化的方法來處理失敗。若你是第一次接觸程式中的錯誤概念，它就沒那麼適合，因為它重點在設計選擇，不只是語法教學。

什麼時候該用它，而不是一般 coding prompt？

當失敗行為本身就是核心問題時，就該用 error-handling-patterns。如果你在意 API contracts、retries、degraded modes，或失敗情境下的 observability，這個 skill 會比泛泛的「加上 error handling」更能提供有效的框架。

這個 skill 支援多種語言嗎？

支援。原始內容明確涵蓋跨語言的核心觀念，例如 exceptions、Result types 與 error categories，接著再進入語言特定模式。因此它很適合混合技術棧的團隊，但你仍然需要在 prompt 中明確指定語言。

error-handling-patterns 適合 Reliability 團隊嗎？

適合。error-handling-patterns for Reliability 的契合度很高，因為它能幫你定義系統在 dependency failures、partial outages 與 asynchronous faults 下應該怎麼表現。對需要統一 operator-facing 與 caller-facing 行為的 service owners 來說，尤其有幫助。

這個 skill 的邊界在哪裡？

這個 skill 擅長的是失敗處理相關的決策與實作模式。它不提供 test harnesses、production dashboards，也沒有 repository-specific automation。你仍然需要依照自己的架構與 incident history，驗證它給出的建議是否可行。

什麼情況下這個 skill 不太適合？

如果你的需求很機械式，例如只想修一個 compiler error，或只想知道某個 framework exception type 的精確語法，那就不必用它。當真正的問題是缺少 domain rules，而不是 error handling 結構差時，它也不是最理想的選擇。

如何改進 error-handling-patterns skill 的使用效果

提供失敗地圖，而不只是程式碼

如果你能把 failure landscape 說清楚，結果通常會更好，例如：

• validation errors
• dependency timeouts
• rate limits
• partial writes
• duplicate requests
• deserialization failures
• programmer bugs

這樣 skill 才能針對不同錯誤推薦不同處理路徑，而不是把同一套模式硬套到所有 error 上。

把呼叫端體驗和維運端體驗分開說明

常見失敗之一，就是只說想要「更好的 errors」，卻沒說是要對誰更好。請明確告訴 skill：終端使用者應該看到什麼、API clients 應該收到什麼、operators 在 logs 或 traces 中需要什麼資訊。這樣它才能給出更實用的 sanitization、wrapping 與 context propagation 建議。

要求明確的 error taxonomy

如果第一輪回答太泛，可以要求 error-handling-patterns skill 直接產出：

• error classes 或 categories
• recoverable 與 unrecoverable 的邊界
• retryable 與 non-retryable 的規則
• internal errors 到 external responses 的對應方式

這通常能把模糊建議轉成可直接落地的實作指引。

提供會改變模式選擇的真實限制

當你有嚴格的 latency SLOs、昂貴的 retries、idempotency 風險，或 backward-compatible API contracts 時，適合的模式會完全不同。請直接把這些限制講清楚，因為它們往往決定你應該回傳 Result、拋出 exception、提前 short-circuit、排入佇列稍後處理，還是選擇 graceful degradation。

第一版之後記得要求迭代

很多時候，第二輪調整才會真正變得夠強。例如：

Revise the recommendation for a high-throughput service. Minimize allocation-heavy exception paths, preserve root cause for debugging, and propose a small set of standard error types the whole team can adopt.

需要迭代，是因為最合適的模式會受到規模、受眾與營運後果影響。

應避免的常見弱 prompt

避免這種 prompt：

• "Handle errors better"
• "Add retries everywhere"
• "Make it production ready"

這些說法把決策標準都藏起來了。這個 skill 在面對需要權衡取捨的問題時會更有效，而不是單純替程式碼加上防禦性結構。

如何驗證輸出結果

使用完 error-handling-patterns guide 之後，請檢查建議是否：

• 有區分可預期失敗與真正的 bugs
• 能避免 retry storms
• 保留足夠上下文以利除錯
• 對呼叫端暴露安全且穩定的錯誤
• 在適合時支援 graceful degradation

如果沒有，請用更具體的 failure cases 與預期結果來細化 prompt，而不是抽象地要求「再多給一些細節」。