omounuj/claude-skills

building-backends

Ceci est la compétence principale pour le travail backend. Lisez-la avant d'écrire du code serveur — elle définit les valeurs par défaut et les incontournables pour que chaque service soit cohérent, puis passe le relais aux compétences spécifiques pour les procédures détaillées. Si une règle ici entre en conflit avec une convention locale du dépôt, le dépôt prime ; si elle ne contredit rien, suivez-la.

D'abord, comprendre avant de construire

• Lisez le code existant avant d'y ajouter. Alignez-vous sur le framework, le modèle d'erreur, le découpage en couches, la nomination et le style de test du dépôt. Un modèle « correct » qui combat la base de code est le mauvais modèle. Introduire une deuxième façon de faire quelque chose que le dépôt fait déjà est un défaut, pas une amélioration.
• Clarifiez le contrat, pas l'implémentation. Connaissez les entrées, les sorties, les cas d'erreur, qui appelle la fonction, et les attentes de cohérence/latence avant de choisir une conception. La plupart des remaniements backend viennent d'une construction rapide du mauvais contrat.
• Préférez le banal. Solutions éprouvées, lisibles et évidentes plutôt que des solutions astucieuses. Le backend tourne sans surveillance à 3h du matin ; optimisez pour l'ingénieur d'astreinte qui doit le comprendre à moitié endormi, pas pour l'élégance.

Architecture — les règles

• Couches avec dépendances pointant vers l'intérieur. transport (http) → services (cas d'utilisation) → domaine (entités/règles), et services → repositories (E/S) → domaine. Le domaine n'importe rien vers l'extérieur et ne fait aucune E/S. Si une flèche d'import pointe dans le mauvais sens, la conception est cassée.
• Les handlers orchestrent, les services décident, les repositories font les E/S. Un handler analyse/valide l'entrée, appelle un service, mappe le résultat vers une réponse — pas de logique métier. Un repository est le seul endroit qui touche une base de données, une file d'attente ou un HTTP externe.
• Gardez le domaine testable sans infrastructure. Si vous ne pouvez pas tester unitairement la logique centrale sans base de données ou réseau, la logique est dans la mauvaise couche.
• Un seul point de composition. Construisez la configuration, câblez les dépendances et démarrez le serveur à un seul endroit. Tout le reste reçoit ses dépendances ; rien ne cherche à construire des singletons globaux.
• Concevez sans état. L'état de session/brouillon vit dans un store partagé (BD/cache), pas dans la mémoire du processus, afin que le service puisse passer à l'échelle horizontalement et survivre à un redémarrage. Si vous mettez en cache dans une variable de module, arrêtez-vous et réfléchissez.

→ Pour mettre en place le squelette avec ces couches déjà câblées, utilisez api-service-scaffold.

Conception d'API — les règles

• Contrats explicites et versionnés. Versionnez l'API (URL ou en-tête) dès le premier jour ; ne faites jamais de changement cassant sur un contrat publié — ajoutez la nouvelle forme à côté et dépréciez l'ancienne.
• Validez chaque entrée à la frontière en une valeur typée. Le noyau ne voit jamais un corps de requête brut. Rejetez une entrée invalide avec 422 et des détails par champ ; ne faites jamais confiance au client.
• Un seul modèle d'erreur, mappé une fois. Le code domaine lève des erreurs typées (NotFoundError, ConflictError, ValidationError, UnauthorizedError…) ; un seul mapper de frontière les transforme en statut + { code, message, details? }. Ne fuyez jamais de traces de pile ni de messages internes. 404 pour « pas trouvé » et « pas à vous » : les distinguer fuit l'existence.
• Formes cohérentes. Même enveloppe pour le succès, même enveloppe pour les erreurs, pagination cohérente (curseur plutôt que décalage pour les grands ensembles), casse cohérente des champs. Un appelant doit apprendre vos conventions une fois.
• Idempotence pour les opérations non sécurisées. PUT/DELETE sont idempotents par définition ; sécurisez les POST qui peuvent être réessayés avec une clé d'idempotence. Les réseaux réessaient — un client facturé deux fois est un bug de conception.
• Bons codes de statut. 2xx succès, 4xx faute de l'appelant, 5xx votre faute. Un échec de validation est 422, pas 200-avec-un-corps-d'erreur ; un échec d'authentification est 401/403, pas 400.

La couche de données — les règles

• La base de données est la source de vérité ; appliquez les invariants là-bas. Les clés étrangères, contraintes d'unicité, NOT NULL et vérifications appartiennent au schéma, pas seulement au code applicatif — le code applicatif a des bugs et des courses ; la BD ne ment pas.
• Les transactions encapsulent les invariants et sont aussi courtes que possible. Tout ce qui doit être tout-ou-rien va dans une transaction ; ne faites aucun travail lent (appels externes, calculs lourds) pendant que vous en tenez une. Les transactions longues verrouillent et affament tout le monde.
• Attendez-vous à de la concurrence. Deux requêtes vont frapper la même ligne en même temps. Utilisez du verrouillage optimiste (une colonne de version) ou un isolement approprié ; ne faites jamais de lecture-modification-écriture sur un aller-retour sans protection.
• Les migrations sont rétrocompatibles et réversibles. Ne changez jamais la signification d'une colonne en un seul déploiement ; étendez→migrez→contractez. Ne prenez jamais un verrou bloquant de table sur une table chaude. Chaque migration est livrée avec un rollback testé.
• Surveillez le N+1. Récupérez les données associées en un ensemble, pas dans une boucle de requêtes. Profilez le nombre de requêtes sur les endpoints réels, pas seulement la latence.
• Indexez les requêtes que vous exécutez réellement — et seulement celles-ci. Un index inutilisé n'est qu'une amplification d'écriture pour rien.

→ Pour les mécanismes de migration (verrous, étendre-contracter, backfills, rollbacks), utilisez db-migration-guardian.

Sécurité — la base (non négociable)

• Authentifiez puis autorisez, sur chaque requête, côté serveur. Ne faites jamais confiance à une affirmation du client sur son identité ou ses droits. Vérifiez la propriété sur chaque accès à une ressource — « j'ai un jeton valide » ≠ « cet enregistrement est à moi ».
• Paramétrez chaque requête. Pas de SQL construit par chaîne, jamais. Idem pour toute interface injectable (shell, LDAP, template).
• Les secrets viennent de l'environnement/gestionnaire de secrets, jamais du code. Rien de sensible dans la source, les logs ou les messages d'erreur. (Voir la compétence secrets-management.)
• Moindre privilège partout — utilisateurs BD, identifiants de service, rôles cloud limités exactement à ce dont le service a besoin.
• Limitez le débit et définissez des timeouts sur les endpoints entrants et les appels sortants. Un appel non limité ou un endpoint sans limite est une attaque par déni de service en devenir.
• Validez et encodez aux frontières pour empêcher l'injection et le SSRF ; traitez chaque entrée externe, y compris celle des autres services internes, comme non fiable.

Concurrence, jobs et défaillances

• Supposez que chaque appel externe échoue. Définissez des timeouts, ajoutez des tentatives limitées avec backoff + gigue, et un circuit breaker pour une dépendance instable. Une tentative sans timeout est la façon dont une dépendance lente fait tomber tout le service.
• Rendez les opérations idempotentes pour qu'une tentative (la vôtre ou celle de l'appelant) soit sûre.
• Le travail en arrière-plan va dans une file d'attente, pas dans le chemin de la requête. La requête met en file d'attente ; un worker traite ; les échecs atterrissent dans une file d'attente de lettres mortes pour inspection, pas dans un catch {} silencieux.
• Échouez bruyamment, dégradez-vous avec grâce. Remontez les erreurs à la télémétrie ; là où une dépendance non critique est en panne, dégradez-vous (servez du périmé, sautez l'enrichissement) plutôt que de mettre une 500 sur toute la requête.

L'observabilité fait partie du « fait », pas une réflexion après coup

Un service que vous ne pouvez pas déboguer en production n'est pas terminé. Les logs structurés, les métriques RED/USE et le traçage lié à un seul identifiant de corrélation sont mis en place au fur et à mesure que vous construisez, pas après le premier incident.

→ Utilisez backend-observabilité pour les détails d'instrumentation et les garde-fous de cardinalité/PII.

Position sur les tests

• Testez le comportement via la surface publique (l'endpoint / le cas d'utilisation), pas les internes privés — afin que les tests survivent aux refactorisations.
• Une pyramide, pas un cornet de glace : beaucoup de tests unitaires rapides sur la logique du domaine/service, un ensemble ciblé de tests d'intégration sur la vraie BD et le câblage, quelques tests de bout en bout sur les chemins critiques.
• Chaque correction de bug obtient un test de régression qui échoue avant la correction et passe après.
• Tests déterministes. Pas de dépendance au temps réel, au réseau ou à l'ordre ; ensemencez les données explicitement ; isolez les tests les uns des autres.

Procédure pour toute tâche backend

1. Lisez le code environnant ; fixez le contrat (entrées/sorties/erreurs/appelants/cohérence).
2. Placez le travail dans la bonne couche ; gardez le domaine sans E/S.
3. Validez l'entrée à la frontière ; utilisez le modèle d'erreur unique ; renvoyez le bon statut.
4. Mettez les invariants dans la BD + une transaction courte ; gérez la concurrence ; planifiez les migrations comme étendre-contracter.
5. Appliquez la base de sécurité (autorisation + propriété, requêtes paramétrées, secrets, timeouts/limites).
6. Rendez les appels externes et les jobs résilients et idempotents.
7. Instrumentez au fur et à mesure ; ajoutez des tests à la bonne couche, y compris un test de régression pour tout bug.
8. Confirmez par rapport à la Définition du fait de la compétence spécifique concernée.

Définition du fait

• Couches respectées (le domaine ne fait pas d'E/S ; les dépendances pointent vers l'intérieur) ; un seul point de composition.
• Chaque entrée validée à la frontière ; un seul modèle d'erreur mappé une fois ; codes de statut corrects ; contrat versionné.
• Invariants appliqués dans la BD ; transactions courtes ; concurrence gérée ; migrations rétrocompatibles + réversibles.
• Base de sécurité satisfaite : vérifications d'autorisation + de propriété, requêtes paramétrées, secrets externes, timeouts/limites de débit présents.
• Appels externes/jobs idempotents et résilients ; travail en arrière-plan hors du chemin de la requête.
• Observabilité câblée (logs/métriques/traces sur un identifiant de corrélation) ; tests aux bonnes couches, verts, avec couverture de régression.