error-handling-patterns

error-handling-patterns skill 概览

error-handling-patterns skill 是做什么的

error-handling-patterns skill 的作用，不只是帮 agent 给代码补几个 try/catch，而是帮助你设计更合理的失败处理机制。它重点关注的是一系列实际决策：什么时候该用 exceptions，什么时候更适合 Result 风格返回；如何区分可恢复与不可恢复的失败；如何在错误传递时保留上下文；以及在部分故障或依赖异常时，系统该如何优雅降级。

谁适合使用这个 skill

这个 skill 特别适合开发者、技术负责人，以及重视 Reliability 的团队，尤其是正在开发 API、服务、异步流程、系统集成或分布式系统的场景。如果你要解决的不是某个零散报错，而是希望整个代码库拥有一致的错误语义和处理方式，它会更有价值。

它要解决的核心问题

大多数用户并不需要一堂“错误处理理论课”，真正需要的是回答这些实际问题：哪些情况应该快速失败？哪些值得重试？哪些错误应该以结构化形式返回给调用方？哪些应该记录日志、暴露给外部、包装后继续抛出，或干脆抑制？当这些决策会直接影响可维护性、排障效率或系统可用性时，error-handling-patterns skill 的价值就会非常明显。

它和普通提示词有什么不同

普通 prompt 往往只会给出比较浅层的建议，比如“加重试”“用 try/catch 包一下”。这个 skill 更偏决策框架。它会围绕错误处理理念、错误分类以及语言特定模式来组织建议，因此更适合做架构层和实现层的指导，帮助你真正提升 Reliability，而不只是修补表面问题。

安装前需要了解什么

这是一个以文档为核心的 skill，只有一个 SKILL.md 文件，没有辅助脚本、参考资源或示例资产。好处是接入简单、上手成本低；但另一方面，输出质量会更依赖你的 prompt 是否具体，以及你是否提供了足够的代码和上下文。

如何使用 error-handling-patterns skill

error-handling-patterns 的安装方式

可以通过下面的命令从仓库安装：

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

如果你的环境已经会从该仓库同步 skills，那你可能只需要在 agent 工作流里按名称启用或调用 error-handling-patterns 即可。

安装后先看什么

建议先读：

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

由于这个 skill 主要就是一份核心文档，所以不需要走很长的 onboarding 流程。优先阅读 “When to Use This Skill” 和 “Core Concepts” 两部分，再根据你的技术栈跳到对应的语言相关章节。

error-handling-patterns skill 需要什么输入，效果才会好

error-handling-patterns skill 在你提供以下信息时效果最好：

• 使用的语言和框架
• 运行时类型：CLI、API、worker、UI、service、library
• 你关心的失败模式
• 调用方是面向用户、内部系统，还是 machine-to-machine
• 现有约束，例如向后兼容、延迟预算或日志规范

弱输入示例：

"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. 如果能提供源码，就明确要求代码级建议。

示例：

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 大体适合三种使用模式：

• 设计模式： 在实现之前先定义错误契约和恢复行为
• 重构模式： 当代码库里的 exceptions、返回值或日志方式不一致时进行梳理
• 事故复盘模式： 在生产故障之后，围绕真实出现的失败类型重设计处理方式

对大多数团队来说，价值最高的一条工作流通常是：先分类错误 -> 再选错误传播模型 -> 定义面向调用方的行为 -> 补齐可观测性 -> 最后测试失败路径。

error-handling-patterns 最强的地方在哪里

这个 skill 在以下问题上最有优势：

• Exceptions 与 Result types 的取舍
• 可恢复与不可恢复错误的划分
• Retry 与 circuit breaker 的思路
• 异步与并发场景下的失败处理
• 提升调试效率和运维上下文
• Reliability 敏感系统中的优雅降级

相比生成某个框架的样板代码，它更擅长帮你做策略和模式层面的决策。

用仓库阅读路径更快评估是否值得采用

如果你正在判断是否要采用 error-handling-patterns skill，建议按这个顺序快速浏览仓库：

1. SKILL.md 的标题列表
2. “When to Use This Skill”
3. “Core Concepts”
4. 各语言的模式章节
5. 任何涉及 retries、propagation 和 graceful failure 的示例

这样可以很快判断它是否适配你的技术栈，以及它提供的结构化指导是否明显优于普通 prompt。

提升输出质量的实用技巧

建议在提问时要求这个 skill 明确说明权衡。好的 prompt 通常会包含这类问题：

• 哪些失败属于预期中的业务结果，哪些才是真正的异常？
• 重试应该放在哪一层，才能避免重复工作？
• 在重新抛出或返回错误前，应该附加哪些上下文？
• 哪些错误应该对用户可见，哪些需要脱敏，哪些只能内部可见？
• 什么时候系统应该降级，而不是直接中止？

这些细节通常比一句“给我最佳实践”更关键。

限制与不适用场景

不要指望这个 skill 取代深入的框架文档、SRE playbook 或语言运行时参考资料。它不附带可执行工具，也没有 lint 规则。如果你只是想知道某个语言结构的语法怎么写，用一个更有针对性的 prompt 可能更快。error-handling-patterns usage 最有价值的场景，是你真正要解决的是失败条件下的设计一致性和 Reliability，而不是单纯的语法问题。

error-handling-patterns skill 常见问题

error-handling-patterns 适合新手吗？

适合，前提是你已经理解基础控制流，并且希望用一种更结构化的方式处理失败场景。但如果你是第一次接触编程错误，它未必是最好的入门材料，因为它重点讨论的是设计取舍，而不只是语法层面的错误处理。

什么时候应该用它，而不是普通 coding prompt？

当“失败行为”本身就是核心问题时，就该用 error-handling-patterns。如果你关心的是 API 契约、重试策略、降级模式，或者故障场景下的可观测性，它比一句泛泛的“加上错误处理”更能给出正确的分析框架。

这个 skill 支持多语言吗？

支持。源文档明确覆盖了跨语言通用的理念，比如 exceptions、Result types 和错误分类，然后再延伸到各语言特定模式。因此它对混合技术栈团队也有帮助，不过你仍然需要在 prompt 里明确说明自己使用的语言。

error-handling-patterns 适合 Reliability 团队吗？

适合。error-handling-patterns for Reliability 的匹配度很高，因为它能帮助团队定义系统在依赖失败、局部故障和异步异常下应如何表现。对于需要统一运维侧和调用侧行为的服务负责人来说，尤其有参考价值。

这个 skill 的边界在哪里？

这个 skill 主要解决的是失败处理相关的决策和实现模式问题。它不会提供测试 harness、生产监控看板，也不负责仓库级自动化。最终建议是否可落地，仍然需要你结合自己的架构和历史事故来验证。

什么情况下它不太适合？

如果你的需求非常机械化，比如只想修一个编译错误，或者只想知道某个框架 exception type 的准确语法，那就没必要用它。如果真正缺的是业务规则，而不是错误处理结构本身，它的帮助也会有限。

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

给 skill 提供失败地图，而不只是代码

想得到更好的结果，最好先把失败版图说清楚，例如：

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

这样这个 skill 才能为不同错误推荐不同处理路径，而不是把同一种模式硬套到所有失败上。

把调用方体验和运维体验分开说

常见问题之一，是用户只说“给我更好的错误”，却没有说明“对谁更好”。你需要告诉 skill：终端用户应该看到什么，API 客户端应该收到什么，operators 在 logs 或 traces 里需要什么。这会直接提升它在脱敏、包装和上下文传播上的建议质量。

明确要求给出错误分类体系

如果第一轮回答太泛，可以直接让 error-handling-patterns skill 输出：

• error classes 或 categories
• recoverable vs unrecoverable 的边界
• retryable vs non-retryable 的判断规则
• internal errors 到 external responses 的映射方式

这通常能把空泛建议推进到可实现层面。

提供真正会影响模式选择的约束

当你有严格的延迟 SLO、高成本重试、幂等性风险，或者必须保持向后兼容的 API 契约时，适用模式会完全不同。把这些约束直接说出来，往往就能决定到底该返回 Result、抛出 exception、直接短路、排队稍后处理，还是优雅降级。

第一版之后继续迭代请求

很多时候，第二轮 refinement 才是高质量结果的开始。一个强有力的二次请求可以像这样：

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 之后，可以检查建议是否满足以下几点：

• 区分了预期失败和程序 bug
• 避免了 retry storm
• 保留了足够的调试上下文
• 向调用方暴露的是安全、稳定的错误
• 在适用场景下支持优雅降级

如果没有做到，不要只抽象地要求“再详细一点”，而应补充具体失败案例和期望结果，再让它重新给出建议。