backend-silk : standards partagés pour le backend

Compétence de codage. Standards d'ingénierie partagés pour les projets backend et API en Python (Flask, FastAPI, Django, FastMCP) et Node.js (Express). Couvre la structure du projet, la stratification routes / helpers / services, les règles de code basées sur les classes, la gestion des erreurs et des codes de statut, les cas limites, la journalisation, la configuration .env, l'authentification et la propriété des données, la communication entre dépôts, l'hygiène Git et les tests. À utiliser lors de la création, l'extension, le débogage, la refactorisation ou la révision de tout backend Python, API REST, serveur MCP ou backend RAG.

Qu'est-ce que backend-silk : standards partagés pour le backend ?

Cette compétence définit les standards d'ingénierie partagés pour les projets backend, principalement Python (Flask, FastAPI, Django, FastMCP) mais aussi Node.js (Express). Elle a été conçue pour éviter deux échecs majeurs : une structure incorrecte (logique dans la mauvaise couche, fichiers superflus) et le sur-ingénierie (abstractions prématurées). Son objectif est de garantir que le code soit simple, prêt pour la production et que tout changement ou refactorisation préserve le comportement existant. La compétence impose une architecture en couches stricte (routes -> helpers -> services -> base de données / systèmes externes), des règles de code basées sur les classes (classes pour helpers, services et utils), la validation des schémas avec Pydantic, un modèle d'erreur unifié, une journalisation centralisée et une gestion de la configuration via des dataclasses gelées. Elle est destinée aux ingénieurs backend senior utilisant des outils comme Claude Code, Cursor ou Codex, et est conçue pour fonctionner avec des compétences compagnons spécifiques au framework (flask-spider, fastapi-spider, django-spider, node-spider, mcp-spider, rag-spider). La compétence guide l'utilisateur à travers la création, l'extension, le débogage, la refactorisation et la révision de projets, en fournissant des listes de contrôle, des règles de nommage et des fichiers de référence à consulter en cas de besoin.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VivekShevale/eight-eye/tree/HEAD/skills/backend/backend-silk

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Backend Silk : standards partagés pour le backend

Agissez en tant qu'ingénieur backend Python senior qui écrit du code simple et prêt pour la production. Les deux échecs que cette compétence vise à éviter sont la mauvaise structure (logique dans la mauvaise couche, fichiers dont personne n'a besoin) et le sur-ingénierie (abstractions avant d'avoir une application fonctionnelle). Un troisième échec, plus silencieux, est tout aussi coûteux : une modification ou une refactorisation qui supprime silencieusement un comportement qui fonctionnait auparavant.

Compétences compagnons

Nom : les compétences *-spider construisent un type de projet spécifique ; les compétences *-silk sont les standards partagés que chaque spider utilise. Cette compétence contient les principes partagés par chaque backend. Chargez également les compagnons correspondants :

SituationÀ utiliser également
Projet Flask / FastAPI / Djangoflask-spider / fastapi-spider / django-spider
Projet Node.js / Expressnode-spider (les règles ici s'appliquent ; les exemples de code Python sont en Python)
Serveur MCP ou client MCPmcp-spider
PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM)sql-silk
MongoDBmongodb-silk
LLM, embeddings, vector store, RAGrag-spider

Les compétences framework décident de la mécanique du framework ; cette compétence décide des principes. En cas de conflit apparent, suivez la compétence framework pour la syntaxe et cette compétence pour la structure.

Avant de modifier le code

  1. Lisez d'abord le code réel. Vérifiez la structure des dossiers, les modèles, la configuration et le fichier que vous allez modifier. Ne devinez jamais un nom de champ, une signature de fonction, un nom de fichier ou un chemin d'importation ; lisez-le. (Un date deviné au lieu du vrai expense_date a un jour cassé le schéma, l'helper et la réponse en une seule fois). En cas de doute sur le fonctionnement d'une bibliothèque installée, vérifiez son API réelle au lieu de supposer.
  2. Décidez d'abord des routes. Pour une fonctionnalité, listez chaque endpoint (méthode, chemin, requête, réponse, codes de statut, auth) avant de l'implémenter.
  3. Le périmètre vient de l'exigence. Construisez ce dont l'énoncé du problème a besoin. Les endpoints supplémentaires, les analyses, la mise en cache, le rate limiting, le ré-ordonnancement, le suivi des coûts, les endpoints de téléchargement/recherche que personne n'a demandés : mentionnez-les sur une ligne comme « possible plus tard », ne les construisez pas.
  4. Préservez le comportement existant. Lors de la réécriture d'une fonction, listez ce qu'elle fait maintenant (filtres, pagination, validation, journalisation, champs de la réponse) et assurez-vous que la nouvelle version fait toujours tout cela.

Couches

routes -> helpers -> services -> base de données / systèmes externes
            |            |
          utils        utils
DossierPossèdeNe doit pas contenir
routes/ (blueprints Flask, routeurs FastAPI, views.py + urls.py Django, tools/ MCP)URL, méthode, dépendance/décorateur d'authentification, code de statut, modèle de réponse, un appel à un helperLogique métier, requêtes, code de validation, try/except, journalisation
helpers/Logique métier pour une fonctionnalité, comme un contrôleur : validation au-delà du schéma, vérifications de propriété, requêtes et filtres spécifiques à la fonctionnalité, orchestration des services, mappage des échecs attendus aux erreurs HTTP, construction de la réponseOuverture/fermeture de sessions DB, commit/rollback, création de clients LLM ou SDK
services/Un système externe ou une pièce d'infrastructure chacun : connexion DB et CRUD générique (db_service.py), LLM, embeddings, vector store, PDF, email, API d'un autre dépôtRègles métier spécifiques à une fonctionnalité, connaissances HTTP (HTTPException, codes de statut), appels aux helpers
utils/Code basé sur les classes réutilisé par plusieurs modules : LogUtils, ErrorHandlers, AuthUtils, convertisseurs pursCode utilisé par une seule fonctionnalité, appels API externes
schemas/Modèles de requête/réponse Pydantic (Django : serializers.py)Modèles DB
models/Modèles de persistanceLogique métier
prompts/Modèles de prompt sous forme de code (uniquement lorsqu'un LLM est utilisé)Prompts dans .env
config.pyUn objet de configuration chargé à partir de .envLogique

Règles découlant du tableau :

  • La direction est à sens unique. Les routes appellent les helpers, les helpers appellent les services. Un service n'appelle jamais un helper ; un utilitaire n'appelle jamais un helper.
  • Split de base de données. L'helper construit les requêtes de fonctionnalité (filtres, recherche, propriété) ; le service DB les exécute et possède la connexion, la session, le commit et le rollback. Détails dans sql-silk / mongodb-silk. Avec Django, l'ORM est la couche DB, il n'y a donc pas de db_service.
  • Pas de couches de transit. Si un helper se contente de transmettre à un service, supprimez le helper et appelez le service. Chaque fichier doit gagner sa place.
  • Utils vs helpers. Utilisé à plusieurs endroits → utils/. Utilisé par une fonctionnalité → helper de cette fonctionnalité.
  • Créez des dossiers et des fichiers lorsqu'un besoin réel se présente, pas à l'avance. Une seule fonction ne justifie jamais un nouveau dossier (errors/, exceptions.py, core/) ; ajoutez-la à la classe existante qui convient.
  • Nommage : <domain>_routes.py (contenant <domain>_router, ou <domain>_bp dans Flask), <domain>_helper.py → XHelper, <domain>_service.py → XService, <domain>_schema.py, <domain>_utils.py → XUtils, <name>_prompt.py → NAME_PROMPT. Un nom de classe correspond toujours à son dossier (une class ExpenseService à l'intérieur de helpers/ est erronée).

Rôles complets des dossiers et arbres de départ : references/architecture.md.

Règles de code

  1. Modules basés sur les classes. Les helpers, services et utils sont des classes. Utilisez @staticmethod/@classmethod pour le code sans état et les instances uniquement lorsque la classe possède une dépendance (par exemple une session ou un client injecté). Les fichiers de routes et urls.py de Django restent au niveau du module. N'imposez pas l'héritage, les classes de base abstraites ou les interfaces sans deux implémentations réelles.
  2. Les fonctions restent autour de 40 à 50 lignes. Divisez une fonction longue en méthodes significatives de la même classe (par exemple list_expenses → parse_filter_parameters + apply_expense_filters), pas en blocs arbitraires.
  3. Pas de noms de fonction commençant par _. Pas de fonctions définies à l'intérieur de fonctions. Enregistrez les handlers avec des appels explicites tels que app.add_exception_handler(...) au lieu de fonctions décorées imbriquées.
  4. Toutes les importations en haut du fichier, regroupées bibliothèque standard → tierce partie → app.*. Corrigez les importations circulaires en déplaçant le code vers le module approprié, pas en important à l'intérieur des fonctions. La seule exception acceptée est l'importation de blueprints Flask à l'intérieur de create_app().
  5. Utilisez des bibliothèques établies au lieu d'une logique manuscrite : password-validator, email-validator/EmailStr, PyJWT, bcrypt, les chargeurs et diviseurs LangChain, httpx.
  6. Validez une fois. Si le schéma Pydantic applique déjà une règle, ne la revérifiez pas dans le helper.
  7. Ne calculez pas la même chose deux fois dans une seule requête, et échouez rapidement. Effectuez les vérifications bon marché avant les vérifications coûteuses (vérification d'email en double avant le hachage bcrypt).
  8. Pas de configuration codée en dur : les URL, noms de modèles, limites, top_k, température et secrets proviennent de config.py.
  9. Pas de code mort : les fonctions inutilisées, les importations inutilisées, les fichiers vides factices et les restes de startapp sont supprimés.
  10. Indications de type et une docstring d'une ligne sur chaque classe et méthode publique. Commentaires uniquement là où la raison n'est pas évidente.
  11. N'avalez jamais les exceptions. Attrapez les exceptions spécifiques là où vous pouvez agir sur elles ; laissez les autres atteindre le gestionnaire global.

Vérification du sur-ingénierie

Avant d'ajouter un fichier, une classe, une couche, une dépendance ou un motif, demandez-vous : l'exigence actuelle en a-t-elle besoin, et quelque chose d'existant le fait-il déjà ? Tout cela a été construit puis supprimé :

  • pydantic-settings ou frameworks de validation avant que l'application ne s'exécute (une configuration dataclass gelée est suffisante)
  • un nouveau module ou une nouvelle classe d'exception pour une seule erreur
  • des helpers qui ne font qu'appeler un service
  • des paires de clés RS256 entre deux services que vous possédez (un secret partagé HS256 est suffisant)
  • des valeurs dérivées stockées (total_tokens alors que input + output existent)
  • deux collections ou tables alors qu'une seule avec une liste intégrée fonctionne
  • des invites longues et des descriptions d'outils longues

Lorsque plusieurs designs fonctionnent, choisissez le plus simple qui soit toujours sûr pour la production.

Schémas de requête et de réponse (résumé)

  • Chaque endpoint valide son corps et ses paramètres de requête avec un schéma de requête qui rejette les champs inconnus et ceux appartenant au serveur ; le code après validation utilise uniquement l'objet validé.
  • Chaque réponse réussie est construite à partir d'un schéma de réponse : la ressource elle-même (XResponse), une liste {"items", "page", "page_size", "total", "total_pages"}, ou un schéma de résultat d'action (TokenResponse). Pas d'enveloppe, pas de littéraux d'objet assemblés dans le handler.
  • Les codes de statut portent le succès et l'échec : 200 lecture/mise à jour, 201 création, 204 suppression sans corps, erreurs avec ErrorResponse. Jamais un échec avec 200.

Contrat complet et emplacement des schémas par framework : references/api-design.md.

Erreurs (résumé)

  • Chaque réponse d'erreur a une seule forme, à partir de assets/common_schema.py : {"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]} (details uniquement lorsqu'il y a des erreurs de champ)
  • Les services lèvent des exceptions simples ou de bibliothèque ; les helpers lèvent des erreurs HTTP pour les cas attendus ; une classe ErrorHandlers dans utils/error_handlers.py mappe les erreurs de dépendance et attrape tout le reste comme une 500.
  • Codes de statut : 400 mauvaise entrée, 401 non authentifié, 404 manquant ou enregistrement d'un autre utilisateur, 409 doublon, 413 trop volumineux, 422 validation de schéma, 424 dépendance propre en panne (base de données, vector store), 429 rate limit amont, 502 l'amont a retourné une erreur, 503 autre service inaccessible, 504 timeout amont, 500 inattendu. Jamais 200 pour un échec.
  • Les utilisateurs voient un message court et sûr, jamais une trace, un hôte, une chaîne de connexion ou une clé.

Liste de contrôle des cas limites et modèles de handlers : references/errors-and-edge-cases.md. Appels entre dépôts : references/cross-repo-communication.md.

Journalisation (résumé)

Une seule classe LogUtils (assets/log_utils.py) configurée une fois au démarrage à partir de LOG_LEVEL et LOG_TO_FILE dans .env ; tous les autres modules font seulement logger = LogUtils.get_logger(__name__). Format %(asctime)s | %(levelname)s | %(name)s | %(message)s, messages comme Événement | key=value, pas de secrets ou de données personnelles, chaque échec journalisé une fois. Détails : references/logging.md.

Configuration et sécurité (résumé)

  • config.py avec un dataclass gelé chargé à partir de .env (assets/config.py) ; .env.example commit avec des espaces réservés et des commentaires (assets/env.example), .env jamais commit (assets/gitignore).
  • Mots de passe : politique password-validator uniquement lors de l'inscription, hachage bcrypt/werkzeug, "Email ou mot de passe invalide." générique à la connexion.
  • JWT : secret à partir de .env, identifiant utilisateur pris uniquement à partir du token vérifié, jamais à partir du corps de la requête.
  • Chaque requête est limitée à l'utilisateur actuel ; les enregistrements d'autres utilisateurs retournent 404.

Détails : references/security.md. Conventions API (méthodes, pagination, filtrage, paramètres de recherche) : references/api-design.md.

Git et tests (résumé)

  • Jamais commit : .env, clés, identifiants, uploads, données vectorielles, bases de données locales, journaux, environnements virtuels, rapports générés. Les migrations sont commit avec le changement de modèle qui les a produites.
  • Les messages de commit suivent les Conventional Commits (feat:, fix:, refactor:, chore:, test:, docs:, perf:), une préoccupation par commit, un commit par dépôt.
  • Les tests couvrent les chemins critiques : auth, propriété entre utilisateurs, validation, réponses d'erreur, échecs de dépendance (simulés). Les services externes (LLM, autres dépôts) sont simulés.
  • Évaluations (jeux de données golden, scripts d'évaluation, rapports) n'existent que lorsqu'elles sont explicitement demandées ; voir rag-spider / mcp-spider.

Détails : references/git-and-testing.md.

Liste de contrôle de code

  • Couches respectées ; pas de fichier de transit ; les noms de classe correspondent aux dossiers
  • Pas de fonctions commençant par un souligné ou imbriquées ; importations en haut ; fonctions ≤ ~50 lignes
  • Comportement existant préservé (filtres, pagination, validation, champs de réponse)
  • Chaque endpoint a un schéma de requête et un schéma de réponse ; pas d'objets de réponse ad-hoc
  • Cas limites de references/errors-and-edge-cases.md gérés avec des codes de statut corrects
  • Nouveaux paramètres dans config.py et .env.example ; rien de codé en dur ; pas de secrets dans le code ou les journaux
  • Journalisation ajoutée là où elle convient, au bon niveau
  • Aucune importation inutilisée ou code mort laissé derrière

Fichiers de référence (lire uniquement si nécessaire)

FichierLire quand
references/architecture.mdCréation d'un projet, ajout d'un dossier de fonctionnalité, incertitude sur l'emplacement du code
references/errors-and-edge-cases.mdRédaction d'endpoints, de gestionnaires d'erreurs ou révision de chemins d'échec
references/cross-repo-communication.mdUn service appelle un autre dépôt, un serveur MCP ou une API externe
references/logging.mdConfiguration ou révision de la journalisation
references/security.mdAuth, mots de passe, JWT, uploads, secrets, CORS
references/api-design.mdConception d'endpoints, schémas de requête/réponse, pagination, filtres, recherche
references/git-and-testing.mdCommits, descriptions de PR, ce qui n'est jamais commit, tests, approche de débogage

Fichiers d'actifs (copier dans le projet et adapter)

Copiez les modèles de manière sélective : ne conservez que les parties que ce projet utilise actuellement (sections de .gitignore, clés .env.example, champs de configuration). Les lignes restantes pour des fonctionnalités que le projet n'a pas sont du bruit et induisent le lecteur suivant en erreur.

FichierDevient
assets/log_utils.pyapp/utils/log_utils.py
assets/common_schema.pyapp/schemas/common_schema.py
assets/config.pyapp/config.py
assets/env.example.env.example
assets/gitignore.gitignore (la section "Toujours" plus uniquement les sections marquées qui s'appliquent)

Skills associés