Consignes pour un code maintenable : contraintes pour la structure des dossiers et le nommage

Pourquoi le code généré par l’IA devient difficile à maintenir

Le code généré par l'IA a l'air super le premier jour parce qu'il s'exécute vite et produit un résultat immédiatement. Le problème arrive quelques jours plus tard, quand il faut ajouter une fonctionnalité, corriger un bug ou confier le projet à quelqu'un d'autre. Sans règles claires, le modèle optimise pour « faire fonctionner maintenant », pas pour « faciliter les changements futurs ».

Les invites vagues sont la cause habituelle. Si vous ne spécifiez pas de règles pour la structure des dossiers, le nommage et la configuration, le modèle comble les vides différemment à chaque fois. C'est ainsi que vous vous retrouvez avec des fichiers éparpillés dans des dossiers aléatoires, trois façons de nommer la même chose, et des paramètres cachés là où personne ne pense à regarder. Le code peut toujours fonctionner, mais il devient fragile.

Les signes courants d'une dérive vers un cauchemar de maintenance incluent des styles incohérents pour des fonctionnalités similaires, un placement de fichiers imprévisible, des noms qui dérivent (userService, users_service, UserSvc) et une configuration mêlée au code avec des valeurs par défaut peu claires. De petits changements commencent à causer des cassures surprenantes ailleurs.

Pour un fondateur solo ou une petite équipe, « maintenable » signifie généralement pouvoir trouver les choses rapidement, changer un comportement sans casser cinq autres, et intégrer une nouvelle personne sans visite guidée. Cela signifie aussi moins de surprises nocturnes comme une authentification cassée, des secrets exposés ou un enchevêtrement confus de fichiers.

Ajoutez des contraintes dès que le projet vivra plus longtemps qu'une démo, ou si vous prévoyez plus d'une itération. Laissez le modèle improviser uniquement pour des expériences jetables, des tests rapides ou des scripts ponctuels. Si vous envisagez de l'expédier, de le maintenir ou de payer quelqu'un pour le corriger plus tard, fixez des contraintes dès le départ.

Les trois contraintes qui comptent le plus

Si vous voulez des invites pour un code maintenable, ne commencez pas par demander plus de fonctionnalités. Commencez par ajouter trois contraintes qui déterminent comment le code est organisé, nommé et configuré. Ce sont des choses pénibles à changer plus tard.

1) Structure des dossiers (où vont les choses)

Une règle de dossier rend la sortie prévisible et prévient le désordre « tout à la racine ».

Définissez des règles comme : garder un seul point d'entrée, grouper le code par responsabilité et séparer le code applicatif de la configuration, des scripts et des tests. Indiquez aussi ce qui doit absolument ne jamais arriver (par exemple, pas de logique métier dans les composants UI, pas de code base de données dans les routes).

2) Nommage (comment reconnaître les éléments plus tard)

Les règles de nommage réduisent le travail dupliqué et la confusion. Sans elles, vous obtenez deux fichiers qui font la même chose, ou un utils.ts qui devient une poubelle.

Soyez précis : les noms de fichiers, de composants, de fonctions, de routes et de tables doivent suivre un style unique et refléter leur but. Utilisez des verbes cohérents pour les actions (create, update, delete), et évitez les noms vagues comme data, helper ou thing.

3) Configuration (comment sont gérés les paramètres et secrets)

La plupart des prototypes IA cassent quand on passe d'exécutions locales à un vrai déploiement. Des contraintes claires sur la configuration préviennent cela.

Définissez ces règles dès le départ :

• Un emplacement de config unique (variables d'env + un module de config), pas de constantes éparpillées
• Séparer les valeurs par défaut dev et prod, avec des fallback sûrs
• Ne jamais coder des secrets, tokens ou clés API en dur dans le code ou des fichiers d'exemple
• Fournir un fichier .env.example minimal contenant seulement des placeholders
• Echouer rapidement (fail fast) si une valeur requise manque, avec une erreur claire

Si vous héritez d'une app générée par IA qui ignore ces contraintes, ce nettoyage vient généralement en premier car il facilite toutes les corrections ultérieures.

Un modèle d'invite réutilisable que vous pouvez copier

Le gain le plus rapide est un petit bloc de contraintes réutilisable. Collez-le dans n'importe quelle requête, puis ajustez seulement ce qui compte pour le projet.

Voici un template que vous pouvez copier tel quel :

CONSTRAINTS
1) Before coding, output a brief file tree (max 15 lines). Ask 2-4 questions only if needed.
2) Folder structure:
   - Keep source in /src
   - Keep shared utilities in /src/lib
   - Keep UI components in /src/components
   - Keep config in /config
3) Naming:
   - Files: kebab-case (user-profile.ts)
   - React components: PascalCase
   - Functions/vars: camelCase
   - No single-letter names (except i/j in loops)
4) Configuration and secrets:
   - Read all secrets from environment variables
   - Provide a sample .env.example (no real secrets)
   - Safe defaults for dev, strict checks for prod
5) If a rule conflicts with the framework:
   - Follow the framework default
   - Explain the conflict in 2-3 sentences
   - Suggest the closest alternative that keeps the spirit of the rule
6) Output:
   - Generate code file-by-file with clear filenames
   - Add short comments only where the intent is not obvious

Gardez les règles spécifiques, mais pas excessivement détaillées. De bonnes contraintes décrivent des résultats vérifiables (où vivent les fichiers, à quoi ressemblent les noms, d'où viennent les secrets). Évitez les règles de style minuscules qui créent du surcroît de travail.

Une habitude qui évite les sorties désordonnées : demandez d'abord l'arbre des fichiers. Cela force le modèle à planifier, et vous donne une chance rapide de dire « déplace l'auth dans /src/lib » avant qu'il n'écrive 10 fichiers.

Si vous corrigez du code généré par IA plus tard, les contraintes accélèrent aussi la réparation. Quand tout a une maison prévisible, il est plus facile de repérer ce qui manque et de le patcher sans casser des parties non liées.

Étape par étape : comment écrire vos contraintes

Les bonnes invites pour un code maintenable commencent par la clarté, puis ajoutent seulement les règles que vous ferez réellement respecter. Si vous en ajoutez trop, le modèle les ignorera ou produira du contenu superflu.

Un workflow simple qui fonctionne

Rédigez votre invite en cinq parties, dans cet ordre :

• Commencez par une phrase qui indique la tâche (pour qui et l'action principale).
• Verrouillez l'essentiel de la stack (framework, langage et toute version qui affecte la syntaxe ou la config). Évitez le reste.
• Fixez les règles du projet : organisation des dossiers et style de nommage des fichiers, composants et fonctions.
• Définissez le fonctionnement de la configuration : ce qui va dans les env vars, quelles valeurs par défaut sont sûres et ce qui ne doit jamais être commis.
• Exigez une séquence de sortie : d'abord un plan de fichiers, puis le code, puis un court auto-contrôle de ce qui a été vérifié.

Cet ordre compte. Si vous commencez par les dossiers et le nommage avant l'objectif, vous obtenez souvent une structure soignée qui résout le mauvais problème.

Exemple mini (mêmes idées, mots plus simples)

Imaginez que vous voulez un simple suivi de factures pour un freelance. Si vous bloquez React + TypeScript et dite « garder le code serveur dans /api, l'UI dans /web, les types partagés dans /shared », vous évitez beaucoup de chaos. Ajoutez un nommage comme « les composants sont PascalCase, les hooks commencent par use », et vous évitez le mystère ultérieur de l'endroit où vit la logique.

Soyez strict sur la config : « lire les secrets depuis les variables d'environnement uniquement, fournir .env.example, et échouer rapidement avec une erreur claire si une variable manque. » Cette seule ligne évite les problèmes classiques d'auth cassée et de secrets exposés.

Terminez par un auto-contrôle requis. Cela pousse le modèle à détecter les fichiers manquants, les noms incohérents et les valeurs par défaut dangereuses avant vous.

Contraintes de structure de dossiers qui gardent les projets propres

Une arborescence propre est l'une des contraintes les plus faciles à ajouter. Le but n'est pas la perfection, mais la prévisibilité, afin que vous (ou quelqu'un d'autre) puissiez trouver les éléments rapidement et réparer sans casser des parties non liées.

Une structure simple qui convient à la plupart des petites apps web ressemble à ceci :

• src/ui/ pour les écrans et composants réutilisables
• src/domain/ pour les règles métier (ce que l'app fait)
• src/data/ pour la base de données et les API externes (comment les données sont stockées/récupérées)
• src/shared/ pour de vrais helpers partagés (petits, ennuyeux, réutilisés)
• src/config/ pour les valeurs par défaut de l'app (pas les secrets)

Ajoutez une règle de plus : séparez l'UI de la logique métier et de l'accès aux données. En termes simples, l'UI ne doit pas parler directement à la base de données, et le code d'accès aux données ne doit pas décider des droits d'un utilisateur.

Pour éviter des fichiers de 800 lignes, définissez « une responsabilité par fichier » de manière pratique. Un fichier doit avoir un but principal (un composant, un service, un repository). S'il a besoin de deux rubriques différentes, scindez-le. S'il est réutilisé à trois endroits, déplacez-le dans shared/. S'il n'est réutilisé que dans une seule fonctionnalité, gardez-le dans le dossier de cette fonctionnalité. Évitez un utils/ générique : exigez des noms de dossiers spécifiques comme shared/date/ ou shared/format/.

Une règle utile pour créer un nouveau module vs ajouter à un existant : créez un nouveau dossier seulement quand il y a un nouveau concept dans l'app. Une app de facturation pourrait ajouter domain/invoices/ et ui/invoices/ quand les factures deviennent une vraie fonctionnalité, pas juste un écran isolé.

Si vous héritez d'une sortie IA désordonnée, ces contraintes rendent la remédiation plus rapide. Une bonne partie du travail consiste à déplacer le code dans des frontières claires avant de pouvoir réparer en toute sécurité la logique, l'auth ou la sécurité.

Règles de nommage qui empêchent la confusion plus tard

Le nommage est souvent le point où le code IA déraille. Si votre invite est stricte ici, vous passerez moins de temps à traquer des importations, deviner ce qu'une fonction fait ou démêler des modèles « presque identiques ».

Choisissez un style par catégorie et ne mélangez pas. Un mappage simple à coller dans des invites :

• Fichiers et dossiers : kebab-case (ex. user-profile.ts)
• Composants React / classes : PascalCase (ex. UserProfile)
• Fonctions et variables : camelCase (ex. fetchUserProfile)
• Constantes : SCREAMING_SNAKE_CASE (ex. MAX_RETRIES)
• Routes API : kebab-case (ex. /user-profile)

Les noms de fichiers doivent correspondre à ce qu'ils exportent. Si un fichier exporte UserService, nommez-le user-service.ts (ou UserService.ts selon votre règle). N'exportez pas cinq choses sans lien dans un même fichier. Une exportation principale par fichier rend les imports prévisibles et les refactors plus sûrs.

Pour les fonctions, utilisez des noms verbaux qui disent ce qui se passe : getUserById, validateSignupForm, saveInvoice, sendPasswordResetEmail. Évitez les noms vagues comme process, handleThing ou doWork. Si c'est asynchrone, soyez cohérent : ajoutez un suffixe Async partout ou appuyez-vous sur le contexte, mais ne mélangez pas les styles.

Les modèles de données doivent utiliser des noms au singulier (User, Invoice). Les champs de base doivent suivre une convention (snake_case est courant en SQL ; camelCase est courant dans le code applicatif). Choisissez-en une et tenez-vous-y. Alignez les noms associés pour que createdAt corresponde proprement à created_at, et non à create_date à un endroit et created ailleurs.

Une petite liste « à ne pas utiliser » évite beaucoup de temps perdu : temp, misc, helper2, final_v3, newNew. Si vous héritez d'une base pleine de ces noms, renommer et réorganiser paye souvent immédiatement car des noms flous cachent des bugs.

Contraintes de configuration : environnements, secrets et valeurs par défaut

Soyez strict sur ce qui est configuration et ce qui est code. La configuration change entre dev, staging et prod : URL de base de données, clés API, origines autorisées, paramètres de cookie, feature flags. Le code, lui, reste la logique : routes, validation, règles métier.

Une bonne contrainte est de séparer la config d'exécution (runtime) de la config de build. La config runtime doit venir des variables d'environnement, car elle peut changer sans rebuild. La config de build peut vivre dans des fichiers committés au repo, comme un module de config typé avec des valeurs par défaut sûres, ou config/*.json utilisé uniquement pour des valeurs non-secrètes.

Les secrets nécessitent des règles explicites car les apps générées par IA les fuient souvent par accident :

• Ne jamais coder des secrets en dur dans le code ou les fichiers de config
• Ne jamais logger de secrets (même dans des logs de debug)
• Ne jamais committer de secrets (ne commettez qu'un fichier d'exemple)
• Echouer rapidement si un secret requis est manquant
• Utiliser des noms clairs comme DATABASE_URL et JWT_SECRET

Les valeurs par défaut comptent aussi. Demandez des valeurs par défaut sûres et banales pour que l'app se comporte de façon prévisible avant réglage. Par exemple : restreindre le CORS (autoriser seulement une liste connue), cookies d'auth en HttpOnly et Secure en production, et des sessions avec un timeout d'inactivité court et une durée maximale claire.

Exigez aussi un endroit unique où la configuration est documentée. Le plus simple : un .env.example commenté, plus une courte section « Configuration » dans le README listant chaque variable, ce qu'elle fait et un exemple de valeur. Cette contrainte sauve des heures plus tard, surtout quand un prototype marche sur une machine et casse au déploiement.

Contraintes de qualité : erreurs, validation et petits tests

La plupart des apps générées par IA échouent en production pour des raisons ennuyeuses : erreurs floues, validation manquante et absence de tests autour des parties risquées. Quelques contraintes de qualité rendent la sortie plus facile à déboguer maintenant et à réparer plus tard.

Commencez par imposer une gestion d'erreur cohérente. Demandez un seul modèle partout, pas un mélange de chaînes jetées, de réponses ad hoc et d'échecs silencieux. Exigez des erreurs explicites, de la même forme, et sûres à afficher aux utilisateurs.

Exigez ensuite une validation des entrées aux frontières, là où des données non fiables arrivent : routes API, formulaires, webhooks, jobs en arrière-plan. Quand la validation manque, vous obtenez des bugs bizarres comme « ça marche sur ma machine » ou « ça casse seulement pour certains utilisateurs ».

Contraintes faciles à copier :

• Utiliser un seul format d'erreur (par exemple : { code, message, details? }) et ne jamais lancer des chaînes brutes.
• Valider toutes les entrées externes aux frontières, retourner des erreurs de validation claires et ne jamais faire confiance aux données client.
• Garder les fonctions petites (environ 20–40 lignes max) et rendre les valeurs de retour prévisibles (pas de types mixtes).
• Logger les échecs inattendus avec assez de contexte pour reproduire (request id, user id si disponible, action).

Les tests n'ont pas besoin d'être lourds pour être utiles. Demandez un ensemble minimal correspondant aux risques. Si vous avez une connexion, un flux de paiement ou une action create/update, ce sont les premiers éléments à couvrir. Un minimum léger peut inclure le rejet d'authentification pour des identifiants invalides, un chemin de réussite principal + une erreur commune, et un test de validation démontrant qu'une entrée incorrecte retourne une erreur claire.

Enfin, exigez une courte section « comment lancer en local » dans la sortie, incluant les env vars nécessaires et des valeurs par défaut sûres. Cela évite beaucoup de projets qui « ne démarrent pas ».

Exemple d'invite : construire une petite app qui reste maintenable

Imaginez que vous voulez une petite app web avec connexion, une page de profil et un formulaire de paramètres. Sans contraintes, une IA disperse souvent la logique d'authentification sur les pages, mélange des appels DB dans l'UI et invente des noms de fichiers au fil de l'eau. Avec des règles claires, vous obtenez des frontières propres et un plan de fichiers facile à déboguer.

Voici un exemple d'invite copiable que vous pouvez adapter :

Build a small app with:
- Login page
- Profile page (shows name + email)
- Settings page (update display name, toggle a feature flag)

Hard constraints (do not violate):
1) Folder structure:
- /src/routes = route definitions only
- /src/handlers = request/response logic only (no database queries)
- /src/services = business rules (auth, profile, settings)
- /src/data = database access only (queries, repositories)
- /src/config = configuration loader and typed config

2) Naming:
- Files: kebab-case (profile-handler.ts)
- Exports: camelCase functions, PascalCase types
- One main export per file

3) Code boundaries:
- Routes call handlers
- Handlers call services
- Services call data layer
- Data layer is the only place allowed to import the DB client

4) Config constraints:
- Read DATABASE_URL and AUTH_SECRET from environment variables
- Never hardcode secrets or sample keys
- Add FEATURE_SETTINGS_ENABLED default=false when missing
- Provide a single config object from /src/config

Deliverables:
- Start with a file tree
- Then output code file-by-file
- Finish with a summary table: file created/changed + 1 sentence why

Si vous voulez une sortie encore plus stricte, ajoutez : « Si vous devez ajouter un nouveau fichier, expliquez pourquoi il appartient à ce dossier. » Cela pousse le modèle à respecter les frontières plutôt que de tout déverser au même endroit.

Erreurs courantes lors de l'ajout de contraintes

Les contraintes servent à rendre la sortie plus lisible, modifiable et réparable. Les problèmes surviennent quand les règles sont soit trop vagues pour guider le modèle, soit si strictes qu'elles entrent en collision avec le framework utilisé.

Erreur 1 : sur-contraindre le projet

Il est facile d'écrire des règles qui semblent propres mais qui forcent des choix contre-naturels. Par exemple, exiger une disposition de dossiers personnalisée qui va à l'encontre des conventions Next.js, ou interdire un fichier de config standard du framework parce qu'il paraît désordonné. Le modèle passe alors du temps à contourner vos règles au lieu de produire du code correct.

Approche plus sûre : conservez les défauts du framework à moins d'avoir une vraie raison de les changer. Ajoutez des contraintes uniquement là où vous voyez systématiquement de la confusion plus tard (par exemple où vivent les routes API ou les types partagés).

Erreur 2 : sous-contraindre avec des mots flous

« Code propre », « bonnes pratiques » et « prêt pour l'entreprise » ne disent rien au modèle. Remplacez-les par des vérifications qu'il peut suivre.

Exemples de contraintes qui fonctionnent réellement :

• « Output a file tree first, then code files in that order. »
• « Use one naming style: camelCase for variables, PascalCase for components. »
• « Put env vars in .env.example and read them only via a config module. »
• « No new libraries unless you ask first and explain why. »
• « If you move files, include migration steps. »

Un autre souci courant est de laisser le modèle inventer des bibliothèques ou des fichiers de config non demandés. Vous demandez de l'auth, il ajoute trois packages, deux configs et un nouvel outil de build.

Ne sautez pas les étapes de migration quand vous changez l'organisation des dossiers. Un petit renommage peut casser des imports, des tests et le déploiement. Demandez une courte section « ce qui a changé » et les commandes nécessaires pour mettre à jour les chemins. Et exigez toujours un arbre de fichiers ; sans lui, la sortie devient éparse et difficile à assembler.

Liste de contrôle rapide et prochaines étapes

Avant d'accepter du code généré par IA (ou de le merger), faites une passe de 5 minutes. Ces vérifications attrapent la plupart des problèmes « semble ok maintenant, douloureux plus tard » :

• L'arbre des fichiers correspond à vos règles (dossiers, couches, code partagé) et il n'y a pas de répertoires ponctuels aléatoires.
• Les noms sont cohérents : un même concept n'est pas appelé trois choses différentes dans les fichiers, routes et variables.
• Pas de secrets dans le code : pas de clés API, tokens, URL privées ou identifiants réels dans les fichiers, commentaires ou configs d'exemple.
• La configuration est claire : il y a un endroit documenté pour les env vars, les valeurs par défaut sont sûres et le comportement ne change pas silencieusement entre dev et prod.
• C'est exécutable avec des étapes copiées-collées : une personne nouvelle peut installer, configurer et lancer sans deviner.

Si vous ne pouvez pas répondre oui à la plupart de ces points, faites une pause. Un petit nettoyage maintenant coûte moins cher que le débogage dans un mois, surtout quand les problèmes sont cachés dans une confusion de noms, une config éparpillée ou une structure de dossiers qui encourage la croissance en spaghetti.

Si vous avez déjà une base IA en désordre, rendez-la compréhensible avant d'ajouter des fonctionnalités. Un ordre pratique : geler le scope 24 heures, cartographier la structure actuelle (dossiers, points d'entrée, où vivent config et secrets), choisir un standard de nommage et l'appliquer au chemin critique en premier, regrouper la config en un seul endroit avec un fichier d'exemple sûr et des étapes de démarrage claires, puis ajouter quelques contrôles légers (validation, gestion d'erreurs basique, un ou deux tests smoke) pour prévenir les régressions.

Si vous êtes coincé avec un prototype de Lovable, Bolt, v0, Cursor ou Replit qui ne tient pas en production, FixMyMess (fixmymess.ai) peut réaliser un audit gratuit du code pour signaler les problèmes de structure, nommage, configuration et sécurité avant toute correction. Vous obtenez ainsi un plan clair, pas une autre série d'hypothèses.