python-resilience

Visão geral da skill python-resilience

O que a python-resilience faz

A skill python-resilience ajuda você a projetar código Python que falha de forma mais segura quando as dependências são pouco confiáveis. O foco está em padrões práticos de resiliência: retries, exponential backoff, jitter, timeouts, janelas de retry limitadas e wrappers tolerantes a falhas em chamadas externas.

Quem deve instalar esta skill

A python-resilience skill é mais indicada para desenvolvedores, times de plataforma e usuários de agentes que trabalham em serviços conectados a APIs, bancos de dados, filas ou outros sistemas em rede. Ela é especialmente útil quando você precisa de ajuda para gerar código que vá além de “adicionar um retry” e, em vez disso, defina limites sensatos para tratamento de falhas.

O problema real que ela resolve

A maioria dos usuários não precisa de uma página teórica sobre confiabilidade. Precisa de padrões Python prontos para perguntas como:

• “Esse erro deve ser tentado novamente ou falhar imediatamente?”
• “Que estratégia de backoff é segura sob carga?”
• “Onde os timeouts devem ser definidos?”
• “Como evitar retries infinitos e thundering herds?”
• “Que decorator ou helper deve envolver esta chamada externa?”

A python-resilience é valiosa porque explicita essas decisões, em vez de tratar a lógica de retry como um patch de uma linha.

O que a diferencia de um prompt genérico

Um prompt genérico de código pode adicionar retries em tudo ou ignorar a diferença entre falhas transitórias e permanentes. python-resilience for Reliability é mais opinativa: faz retry apenas em falhas retryable, adiciona jitter, limita tentativas e tempo total, e trata as fronteiras externas como o principal lugar para aplicar lógica de resiliência.

O que a fonte realmente cobre

A skill upstream é um único arquivo SKILL.md, mas com conteúdo substancial. Ela se concentra em:

• falhas transitórias vs permanentes
• exponential backoff
• jitter
• retries com limite
• exemplos práticos em Python usando tenacity

Isso a torna leve para inspecionar e rápida de adotar, mas também significa que você deve esperar orientação, não uma biblioteca pronta ou um test harness.

Quando esta skill é uma boa escolha

Use python-resilience quando você estiver:

• chamando APIs de terceiros
• envolvendo interações instáveis com rede ou serviços
• construindo microservices ou workers
• adicionando controles de confiabilidade a utilitários compartilhados de cliente
• lidando com rate limiting, indisponibilidades temporárias ou timeouts intermitentes

Se o seu código for majoritariamente lógica pura em processo, esta skill provavelmente não é a instalação com maior retorno.

Como usar a skill python-resilience

Contexto de instalação da python-resilience

Instale a skill a partir do repositório wshobson/agents:

npx skills add https://github.com/wshobson/agents --skill python-resilience

Depois da instalação, abra primeiro o arquivo da skill:

• plugins/python-development/skills/python-resilience/SKILL.md

Esta área do repositório parece conter apenas o documento da skill, então a adoção é direta: leia a skill e depois aplique os padrões no seu próprio codebase.

Leia este arquivo primeiro

Comece pelo SKILL.md, do início ao fim. As seções de maior valor para revisar primeiro são:

1. When to Use This Skill
2. Core Concepts
3. Quick Start

Essa ordem de leitura dá contexto de adequação, regras de design e formato de implementação antes de você pedir ao modelo para modificar seu código.

Quais informações a skill precisa de você

A qualidade de uso da python-resilience depende muito do contexto que você fornece. Antes de invocar a skill, reúna:

• a função ou fronteira de serviço que será protegida
• o tipo de dependência: HTTP API, DB, queue, cache, filesystem
• as exceções exatas ou sintomas de falha observados
• se as falhas são transitórias ou permanentes
• expectativas de timeout
• restrições de idempotency
• latência máxima aceitável
• orçamento de retry: tentativas ou duração total
• se muitos clientes podem dar retry ao mesmo tempo

Sem essas entradas, o modelo frequentemente produz lógica de retry ampla demais.

Como transformar um objetivo vago em um prompt forte

Prompt fraco:

Add resilience to this Python API client.

Prompt melhor:

Use the python-resilience skill to refactor this Python client method.

Context:
- Dependency: third-party HTTP API
- Library: httpx
- Traffic: moderate, bursty
- Common failures: read timeout, connect timeout, occasional 429 and 503
- Permanent failures: 400, 401, 403 should not be retried
- Idempotency: safe to retry GET requests only
- SLO: fail within 8 seconds total
- Requirement: use bounded retries, exponential backoff with jitter, and clear logging

Task:
- Propose a retry policy
- Implement the wrapper/decorator
- Explain which exceptions and status codes are retryable
- Show where timeout configuration should live

Isso funciona melhor porque fornece à skill os limites de decisão para os quais ela foi projetada.

Peça a política antes do código

Um bom fluxo de trabalho com o python-resilience guide é:

1. pedir a classificação das falhas
2. pedir uma política de retry/timeout
3. revisar os trade-offs
4. só então gerar o código de implementação

Isso evita partir direto para decorators antes de decidir o que deve e o que não deve ter retry.

Use a skill nas fronteiras externas

A skill é mais eficaz quando aplicada a código que cruza fronteiras de processo ou de rede, como:

• chamadas com httpx ou requests
• publicação ou consumo de mensagens
• queries de banco de dados com modos de falha transitória conhecidos
• chamadas de cloud SDK
• métodos de clients de serviço

Não comece envolvendo grandes fluxos de negócio de ponta a ponta. Primeiro, coloque os controles de resiliência em volta da dependência instável.

O que uma boa saída de python-resilience deve incluir

Quando a skill está funcionando bem, a saída geralmente deve incluir:

• regras explícitas para falhas transitórias vs permanentes
• limites finitos de retry
• exponential backoff
• jitter
• posicionamento de timeout
• exemplos usando ferramentas Python como tenacity
• observações sobre idempotency e efeitos colaterais

Se o resultado apenas disser “retry 3 vezes”, peça uma política de retry mais explícita.

Padrão prático de implementação para pedir

A skill original inclui um quick start baseado em tenacity. Na prática, isso significa que você pode pedir padrões como:

• um decorator em torno de um método de client de serviço
• um helper wrapper para todas as chamadas HTTP de saída
• políticas separadas de retry para leitura vs escrita
• retries filtrados por tipo de exceção ou status code

Para operações de mutação, peça que o modelo justifique a segurança do retry. Padrões de confiabilidade que ignoram idempotency podem criar efeitos colaterais duplicados.

Erros comuns ao usar a python-resilience

Fique atento a estes problemas no código gerado:

• fazer retry de falhas de autenticação ou validação
• ter retries sem timeout
• loops de retry sem orçamento total
• backoff sem jitter
• envolver código demais e esconder a causa raiz
• fazer retry por padrão em writes não idempotentes

Esses são os bloqueios práticos que importam mais do que estilo de código.

Um workflow útil no seu repositório

Para melhores resultados, forneça à skill:

• a função atual do client
• as classes de exceção que aparecem nos logs
• exemplos de status codes
• seu orçamento de latência ou retry
• um ou dois failure traces representativos

Depois, peça:

1. resumo da política
2. mudanças no código
3. testes que você deve adicionar
4. campos de monitoramento para registrar em log

Essa sequência normalmente produz uma saída mais pronta para adoção do que pedir só o código.

FAQ da skill python-resilience

A python-resilience serve só para web APIs?

Não. A python-resilience skill trata, de forma ampla, de dependências não confiáveis. Chamadas HTTP são o exemplo mais fácil, mas o mesmo raciocínio vale para filas, bancos de dados, caches e serviços em nuvem onde falhas transitórias são comuns.

Isso é uma biblioteca ou uma skill de orientação?

É uma skill de orientação, não um pacote Python standalone. Ela ensina padrões e mostra estilo de implementação, incluindo exemplos baseados em tenacity, mas você ainda precisa aplicar esses padrões dentro do seu próprio codebase.

Quando eu não devo usar python-resilience?

Não use python-resilience como camada padrão sobre toda função. Ela é uma escolha ruim para:

• lógica local puramente CPU-bound
• erros claramente permanentes
• fluxos em que retries duplicariam efeitos colaterais inseguros
• sistemas em que o orçamento de latência é apertado demais para janelas de retry

Nesses casos, é melhor falhar rápido ou redesenhar a integração.

A python-resilience é adequada para iniciantes?

Sim, se você já conhece o básico de Python e tratamento de exceções. As ideias centrais da skill são acessíveis, mas o usuário ainda precisa fornecer contexto de negócio, como segurança de retry, orçamento de timeout e quais falhas podem ser tentadas novamente.

Como isso é melhor do que pedir retries a um LLM?

A vantagem de python-resilience for Reliability não está só na geração de código. Ela ajuda o modelo a raciocinar sobre categorias de falha, retries com limite e comportamento de backoff. Prompts genéricos frequentemente ignoram esses limites e geram lógica de retry insegura ou barulhenta sob carga.

A python-resilience escolhe a política exata de retry para mim?

Não automaticamente. Ela fornece um vocabulário forte de padrões, mas a melhor política depende do comportamento da sua dependência, dos requisitos de latência e das regras de idempotency. Espere ajustar tentativas, intervalos de espera e filtros de retry ao seu ambiente.

Como melhorar a skill python-resilience

Dê à python-resilience uma classificação de falhas melhor

A forma mais rápida de melhorar os resultados de python-resilience é especificar quais falhas são transitórias e quais são permanentes. Por exemplo:

• transitórias: ConnectTimeout, ReadTimeout, 503, alguns 429
• permanentes: 400, 401, 403, erros de schema, credenciais inválidas

Essa única distinção normalmente determina se a política gerada é segura.

Informe orçamentos de latência e retry

Se você não fornecer um orçamento, o modelo pode escolher contagens arbitrárias de retry. Declare limites como:

• máximo de 3 tentativas
• janela total de retry abaixo de 8 segundos
• timeout de 2 segundos por requisição
• job em background pode tolerar 30 segundos no total

Essas restrições produzem código mais realista.

Diga se as operações são idempotentes

Muitos erros de resiliência vêm da falta de contexto sobre efeitos colaterais. Melhore o uso da python-resilience classificando as operações como:

• seguras para retry
• seguras apenas com idempotency key
• inseguras para retry automático

Isso muda tanto o design do decorator quanto os filtros de exceção.

Peça regras explícitas de não retry

Não pergunte apenas “o que deve ter retry?”. Pergunte também:

• o que deve falhar rápido?
• o que deve ser exposto imediatamente aos callers?
• o que deve ser logado, mas não tentado novamente?

Isso torna a saída muito mais utilizável em produção.

Peça observabilidade junto com a implementação

Um bom python-resilience guide não deve parar nos decorators. Peça ao modelo para adicionar:

• contagem de tentativas nos logs
• tipo de exceção
• tempo decorrido
• motivo da falha final
• mensagem de esgotamento de retries

Sem isso, sua camada de resiliência pode esconder por que as chamadas estão falhando.

Itere depois da primeira versão

Depois da primeira saída, refine com feedback concreto, como:

• “Não faça retry em requests POST.”
• “Limite o tempo total, não só as tentativas.”
• “Trate 429 de forma diferente de 500.”
• “Use jitter para evitar retries sincronizados.”
• “Separe a configuração de timeout da configuração de retry.”

Esse tipo de iteração melhora materialmente a implementação.

Teste os caminhos de falha que a skill propõe

Peça ao modelo para gerar testes para:

• retries de exceções transitórias
• comportamento de falha rápida em exceções permanentes
• esgotamento de retries
• aplicação de timeout
• limites da política de backoff

Código de resiliência sem testes é fácil de configurar errado e difícil de confiar.

Melhore a saída da skill com traces reais

Se você tiver logs ou exemplos de stack traces, inclua isso. Evidências reais de falha ajudam a python-resilience a recomendar filtros de exceção mais específicos e configurações de timeout/backoff mais críveis do que prompts abstratos.

Mantenha o nível de abstração sob controle

Um modo comum de falha é pedir à skill que desenhe um framework completo de resiliência quando você só precisa de um wrapper confiável de client. Comece menor:

• uma função
• uma dependência
• uma política de retry

Depois expanda, quando o padrão já tiver se mostrado útil.

Use python-resilience como lente de revisão

Mesmo que você já tenha escrito o código, python-resilience também é útil como prompt de revisão. Peça que ela inspecione a lógica de retry existente em busca de:

• retries sem limite
• ausência de jitter
• timeout mal posicionado
• retry em falhas permanentes
• riscos ocultos de efeitos colaterais

Esse uso orientado à revisão costuma ser uma das formas mais valiosas de aplicar a skill em codebases mais maduros.