error-handling-patterns

Visão geral da skill error-handling-patterns

O que a skill error-handling-patterns faz

A skill error-handling-patterns ajuda um agente a projetar um comportamento melhor diante de falhas, e não apenas a remendar blocos de try/catch. Ela foca em decisões práticas, como quando usar exceções versus retornos no estilo Result, como classificar falhas recuperáveis e irrecuperáveis, como propagar contexto e como degradar o serviço com elegância durante indisponibilidades parciais.

Para quem esta skill é indicada

Esta skill é mais indicada para desenvolvedores, tech leads e equipes com foco em Reliability que trabalham com APIs, serviços, fluxos assíncronos, integrações ou sistemas distribuídos. Ela é especialmente útil quando você precisa de semântica de erro consistente em toda a base de código, e não de correções pontuais.

Trabalho que ela resolve

A maioria dos usuários não precisa de uma aula teórica sobre erros. Precisa de ajuda para responder perguntas como: o que deve falhar rápido? O que deve ser tentado novamente? O que deve retornar erros estruturados para quem chama? O que deve ser registrado em log, exposto, encapsulado ou suprimido? A skill error-handling-patterns ganha valor quando essas decisões afetam manutenibilidade, velocidade de depuração ou disponibilidade.

O que a diferencia de um prompt genérico

Um prompt genérico costuma gerar conselhos superficiais, como "adicione retries" ou "use try/catch". Esta skill error-handling-patterns é mais orientada à tomada de decisão. Ela organiza o tratamento de erros em torno de filosofia, categorias de erro e padrões específicos por linguagem, o que a torna mais útil para orientação de arquitetura e implementação com foco em Reliability.

O que saber antes de instalar

Esta é uma skill orientada por documentação, com um único arquivo SKILL.md e sem scripts auxiliares, referências ou exemplos prontos. Isso simplifica a adoção, mas também significa que a qualidade da saída depende bastante da especificidade do seu prompt e do contexto de código que você fornecer.

Como usar a skill error-handling-patterns

Opções de instalação da error-handling-patterns

Instale a partir do repositório com:

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

Se o seu ambiente já sincroniza skills desse repositório, talvez você só precise habilitar ou invocar error-handling-patterns pelo nome no fluxo do seu agente.

O que ler primeiro depois da instalação

Comece por:

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

Como esta skill é entregue como um documento principal, não existe uma trilha longa de onboarding. Leia primeiro as seções "When to Use This Skill" e "Core Concepts" e depois vá direto para as partes específicas da linguagem relevantes para a sua stack.

Que tipo de entrada a skill precisa para funcionar bem

A skill error-handling-patterns funciona melhor quando você informa:

• linguagem e framework
• tipo de runtime: CLI, API, worker, UI, service, library
• modos de falha com que você se preocupa
• se o chamador é voltado ao usuário, interno ou machine-to-machine
• restrições existentes, como compatibilidade retroativa, orçamento de latência ou padrões de logging

Entrada fraca: "Improve error handling in this service."

Entrada forte: "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."

Como transformar um objetivo vago em um prompt forte para error-handling-patterns

Use uma estrutura de prompt como esta:

1. Informe o sistema e a linguagem.
2. Nomeie os cenários de falha.
3. Descreva o comportamento desejado para chamadores e operadores.
4. Peça padrões concretos, não princípios genéricos.
5. Solicite recomendações em nível de código se você puder compartilhar o código-fonte.

Exemplo:

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.

Melhores fluxos de trabalho para uso prático

Use esta skill error-handling-patterns em um de três modos:

• Modo de design: antes da implementação, para definir contratos de erro e comportamento de recuperação
• Modo de refatoração: quando a base de código tem exceções, valores de retorno ou logs inconsistentes
• Modo de incidente: após falhas em produção, para redesenhar o tratamento com base nas classes reais de falha

Para a maioria das equipes, o fluxo de maior valor é: classificar erros -> escolher o modelo de propagação -> definir o comportamento voltado a quem chama -> adicionar observabilidade -> testar caminhos de falha.

Onde esta skill é mais forte

A skill error-handling-patterns é mais forte quando você precisa de orientação sobre:

• exceções versus tipos Result
• erros recuperáveis versus irrecuperáveis
• estratégia de retry e circuit breaker
• tratamento de falhas assíncronas e concorrentes
• melhor contexto para depuração e operação
• degradação graciosa em sistemas sensíveis à confiabilidade

Ela é mais útil para decisões de política e padrão do que para gerar boilerplate específico de framework.

Caminho de leitura do repositório para avaliar mais rápido

Se você está decidindo se deve adotar a skill error-handling-patterns, faça uma leitura rápida do repositório nesta ordem:

1. lista de headings do SKILL.md
2. "When to Use This Skill"
3. "Core Concepts"
4. seções sobre padrões específicos por linguagem
5. quaisquer exemplos que mostrem retries, propagação e falha graciosa

Isso permite avaliar rapidamente se ela combina com a sua stack e se oferece estrutura suficiente além de um prompt comum.

Dicas práticas que melhoram a qualidade da saída

Peça à skill error-handling-patterns para explicitar os trade-offs. Bons prompts incluem perguntas como:

• Quais falhas são resultados de negócio esperados versus exceções de fato?
• Onde os retries devem ficar para evitar trabalho duplicado?
• Que contexto deve ser anexado antes de relançar ou retornar?
• Quais erros devem ser visíveis ao usuário, sanitizados ou apenas internos?
• Quando o sistema deve degradar em vez de abortar?

Esses detalhes normalmente importam mais do que simplesmente pedir "best practices".

Restrições e casos em que não é a escolha ideal

Não espere que esta skill substitua documentação profunda de framework, playbooks de SRE ou referências da runtime da linguagem. Ela não inclui tooling executável nem regras de lint. Se você só precisa de ajuda de sintaxe para uma construção específica de linguagem, um prompt direcionado pode ser mais rápido. O caso de uso de error-handling-patterns é mais forte quando o problema real é consistência de design e Reliability sob falha.

FAQ da skill error-handling-patterns

error-handling-patterns é boa para iniciantes?

Sim, se você já entende fluxo de controle básico e quer um guia estruturado para tratamento de falhas. Ela é menos adequada como primeira introdução a erros de programação, porque foca em escolhas de design, e não apenas em sintaxe.

Quando devo usar isso em vez de um prompt normal de código?

Use error-handling-patterns quando o comportamento diante de falhas for o problema central. Se você se importa com contratos de API, retries, modos degradados ou observabilidade sob falha, esta skill oferece um enquadramento melhor do que um pedido genérico como "add error handling".

A skill oferece suporte a várias linguagens?

Sim. A fonte cobre explicitamente filosofias entre linguagens, como exceções, tipos Result e categorias de erro, e depois passa para padrões específicos por linguagem. Isso a torna útil para equipes com stack mista, embora você ainda precise informar a linguagem no prompt.

error-handling-patterns é para equipes de Reliability?

Sim. A aderência de error-handling-patterns para Reliability é forte porque ela ajuda a definir como os sistemas se comportam durante falhas de dependência, indisponibilidades parciais e falhas assíncronas. É especialmente relevante para donos de serviços que precisam de comportamento consistente tanto para operadores quanto para quem consome o sistema.

Quais são os limites da skill?

Esta skill ajuda na tomada de decisão e nos padrões de implementação em torno de falhas. Ela não fornece harnesses de teste, dashboards de produção nem automação específica de repositório. Você ainda precisa validar as recomendações em relação à sua arquitetura e ao histórico de incidentes.

Quando esta skill não é uma boa escolha?

Evite esta skill se sua necessidade for puramente mecânica, como corrigir um único erro de compilação ou aprender a sintaxe exata de um tipo de exceção de um framework. Ela também é menos indicada quando o problema real é falta de regras de domínio, e não uma estrutura ruim de tratamento de erros.

Como melhorar a skill error-handling-patterns

Dê à skill error-handling-patterns um mapa de falhas, não apenas código

Você terá resultados melhores ao nomear o panorama de falhas:

• erros de validação
• timeouts de dependências
• rate limits
• escritas parciais
• requisições duplicadas
• falhas de desserialização
• bugs de programação

Isso permite que a skill recomende caminhos de tratamento diferentes, em vez de forçar um único padrão para todo erro.

Separe a experiência de quem chama da experiência de quem opera

Um modo de falha comum é pedir "erros melhores" sem dizer para quem. Informe à skill o que os usuários finais devem ver, o que clientes de API devem receber e o que operadores precisam em logs ou traces. Isso gera recomendações mais úteis sobre sanitização, wrapping e propagação de contexto.

Peça uma taxonomia de erros explícita

Se a primeira resposta parecer genérica, peça à skill error-handling-patterns para produzir:

• classes ou categorias de erro
• fronteiras entre recuperável e irrecuperável
• regras sobre o que permite retry e o que não permite
• mapeamento de erros internos para respostas externas

Isso normalmente transforma conselhos vagos em orientação pronta para implementação.

Forneça restrições reais que mudam a escolha do padrão

Os padrões mudam quando você tem SLOs de latência rígidos, retries caros, riscos de idempotência ou contratos de API com compatibilidade retroativa. Mencione essas restrições diretamente. Muitas vezes, elas determinam se você deve retornar um Result, lançar uma exceção, encurtar o fluxo, enfileirar para depois ou degradar de forma graciosa.

Peça uma iteração depois do primeiro rascunho

Uma boa segunda rodada costuma se parecer com isto:

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.

Iteração importa porque o melhor padrão depende de escala, público e consequências operacionais.

Prompts fracos comuns para evitar

Evite prompts como:

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

Esses pedidos escondem os critérios de decisão. A skill é muito mais eficaz quando recebe a tarefa de escolher entre trade-offs, e não apenas de decorar o código com construções defensivas.

Como validar a saída

Depois de usar o guia error-handling-patterns, verifique se a recomendação:

• distingue falhas esperadas de bugs
• evita tempestades de retry
• preserva contexto suficiente para depuração
• expõe erros seguros e estáveis para quem chama
• oferece suporte à degradação graciosa quando apropriado

Se não, refine o prompt com casos concretos de falha e resultados desejados, em vez de pedir mais detalhes de forma abstrata.