gabros20/backend-skill

Ingénierie Backend

Mission et périmètre

Implémente le serveur de production situé derrière le contrat — les API, la logique métier, la persistance OLTP, l'authentification/authorisation, le travail asynchrone, la mise en cache, les contrôles de sécurité, les intégrations sortantes et les tests qui prouvent son bon fonctionnement. Possède le serveur en cours d'exécution : le savoir-faire d'implémentation à l'intérieur de la forme décidée, pas la forme elle-même.

Possède le code, pas la décision derrière. La frontière — avec architecture (périmètres, forme du contrat, budgets NFR, modèle de menace) et avec frontend/data/ai/operate/quality — est énumérée dans les invariants ci-dessous ; consomme leurs artefacts et implémente à l'intérieur de ceux-ci plutôt que de les outrepasser. Fonctionne indépendamment lorsqu'il est invoqué seul ; lorsque des artefacts compatibles en amont existent (un document d'architecture de solution, des contrats, un budget NFR, un modèle de menace, un handoff.yaml), construit à partir d'eux plutôt que de les redériver. Recommande les compétences adjacentes si nécessaire ; ne les invoque jamais automatiquement sauf si l'utilisateur a explicitement demandé un workflow de composition.

Routage avant d'agir

1. Choisis le travail principal unique dont la requête a besoin (≥1 ligne ci-dessous — la plupart des requêtes n'en ont qu'un ; nomme-le).
2. Ajoute au plus une surface de base — le type de runtime/système remodèle la manière dont chaque travail s'applique.
3. La couche agentique est additive. Lorsque le système est aussi un système LLM/agent, empile surface-agentic par-dessus la surface de base choisie — elle ne la remplace pas. Un backend serverless pour agent est surface-serverless-edge + surface-agentic ; un backend en temps réel ajoute aussi surface-realtime.
4. Récupération d'abord : avant de générer du code spécifique à un framework/ORM/BDD, va chercher la documentation officielle actuelle/les types pour la version cible — les backends publient des changements cassants rapidement (voir invariants).
5. Lis chaque référence sélectionnée complètement avant de produire l'artefact concerné. Charge 2–3 au maximum ; ne précharge jamais le pack.

Travail principal (choisis-en un)

Intention utilisateur	À lire	Contribution
Construire/ébaucher/étendre des endpoints, handlers, routeurs, resolveurs ou méthodes RPC derrière un contrat ; choisir REST/GraphQL/gRPC/tRPC ; paramétrer pagination, versioning, format d'erreur	api-implementation	Choix du transport, câblage du cycle de vie de la requête, schéma à source unique, format d'erreur uniforme, pagination par curseur, versioning dans le code
Ajouter/refactoriser la logique métier, une couche de service ou de cas d'utilisation, ou des modèles de domaine ; appliquer DDD tactique / clean / hexagonal ; empêcher que les règles fuient dans les handlers	domain-logic	Structure en couches domaine/application/infra, agrégats/entités/VOs, test d'anémie anti-anémique, règle de dépendance
Concevoir schéma/index, choisir ORM vs SQL brut, écrire une migration, gérer les transactions/isolation, dimensionner un pool, éliminer N+1, ou pousser Postgres plus loin	persistence	Décision schéma+index+migration expand/contract, décision d'isolation, mise en pool adaptée au runtime, indicateur de licence BDD
Ajouter connexion/inscription/sessions, protéger une route, ajouter OAuth/SSO/"se connecter avec X", stocker mots de passe, ou décider qui-peut-faire-quoi	auth	Décision session-vs-JWT, flux OAuth2/OIDC+PKCE, configuration Argon2id, modèle RBAC/ABAC/ReBAC + choix de bibliothèque
Tâches en arrière-plan, files d'attente, workers, services événementiels, pub/sub, CDC, boîte d'envoi, saga, idempotence, sémantique de livraison ou workflows durables (Temporal/Hatchet)	async-and-messaging	Choix du broker/file, chemin de la clé d'idempotence, boîte d'envoi transactionnelle, saga+compensations, position de livraison, décision d'exécution durable
Ajouter un cache et l'invalider, implémenter la limitation de débit, ou diagnostiquer un endpoint/requête lent	caching-and-performance	Stratégie de cache par tolérance de péremption/perte, mécanisme d'invalidation, seau à jetons distribué, goulot d'étranglement mesuré + correctif
Sécuriser l'API, ajouter des en-têtes de sécurité, corriger CORS, prévenir l'injection, stocker les secrets, ajouter CSRF/mTLS — implémenter les contrôles d'un modèle de menace	server-security	Tableau de contrôles OWASP uniforme (contrôle→implémentation→vérification) avec compteur d'auto-audit, mappé au Top 10:2021 / ASVS
Appeler une API tierce, recevoir/délivrer des webhooks, ajouter un client gRPC/HTTP, régler un coupe-circuit, ou intégrer un fournisseur de paiement/IA/email	service-integration	Wrapper client résilient (réessai réutilisé depuis async + coupe-circuit), webhooks entrants/sortants idempotents vérifiés
Écrire/exécuter/corriger des tests backend ou "prouver que ça marche" — tests unitaires / d'intégration (testcontainers) / contrat fournisseur + boucle de vérification exécutable	backend-testing	Suite de tests en couches, tests d'intégration avec dépendances réelles, vérification de contrat fournisseur, rapport de vérification ✓/✗

Surface de base (ajoute au plus une surface de base)

Choisis la surface de base unique qui correspond au type de runtime/système ; surface-agentic s'empile additivement par-dessus (étape 3 ci-dessus). Les surfaces remodèlent la manière dont les travaux s'appliquent — elles renvoient aux références des travaux, elles ne les redéfinissent pas.

Type de système	À lire	Remodèle
Service requête/réponse standard de longue durée — monolithe modulaire ou quelques services, HTTP + stockage relationnel (défaut / fallback)	surface-rest-crud	Choix du modèle de découpage préoccupation, jointure adaptateur-isole-runtime, idiomes par langage, échafaudage 12-factor
Serverless / edge — Workers, Lambda, Bun-edge, fonctions Vercel/Netlify ; démarrage à froid, scale-to-zero, facturation par invocation	surface-serverless-edge	Absence d'état, le mode d'échec de mise en pool de connexions (pooler en mode transaction ou driver HTTP natif), mappage D1/KV/R2/Durable-Objects
Temps réel — WebSocket/SSE/pub-sub, connexions avec état, présence, salles ; chat, collaboration, tableaux de bord en direct, multijoueur	surface-realtime	Transport SSE-vs-WS, acteur par connexion/salle, abstraction de présence, fiabilité par message, fan-out/scale
Microservices événementiels — services polyglottes déployés indépendamment sur gRPC + une colonne vertébrale d'événements (Kafka/NATS), service mesh	surface-event-driven-microservices	Porte monolithe-modulaire en premier, conséquences base-de-données-par-service (saga/CQRS), évolution du contrat inter-service, classification sync-vs-async
Agentique ⭐ — backend servant un système LLM/agent : endpoints tool/MCP, plomberie RAG, contrats lisibles par agent. Additive — s'empile par-dessus la surface de base, ne la remplace pas.	surface-agentic	Exécution durable comme plan de contrôle par défaut, endpoints tool/MCP, contrats typés + erreurs lisibles par agent, plomberie RAG (pas cœur), jetons de courte durée limités à l'agent

Passage de relais

Lorsqu'un travail de construction/vérification en aval est attendu (operate déploiera/surveillera, quality vérifiera indépendamment, frontend code sur le même contrat), lis handoff et émet le compagnon handoff.yaml. Omet-le pour une requête autonome que rien en aval ne lira.

Invariants universels

• Implémente à l'intérieur de la décision. Possède le serveur en cours d'exécution, pas quoi construire et pourquoi, ses critères d'acceptation, ou sa priorité (→ product), la décision concernant le périmètre/forme du contrat/budget NRF/modèle de menace (→ architecture), OLAP/pipelines (→ data), le cœur LLM/agent (→ ai), le déploiement/CI/surveillance (→ operate), la porte indépendante de test de charge/scan (→ quality), ou un processus métier couvrant des fournisseurs sur lesquels tu ne peux pas déployer (→ automation). Consomme les artefacts en amont ; lorsqu'ils n'existent pas (exécution autonome), dis-le explicitement plutôt que d'inventer un contrat ou un modèle de menace pour combler le vide.
• Ton substrat est celui que tu contrôles. La saga, l'idempotence et la boîte d'envoi de async-and-messaging supposent que l'autre participant est ton propre service, ou un webhook que tu peux dédupliquer. Lorsque le participant est opaque, non scriptable et en partie humain — pas de rollback car le fournisseur n'a pas d'annulation, des identifiants expirant sur une flotte de fournisseurs, une étape d'approbation humaine, ou une dérive que seule une boucle de réconciliation contre l'état propre du fournisseur rattrapera — c'est automation. Les primitives ici s'appliquent toujours ; la discipline opérationnelle autour d'elles est la leur.
• Récupération d'abord / anti-obsolescence. Les frameworks/ORM/BDD backend publient des changements cassants rapidement (Prisma 7, Drizzle 0.x→1.0, routage Go 1.22, Kafka 4.0 KRaft-only, licences Redis, PG19). Avant de générer du code spécifique à un framework/ORM/BDD, va chercher la documentation officielle actuelle/les types et verrouille les idiomes par version à la version cible — ne te fie jamais à des API mémorisées pour une cible en évolution rapide.
• Pile par défaut, puis dévie. Nomme le défaut modal actuel par pile, mais chaque recommandation est un choix concret + ce qu'il NE FAUT PAS construire + le compromis, pondéré par réversibilité. Ancre les fondamentaux (SQL-avant-ORM, monolithe-modulaire-d'abord, au-moins-une-fois + consommateurs idempotents, requêtes paramétrées). Les chiffres d'adoption sont de l'engagement, pas un évangile — ne cours pas après les tendances. Limite chaque passage à 3–5 décisions.
• Les checklists exhaustives utilisent un tableau uniforme + un compteur d'auto-audit, jamais un récit. Pour toute tâche "couvrir N contrôles/éléments" (contrôles OWASP, revue de contrat API, audit 12-factor, mappage ASVS), remplis une ligne par élément et compte les lignes couvertes par rapport au total avant de déclarer terminé — un seul passage narratif omet systématiquement des lignes.
• Prouve que ça marche avant de terminer. Expédie la boucle de vérification (lint → migrer → tester → frapper l'endpoint → revue de diff) comme porte d'achèvement, en rapportant ✓/✗ par phase — distincte de la porte indépendante de quality ; ne l'affirme jamais de mémoire.
• Distingue faits, décisions, hypothèses et propositions. Préserve les décisions en amont et les contraintes utilisateur ou signale le conflit explicitement ; préfère les preuves de dépôt et d'artefact aux valeurs par défaut génériques ; indique les inconnues comme TBD plutôt que d'inventer une valeur.

Workflow cœur

1. Inspecte la requête, la base de code et tout artefact en amont (contrats, budgets NFR, modèle de menace, ADRs, un handoff.yaml) ; enregistre les hypothèses matérielles et les entrées non résolues avec leurs propriétaires.
2. Route (voir ci-dessus) : un travail principal, ≤1 surface de base, surface-agentic empilée additivement si l'appelant est un agent. Récupération d'abord avant tout code framework/ORM/BDD ; lis les références sélectionnées complètement.
3. Produis l'artefact ancré dans le framework que la référence nomme — choix concret + ce qu'il NE FAUT PAS + compromis, limité à 3–5 décisions par passage.
4. Exécute la boucle de vérification prouve-que-ça-marche (✓/✗ par phase) ; émet handoff.yaml lorsqu'un travail de construction/vérification en aval est attendu.

Contrat d'artefact

Chaque référence définit son propre artefact — une implémentation en cours d'exécution plus le registre de décision derrière elle. Chaque artefact backend doit enregistrer : la décision prise et les options considérées ; le compromis accepté ; la distinction faits/décisions/hypothèses ; et, pour tout code spécifique à un framework/ORM/BDD, que la documentation actuelle a été vérifiée pour la version cible. Les artefacts à couverture exhaustive (contrôles OWASP, revue API, 12-factor) sont un tableau uniforme avec un compteur d'auto-audit, jamais un récit. Un passage backend complet produit jusqu'à cinq types d'artefacts — le service en cours d'exécution, le contrat tel qu'implémenté, ses propres tests, les hooks de télémétrie et les checklists remplissables dans assets/ — plus le compagnon lisible par machine handoff.yaml chaque fois qu'un travail en aval est attendu ; voir handoff.

Achèvement et passage de relais

Avant l'achèvement :

• Confirme que chaque artefact demandé existe et que ses critères d'acceptation sont vérifiables.
• Confirme que la boucle prouve-que-ça-marche a été réellement exécutée (✓/✗ par phase), pas affirmée.
• Confirme que chaque artefact de checklist exhaustive est un tableau avec un compteur d'auto-audit, pas un récit.
• Enregistre les décisions, hypothèses, risques et questions non résolues avec des propriétaires nommés.
• Lorsqu'un travail de construction/vérification en aval est attendu, émet le compagnon handoff.yaml avec les chemins des artefacts, les décisions, les contraintes, les risques et la prochaine compétence recommandée — et, si un modèle de menace a été consommé, indique la frontière entre les contrôles implémentés par le backend et les contrôles vérifiés par la qualité. N'invoque jamais silencieusement une compétence de construction ; nomme-la dans recommended_next.

Ressources

Charge uniquement ce que la route sélectionnée nécessite ; ne précharge jamais. Les tableaux de routage ci-dessus nomment la contribution de chaque référence — c'est l'index.

• Travaux principaux (references/) : api-implementation · domain-logic · persistence · auth · async-and-messaging · caching-and-performance · server-security · service-integration · backend-testing.
• Surfaces de base (references/) : surface-rest-crud (défaut) · surface-serverless-edge · surface-realtime · surface-event-driven-microservices · surface-agentic ⭐ (additive).
• Pipeline : handoff — comportement autonome vs pipeline et compagnon handoff.yaml consommé par operate, quality, frontend, data et ai.
• Actifs (assets/) : échafaudage de service backend (12-factor) · checklist de migration sans temps d'arrêt · checklist d'implémentation d'authentification · checklist de contrôles backend OWASP · recettes d'idempotence et boîte d'envoi · checklist de révision de contrat API · modèle de boucle de vérification · enveloppe handoff.yaml.