Utilisez cette checklist d'export de base de code générée par l'IA pour remettre un projet en toute sécurité : variables d'environnement, secrets, configuration locale, bootstrap DB, CI et un README d'exécution clair.
La plupart des projets exportés échouent pour une raison simple : ils fonctionnaient bien à l'intérieur de la plateforme d'origine, où des valeurs par défaut, des secrets, l'état de la base de données et des étapes de build étaient déjà en place. Une fois le code sorti de cette bulle, le développeur suivant doit deviner ce qui avait été supposé.
Une remise propre signifie que le projet peut être cloné, configuré et démarré par quelqu'un qui ne l'a pas construit, sur une machine vierge, sans longs aller-retour. Il ne faut pas du code parfait. Il faut que les éléments de base soient explicites et reproductibles.
Les exports cassent toujours pour les mêmes raisons : configuration cachée, gestion des secrets floue, étapes locales vagues, surprises liées à la base de données, et CI qui ne fonctionne que dans un seul environnement.
C'est pourquoi une checklist d'export de base de code générée par l'IA porte surtout sur la documentation et la reproductibilité, pas sur la copie de fichiers. Si vous avez construit l'app sur une plateforme vibe-coding comme Koder.ai puis exporté le code source, l'équipe suivante a toujours besoin d'une carte : quoi configurer, quoi exécuter et à quoi ressemble un état « fonctionnel ».
Cette checklist se concentre sur l'essentiel de la remise : variables d'environnement, secrets, configuration du développement local, bootstrap de la base de données, configuration CI, et un README pratique « comment lancer ». Elle ne couvre pas les décisions produit, le polish UX, ni la refonte d'architecture.
La responsabilité doit aussi être claire. Le créateur doit rendre les hypothèses visibles (docs, scripts, valeurs par défaut sûres). Le récepteur doit adapter le projet à son environnement (gestionnaire de secrets, hébergement, règles CI plus strictes). Quand les deux côtés savent ce qu'ils doivent faire, la remise devient routinière.
Une remise propre commence par un accord simple : que signifie « terminé » quand le code quitte la plateforme. Sans ça, les équipes se disputent plus tard sur des scripts manquants, des dépendances surprises, ou sur la version qui est la bonne.
Choisissez un point unique et stable dans le temps et traitez-le comme la source de vérité. Exporter en plein changement, c'est la façon dont on finit avec un repo qui tourne presque.
Un bon point d'export est généralement l'un de ceux-ci :
Ajoutez une phrase expliquant pourquoi ce point est le bon. Exemple : « Tous les flux principaux passent et le schéma de base de données est final pour ce jalon. »
Rédigez un inventaire court de ce que le destinataire doit attendre. Soyez explicite sur ce qui est inclus et ce qui est volontairement exclu.
Incluez le minimum : code source (apps, services, packages partagés), modèles de config (fichiers env exemples), scripts (build, dev, test, migrations, seed), et notes de déploiement. N'incluez des données d'exemple que si elles sont nettoyées et sûres.
Ensuite, figez les versions pour que « ça marche sur ma machine » ne devienne pas la nouvelle base. Capturez les versions d'exécution et de toolchain (Node, Go, Flutter, gestionnaire de paquets), ainsi que la version de la base de données (la version majeure de PostgreSQL compte).
Enfin, listez les prérequis à effectuer avant de lancer quoi que ce soit. Restez concis et concret : comptes requis, outils à installer, ports à libérer, et toute étape d'installation unique.
La plupart des exports « ça marchait sur la plateforme » cassent parce que des paramètres clés n'ont jamais été consignés. Les variables d'environnement sont souvent en cause : elles vivent en dehors du repo, donc un nouveau membre clone le projet et n'a aucune idée des valeurs attendues.
Considérez ceci comme requis pour une exportation propre : chaque variable doit être repérable, expliquée et facile à définir sans deviner.
Créez une source unique de vérité dans votre README de remise : une liste de noms de variables, ce qu'elles contrôlent et d'où proviennent les valeurs. Gardez les explications en langage simple et signalez tout ce qui est lié à la sécurité.
Un format simple pour chaque variable :
En parallèle, fournissez un fichier .env.example dans le repo. Il doit inclure chaque variable potentiellement nécessaire, avec des valeurs de substitution sûres pour que l'app puisse démarrer avec des modifications minimales.
# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev
# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173
# Environment specific
PUBLIC_BASE_URL=http://localhost:3000
Quelques détails évitent la plupart des confusions :
Rendez « requise vs optionnelle » explicite. Si une variable manquante provoque un plantage, dites-le. Si elle active une fonctionnalité (envoi d'e-mails, paiements, stockage de fichiers), nommez la fonctionnalité et décrivez ce qui se passe quand elle n'est pas définie.
Indiquez ce qui change selon l'environnement. DATABASE_URL et PUBLIC_BASE_URL diffèrent souvent entre dev, staging et production, tandis que LOG_LEVEL peut rester le même partout. Si vous avez utilisé Koder.ai pour exporter et déployer, vérifiez que les valeurs par défaut de la plateforme (ports, URLs de base, origines autorisées) sont bien reflétées dans la doc pour que le comportement reste cohérent hors plateforme.
Enfin, précisez comment les variables d'environnement sont chargées en local. Si le projet attend un fichier .env, indiquez où il se trouve et si l'app le lit automatiquement ou nécessite une commande/outil.
Les secrets sont des valeurs dont la fuite causerait des dommages : clés d'API, mots de passe de base, tokens d'auth, secrets OAuth, clés privées, secrets de vérification de webhook, etc.
Pour un export, simplifiez : le dépôt ne doit contenir que des placeholders, jamais de vraies valeurs secrètes. Si un secret est nécessaire au démarrage, incluez-le avec un nom clair dans .env.example et expliquez comment générer la vraie valeur.
Un pattern pratique est de séparer trois choses : un fichier d'exemple, un fichier local, et un store de secrets pour la CI/deploiement. Votre code exporté doit inclure l'exemple, ignorer le fichier local, et documenter comment la CI/l'hébergement reçoit les secrets.
Choisissez une approche par environnement et tenez-vous-en à elle.
.env (gitignored) chargé par l'app, ou le gestionnaire de secrets local de votre équipeExemple : le repo inclut PAYMENTS_API_KEY=replace_me. Le récepteur génère sa propre clé dans le dashboard du fournisseur et la définit dans son .env local et en CI. Le code reste identique.
La remise est un bon moment pour faire tourner les secrets, surtout s'ils ont été utilisés dans une session partagée sur la plateforme.
.env locaux.Si vous avez exporté depuis Koder.ai, considérez l'export comme un nouvel environnement et générez des secrets frais pour l'équipe destinataire.
Une remise réussie permet à un nouveau développeur de cloner le repo, exécuter quelques commandes et voir l'app fonctionner sans deviner. Visez des prérequis prévisibles, un ordre de commandes clair et un court bloc « comment lancer » qui reflète la réalité.
Mettez ces points en haut du README pour éviter les inférences via les messages d'erreur :
Si le projet a été construit sur Koder.ai, alignez la configuration locale avec ce que vous avez exporté (même structure de dossiers, mêmes commandes de démarrage). N'assumez pas « Postgres est déjà lancé » sauf si vous l'indiquez clairement.
Indiquez les commandes exactes dans l'ordre que doit suivre un nouveau coéquipier. Gardez-les copiables-collables :
# 1) Install dependencies
cd web
npm ci
cd ../server
go mod download
# 2) Create your env file
cp .env.example .env
# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose
# 4) Run the app
cd server
go run ./cmd/api
cd ../web
npm run dev
Ajoutez juste en dessous une section minimaliste test et build :
# Tests
cd server && go test ./...
cd web && npm test
# Build
cd web && npm run build
cd server && go build ./...
La plupart des problèmes « ça ne démarre pas » tombent dans quelques catégories :
Mauvaises versions (Node/Go). Symptômes : erreurs de dépendances ou de compilation. Correction : installez les versions indiquées et relancez les installations.
Variables d'environnement manquantes. Symptômes : config « undefined », échecs d'auth, erreurs 500. Correction : comparez .env à .env.example et remplissez les valeurs requises.
Base de données inaccessible. Symptômes : connection refused, « database does not exist ». Correction : démarrez Postgres, vérifiez host/port/user et exécutez les étapes d'initialisation de la base exactement comme indiqué.
Quand un projet est exporté depuis une plateforme, la base de données est souvent la première chose qui casse sur une nouvelle machine. L'objectif est simple : un coéquipier doit pouvoir passer de « j'ai cloné le repo » à « l'app tourne avec des données réelles » sans deviner.
Notez les étapes minimales pour une installation PostgreSQL fraîche, et placez les commandes dans des scripts quand c'est possible. Votre remise doit répondre à quatre questions :
Si vous avez déjà des scripts (cibles Makefile, scripts shell, commandes d'un task runner), utilisez-les plutôt que de décrire des étapes manuelles. Si vous n'en avez pas, ajoutez-en un petit jeu maintenant.
Gardez le flux cohérent entre environnements (local, CI, staging). Une base raisonnable ressemble à ceci :
# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user
# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up
# 3) Seed minimal demo data
./scripts/seed
Pour les seeds, préférez des données minimales et fonctionnelles plutôt qu'un dump proche de la production. Les seeds doivent pouvoir s'exécuter plusieurs fois sans casse (inserts idempotents, ou une règle « exécuter uniquement sur une DB vide »).
Pour les resets, soyez explicite sur la sécurité. Une commande de reset doit cibler par défaut le développement local. Si vous fournissez un script destructeur, ajoutez une garde (par exemple CONFIRM_RESET=1, ou vérifiez APP_ENV=development). Définissez aussi ce que « reset » signifie : drop & recreate, vider des tables, ou restaurer un snapshot connu.
Une remise part en sucette quand le repo ressemble à un tiroir à bazar. Quelqu'un de nouveau doit pouvoir distinguer ce qui compte, ce qui est généré, et où modifier les paramètres.
Commitez ce qui rend le projet reproductible : lockfiles, fichiers de migration, petits modèles de config comme .env.example, et tout script qui bootstrap l'app.
Gardez hors du contrôle de version les fichiers personnels, les fichiers générés ou sensibles : fichiers d'environnement locaux, réglages d'éditeur, output de build, logs, caches, et tout ce qui donne accès (clés API, mots de passe DB, fichiers de compte de service).
Une règle simple : si le modifier impacte tout le monde, commitez-le. Si ça change par machine ou par environnement, documentez et excluez-le du repo.
Si vous ajoutez une courte note « commit vs ignore », restez bref :
README, lockfiles, migrations, scripts de seed, .env.example.env, fichiers de secrets, dossiers de build, logs, caches locauxAjoutez une carte de répertoires courte pour que la structure soit évidente sans fouiller. Exemple : « /backend service API, /web frontend, /mobile app, /db migrations et seeds, /scripts aides d'installation. »
Si vous avez exporté depuis Koder.ai, considérez l'export comme le début d'une passe de nettoyage : enlevez le bazar généré, confirmez les règles d'ignore et rédigez la carte des dossiers.
Une remise échoue silencieusement quand le CI est presque identique au local. Si quelqu'un peut lancer le projet sur son laptop, le CI doit exécuter les mêmes commandes et obtenir le même résultat.
Décidez ce que le CI doit prouver pour chaque pull request. La plupart des équipes ont besoin d'un petit ensemble :
Les tests d'intégration et les étapes de déploiement sont acceptables aussi, mais seulement s'ils sont fiables et clairement limités.
Gardez les étapes CI proches des commandes locales pour éviter la dérive. Si local c'est make test, CI doit aussi lancer make test. Si vous n'avez pas de Makefile (ou équivalent), pensez à en ajouter un et à l'utiliser comme point d'entrée partagé.
Le CI casse souvent parce qu'il dépend d'une configuration cachée. Ajoutez une courte section « variables CI » dans le README listant les noms exacts attendus par la CI. Séparez la config publique des secrets.
Noms d'exemple (à ajuster selon votre stack) : APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. En CI, les secrets doivent provenir du store secret du fournisseur CI, jamais de fichiers committés. Pour un backend Go + Postgres (commun dans les exports Koder.ai), notez aussi si les migrations s'exécutent automatiquement ou nécessitent une étape explicite.
Décidez quelles vérifications sont requises avant merge et écrivez-les. « lint + unit tests + build » suffit généralement. Si vous ajoutez des jobs optionnels (par ex. builds mobile), laissez-les non bloquants sauf si vraiment nécessaires.
Rendez aussi les sorties CI faciles à déboguer : affichez les versions des outils et faites échouer avec des messages clairs. Ajoutez du caching une fois la pipeline stable.
Maya reçoit un projet exporté depuis Koder.ai. C'est une configuration typique : un front React, une API Go et une base PostgreSQL. Elle doit pouvoir cloner et atteindre un écran fonctionnel sans deviner.
Ses 30 premières minutes devraient ressembler à ceci :
.env.example en .env (ou définir les mêmes valeurs dans son shell) pour web et api.Dans une remise embrouillée, elle rencontre généralement trois blocages.
Premier : l'app démarre, puis plante avec une erreur vague « config manquante ». Le vrai problème est une variable non documentée comme AUTH_JWT_SECRET ou un format DATABASE_URL requis. Si le README liste chaque variable requise, montre une valeur d'exemple sûre et explique où elle est utilisée, le problème se résout vite.
Deuxième : l'API démarre, mais toutes les pages montrent « pas de données » ou renvoient des 500. La base existe, mais elle n'a ni tables ni données. Une remise propre inclut une ou deux commandes fiables : lancer les migrations, seed de données minimales, et une commande de reset quand ça tourne mal.
Troisième : tout tourne, mais le frontend pointe vers le mauvais port. Maya ouvre localhost:3000, mais l'API attend localhost:8080, ou CORS bloque les requêtes. C'est là que des valeurs par défaut cohérentes aident : un seul endroit pour définir WEB_PORT, API_PORT, et API_BASE_URL, avec le README indiquant les URLs locales attendues.
Une remise n'est terminée que lorsqu'une autre personne peut exécuter le projet depuis un clone propre sans poser de questions. Prouvez que le projet survit hors de la plateforme.
Faites un dernier test de « clean clone » sur une machine fraîche ou un conteneur jetable. N'utilisez pas votre dossier existant, ni des dépendances en cache, ni une base de données locale. Suivez votre propre README à la lettre. Si vous devez improviser, corrigez la doc ou les scripts jusqu'à ce que vous n'ayez plus à improviser.
Vérifications rapides qui attrapent la plupart des échecs :
.env.example existe et chaque variable requise est expliquée avec une valeur d'exemple sûre.Les pièges courants sont ennuyeux, et c'est pour ça qu'on les oublie :
Étapes suivantes : nommez un responsable pour valider l'export sous 24 à 48 heures, pas des semaines plus tard. Il doit faire le test du clean clone et signaler les manques.
Si vous construisez sur Koder.ai (Koder.ai), traitez cette checklist comme partie intégrante de votre flux de travail : utilisez le mode planning pour noter le chemin d'exécution, prenez des snapshots avant les gros changements, et exportez le source régulièrement pour que le package de remise reste à jour.
Choisissez un point stable et considérez-le comme la source de vérité.
Au minimum, incluez :
.env.example et une documentation claire des variables d'environnementLaissez de côté tout ce qui est sensible et les véritables identifiants.
Documentez chaque variable d'environnement en un seul endroit (généralement le README racine) et fournissez un fichier .env.example.
Pour chaque variable, listez :
Ne commitez pas de secrets. Ne commitez que des placeholders.
Un schéma simple :
.env.example avec des placeholders replace_me.env (ignoré par git)Documentez aussi comment générer chaque secret requis (par exemple : « créez une chaîne aléatoire de 32+ caractères pour »).
Faites tourner à nouveau tout secret qui a pu être partagé ou réutilisé.
Ordre pratique pour la rotation :
.env locauxConsidérez l'export comme un nouvel environnement et repartez à zéro.
Rendez la première exécution « copier, coller, exécuter » :
Si le projet nécessite Docker ou Make, dites-le explicitement—ne laissez pas les gens le découvrir via des erreurs.
Oui — car les versions majeures de PostgreSQL et des outils peuvent modifier le comportement.
Enregistrez au minimum :
Pincez les versions quand c'est possible, et affichez les versions dans la CI pour faciliter le debug des échecs.
Fournissez un chemin répétable « à partir de zéro » :
Ajoutez des garde-fous pour les actions destructrices (par exemple, exiger APP_ENV=development ou un flag de confirmation).
Gardez le CI proche des commandes locales et rendez la configuration explicite.
Si des migrations sont nécessaires pour les tests, documentez si la CI les exécute automatiquement ou non.
Faites un « clean clone » test :
Si vous devez improviser même une fois, corrigez la doc ou les scripts jusqu'à ne plus avoir à improviser. C’est la méthode la plus rapide pour attraper les hypothèses cachées de l'environnement d'origine (y compris les plateformes vibe-coding comme Koder.ai).
JWT_SECRET