error-handling-patterns

Vue d’ensemble de la skill error-handling-patterns

Ce que fait la skill error-handling-patterns

La skill error-handling-patterns aide un agent à concevoir un meilleur comportement en cas d’échec, au-delà du simple ajout de blocs try/catch. Elle met l’accent sur des choix concrets : quand utiliser des exceptions plutôt que des retours de type Result, comment distinguer les erreurs récupérables des échecs irrécupérables, comment propager le contexte utile et comment assurer une dégradation maîtrisée en cas de panne partielle.

À qui s’adresse cette skill

Cette skill convient particulièrement aux développeurs, leads techniques et équipes orientées fiabilité qui travaillent sur des API, des services, des workflows asynchrones, des intégrations ou des systèmes distribués. Elle est particulièrement utile lorsque vous avez besoin d’une sémantique d’erreur cohérente à l’échelle d’un codebase, plutôt que de correctifs ponctuels.

Le besoin auquel elle répond

La plupart des utilisateurs n’ont pas besoin d’un cours théorique sur les erreurs. Ils ont besoin d’aide pour répondre à des questions comme : qu’est-ce qui doit échouer immédiatement ? Qu’est-ce qui doit être relancé ? Qu’est-ce qui doit renvoyer des erreurs structurées aux appelants ? Qu’est-ce qui doit être journalisé, exposé, encapsulé ou ignoré ? La skill error-handling-patterns est particulièrement utile lorsque ces décisions ont un impact direct sur la maintenabilité, la rapidité de débogage ou la disponibilité.

Ce qui la distingue d’un prompt générique

Un prompt générique produit souvent des conseils superficiels du type « ajoutez des retries » ou « utilisez try/catch ». Cette skill est plus orientée décision. Elle structure la gestion des erreurs autour d’une philosophie, de catégories d’erreurs et de patterns propres aux langages, ce qui la rend plus pertinente pour des recommandations d’architecture et d’implémentation au service de la Reliability.

Ce qu’il faut savoir avant l’installation

Il s’agit d’une skill pilotée par la documentation, avec un unique fichier SKILL.md et sans scripts d’assistance, références ni assets d’exemple. L’adoption est donc simple, mais la qualité du résultat dépend fortement de la précision de votre prompt et du contexte de code que vous fournissez.

Comment utiliser la skill error-handling-patterns

Options d’installation de error-handling-patterns

Installez-la depuis le dépôt avec :

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

Si votre environnement synchronise déjà les skills depuis ce dépôt, il vous suffira peut-être d’activer ou d’invoquer error-handling-patterns par son nom dans le workflow de votre agent.

Que lire en premier après l’installation

Commencez par :

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

Comme cette skill est fournie sous la forme d’un document principal unique, il n’y a pas de long parcours d’onboarding. Lisez d’abord les sections "When to Use This Skill" et "Core Concepts", puis allez directement aux parties spécifiques au langage qui correspondent à votre stack.

Les entrées nécessaires pour bien exploiter la skill

La skill error-handling-patterns donne les meilleurs résultats si vous fournissez :

• le langage et le framework
• le type d’exécution : CLI, API, worker, UI, service, library
• les modes de défaillance qui vous préoccupent
• si l’appelant est orienté utilisateur, interne ou machine-to-machine
• les contraintes existantes, comme la compatibilité ascendante, les budgets de latence ou les standards de logging

Entrée faible : « Improve error handling in this service. »

Entrée solide : « 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. »

Transformer un objectif flou en prompt efficace

Utilisez une structure de prompt comme celle-ci :

1. Indiquez le système et le langage.
2. Nommez les scénarios de défaillance.
3. Décrivez le comportement attendu pour les appelants et les opérateurs.
4. Demandez des patterns concrets, pas seulement des principes généraux.
5. Demandez des recommandations au niveau du code si vous avez du source à partager.

Exemple :

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.

Les meilleurs workflows pour un usage concret

Utilisez cette skill dans l’un de ces trois modes :

• Mode conception : avant l’implémentation, pour définir les contrats d’erreur et les comportements de récupération
• Mode refonte : lorsqu’un codebase présente des exceptions, valeurs de retour ou logs incohérents
• Mode incident : après des échecs en production, pour repenser la gestion autour des véritables classes de défaillance

Pour la plupart des équipes, le workflow à plus forte valeur est le suivant : classifier les erreurs -> choisir un modèle de propagation -> définir le comportement côté appelant -> ajouter de l’observabilité -> tester les chemins d’échec.

Les points forts de la skill error-handling-patterns

La skill est particulièrement utile lorsque vous avez besoin de recommandations sur :

• exceptions vs types Result
• erreurs récupérables vs irrécupérables
• logique de retry et circuit breaker
• gestion des échecs en asynchrone et en concurrence
• meilleur contexte pour le débogage et les opérateurs
• dégradation maîtrisée dans des systèmes sensibles à la fiabilité

Elle est plus pertinente pour les décisions de politique et de patterns que pour générer du boilerplate spécifique à un framework.

Parcours de lecture du dépôt pour évaluer plus vite

Si vous cherchez à savoir s’il faut adopter la error-handling-patterns skill, parcourez le dépôt dans cet ordre :

1. la liste des headings de SKILL.md
2. "When to Use This Skill"
3. "Core Concepts"
4. les sections sur les patterns spécifiques aux langages
5. les éventuels exemples montrant les retries, la propagation et les échecs gérés proprement

Cela vous permet de voir rapidement si elle correspond à votre stack et si elle apporte un cadre suffisant au-delà d’un prompting classique.

Conseils pratiques pour améliorer la qualité des résultats

Demandez à la skill de rendre les arbitrages explicites. Les bons prompts incluent des questions comme :

• Quels échecs sont des résultats métier attendus, et lesquels sont de vraies exceptions ?
• Où placer les retries pour éviter le travail en double ?
• Quel contexte faut-il attacher avant de relancer ou de renvoyer l’erreur ?
• Quelles erreurs doivent être visibles par l’utilisateur, assainies ou réservées à l’interne ?
• Quand le système doit-il se dégrader au lieu d’abandonner ?

Dans la plupart des cas, ces précisions comptent davantage que de demander simplement des « best practices ».

Contraintes et cas où la skill convient mal

N’attendez pas de cette skill qu’elle remplace une documentation de framework approfondie, des playbooks SRE ou des références de runtime de langage. Elle ne fournit ni outil exécutable ni règles de lint. Si vous avez seulement besoin d’aide sur la syntaxe d’une construction de langage précise, un prompt ciblé sera souvent plus rapide. Le scénario d’usage error-handling-patterns usage est le plus convaincant lorsque votre vrai problème concerne la cohérence de conception et la Reliability en situation d’échec.

FAQ sur la skill error-handling-patterns

error-handling-patterns est-elle adaptée aux débutants ?

Oui, si vous maîtrisez déjà les bases du contrôle de flux et cherchez un guide structuré de gestion des défaillances. Elle convient moins comme toute première introduction aux erreurs en programmation, car elle met l’accent sur les choix de conception, pas seulement sur la syntaxe.

Quand l’utiliser plutôt qu’un prompt de code classique ?

Utilisez error-handling-patterns lorsque le comportement en cas d’échec est le vrai sujet. Si vous vous souciez des contrats d’API, des retries, des modes dégradés ou de l’observabilité en situation d’erreur, cette skill offre un meilleur cadre qu’une demande générique du type « add error handling ».

La skill prend-elle en charge plusieurs langages ?

Oui. La source couvre explicitement des approches transverses aux langages — exceptions, types Result et catégories d’erreurs — avant de passer à des patterns propres à chaque langage. Elle est donc utile pour les équipes avec une stack mixte, même si vous devez toujours préciser votre langage dans le prompt.

error-handling-patterns est-elle faite pour les équipes Reliability ?

Oui. L’adéquation error-handling-patterns for Reliability est forte, car elle aide à définir le comportement des systèmes lors de défaillances de dépendances, de pannes partielles et de défauts asynchrones. Elle est particulièrement pertinente pour les responsables de services qui doivent assurer un comportement cohérent à la fois pour les opérateurs et pour les appelants.

Quelles sont les limites de la skill ?

Cette skill aide à la prise de décision et aux patterns d’implémentation autour des défaillances. Elle ne fournit ni harness de test, ni dashboards de production, ni automatisation spécifique au dépôt. Vous devez toujours valider les recommandations au regard de votre architecture et de votre historique d’incidents.

Dans quels cas la skill est-elle peu adaptée ?

Évitez-la si votre besoin est purement mécanique, par exemple corriger une seule erreur de compilation ou apprendre la syntaxe exacte d’un type d’exception dans un framework. Elle est aussi moins adaptée lorsque le vrai problème vient de règles métier manquantes plutôt que d’une mauvaise structuration de la gestion des erreurs.

Comment améliorer la skill error-handling-patterns

Donnez à la skill error-handling-patterns une cartographie des défaillances, pas seulement du code

Vous obtiendrez de meilleurs résultats si vous nommez clairement le paysage des erreurs :

• erreurs de validation
• timeouts de dépendances
• rate limits
• écritures partielles
• requêtes dupliquées
• échecs de désérialisation
• bugs de programmation

Cela permet à la skill de recommander des traitements différents au lieu d’appliquer le même pattern à toutes les erreurs.

Séparez l’expérience de l’appelant de celle de l’opérateur

Un écueil fréquent consiste à demander de « meilleures erreurs » sans préciser pour qui. Indiquez à la skill ce que les utilisateurs finaux doivent voir, ce que les clients API doivent recevoir et ce dont les opérateurs ont besoin dans les logs ou les traces. Vous obtiendrez ainsi des recommandations plus utiles sur l’assainissement, l’encapsulation et la propagation du contexte.

Demandez une taxonomie d’erreurs explicite

Si la première réponse vous paraît trop générique, demandez à la skill error-handling-patterns de produire :

• des classes ou catégories d’erreurs
• des frontières entre récupérable et irrécupérable
• des règles retryable vs non-retryable
• une correspondance entre erreurs internes et réponses externes

Cela transforme souvent des conseils vagues en recommandations directement exploitables en implémentation.

Fournissez de vraies contraintes qui changent le choix du pattern

Les patterns diffèrent selon que vous avez des SLO de latence stricts, des retries coûteux, des risques d’idempotence ou des contrats d’API à compatibilité ascendante. Mentionnez ces contraintes explicitement. Ce sont souvent elles qui déterminent s’il faut renvoyer un Result, lever une exception, court-circuiter, mettre en file pour plus tard ou passer en mode dégradé.

Demandez une itération après la première version

Une bonne deuxième passe ressemble souvent à ceci :

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.

L’itération compte, car le meilleur pattern dépend de l’échelle, du public visé et des conséquences opérationnelles.

Prompts faibles à éviter

Évitez les prompts du type :

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

Ils masquent les critères de décision. La skill est bien plus efficace lorsqu’on lui demande de trancher entre des compromis, et non simplement d’ajouter des constructions défensives au code.

Comment valider le résultat

Après avoir utilisé le guide error-handling-patterns, vérifiez si la recommandation :

• distingue les échecs attendus des bugs
• évite les tempêtes de retries
• conserve suffisamment de contexte pour déboguer
• expose aux appelants des erreurs sûres et stables
• permet une dégradation maîtrisée lorsque c’est pertinent

Si ce n’est pas le cas, affinez le prompt avec des cas de défaillance concrets et les résultats attendus, plutôt que de demander plus de détails de manière abstraite.