Workflow greenfield Claude Code : du dépôt vide à la première tranche verticale

Ce que vous essayez d'éviter avec un démarrage greenfield

Commencer depuis un dépôt vide donne l'impression de liberté, mais cela tourne souvent en chaos : beaucoup de fichiers générés, une build à moitié fonctionnelle, et aucun endroit clair où mettre le prochain changement. Le but d'un workflow greenfield Claude Code est d'éviter ce chaos de la première semaine.

Quelques échecs reviennent souvent :

• Du code qui « fonctionne sur ma machine » parce que la configuration vit dans la mémoire de quelqu'un, et non dans des scripts.
• Un arbre de dossiers qui reflète l'ordre de création des choses, pas la façon dont l'application devrait évoluer.
• Une boucle où chaque nouveau prompt réécrit des choix précédents, de sorte que rien ne devient stable.

Les décisions prises tôt sont douloureuses à annuler car tout s'empile dessus. Une structure confuse se renforce. Une build manuelle devient dix setups différents. Si vous ne verrouillez pas une commande dev simple dès le départ, vous ne pouvez pas distinguer si un changement a cassé l'application ou juste l'environnement.

Quand ce post dit « application en fonctionnement », il désigne quelque chose de précis : une commande unique qui démarre le projet, affiche une sortie prévisible et échoue bruyamment quand quelque chose manque. Vous devriez pouvoir supprimer votre installation locale, cloner le repo, exécuter cette commande et voir le même résultat.

Une « tranche verticale » est la plus petite fonctionnalité bout en bout qui prouve que votre appli est réelle. Ce n'est pas une maquette d'interface. Ce n'est pas seulement une table de base de données. C'est une ligne mince à travers tout le système : une page avec un formulaire, un endpoint API qui enregistre des données, une écriture et une lecture en base, et un résultat visible sur la page.

Si vous pouvez lancer l'app avec une commande et livrer une tranche verticale, vous avez une base sur laquelle itérer sans deviner.

Décidez la première tranche avant de générer quoi que ce soit

Une première tranche claire garde votre repo propre et vos prompts concentrés. C'est le moment de décider ce que vous voulez démontrer bout en bout, pas ce que vous espérez que le produit final devienne.

Choisissez la plus petite story utilisateur qui prouve que l'app fonctionne sur tout le chemin. Une bonne tranche touche l'UI, les données et une action réelle. Exemple : « En tant qu'utilisateur, je peux ajouter une tâche et la voir apparaître dans une liste après rafraîchissement. » C'est minuscule, mais ça force le routage, la validation, le stockage et un écran basique.

Choisissez une plateforme cible pour la semaine 1 et tenez-vous-y. Si vous commencez web, faites uniquement web. N'ajoutez pas d'écrans mobile « au cas où ». Même si vous prévoyez d'utiliser une plateforme comme Koder.ai plus tard, vous aurez de meilleurs résultats si la première tranche reste dans une voie (React web, ou une API Go, ou Flutter).

Définissez ce que « fini pour la semaine 1 » signifie en termes simples :

• S'exécute localement depuis un clone frais avec une commande unique
• Une fonctionnalité fonctionnelle que vous pouvez parcourir de bout en bout
• Les erreurs affichent un message humain (pas une trace de pile)
• Les données persistent quelque part de façon simple (même une base locale)

Puis notez trois non-objectifs qui protègent la portée. Par exemple : pas d'auth, pas de système de thème, pas de jobs en arrière-plan.

Une fois ces décisions écrites, votre prompt de génération peut être strict : construisez uniquement ce qui supporte la tranche, et laissez le reste en TODO.

Quelques décisions préalables qui évitent les retouches

Avant de demander à Claude de générer quoi que ce soit, verrouillez un petit ensemble de valeurs par défaut. Elles semblent mineures, mais évitent le bordel « renommer tout plus tard ».

D'abord, décidez de la forme de l'app. Si vous avez vraiment besoin d'une UI navigateur et d'un backend, commencez avec deux parties claires (frontend + API) et un endroit partagé pour les contrats (types API ou un simple schéma). Si l'app peut être rendue côté serveur en une seule base, gardez un seul codebase pour que le dev local reste simple.

Ensuite, mettez-vous d'accord sur les règles de configuration. Utilisez un fichier env local, gardez-le hors de git, et committez un template à la place (par exemple, .env.example) avec des placeholders sûrs et de courts commentaires. Ça facilite l'onboarding et réduit les fuites de secrets.

Choisissez des ports de dev par défaut et gardez-les stables. Les ports finissent dans les scripts, la doc et les messages d'erreur, donc les changer plus tard est pénible. Faites pareil pour le nommage : dossiers, services et packages doivent suivre une convention. La cohérence compte plus que la « convention parfaite ».

Un petit jeu de décisions de départ :

• Forme de l'app : application unique ou frontend + API
• Config : .env local, .env.example committé
• Ports : un pour le web, un pour l'API, un pour la BDD (si nécessaire)
• Noms : un style de casse pour les dossiers, noms de services cohérents
• Secrets : jamais committés, tournés s'ils sont exposés

Exemple : vous choisissez web sur le port 3000 et api sur le port 8080. Votre template env inclut API_URL=http://localhost:8080 et DATABASE_URL=.... Quand Claude génère des scripts et docs plus tard, tout s'ajuste au lieu de dériver.

Comment prompt-er Claude Code pour garder la structure

Commencez par demander un squelette exécutable, pas « l'application complète ». Le chemin le plus rapide vers une sortie désordonnée est de demander des fonctionnalités avant d'avoir un endroit où les placer.

Soyez explicite sur la structure. Demandez un plan de dossiers avec de courts commentaires qui expliquent ce qui va où et ce qui n'y a pas sa place. Cela force des décisions en amont plutôt que de disperser les fichiers au fil du temps.

Une manière simple de rester discipliné est d'imposer des règles dans le prompt :

• Générez d'abord le plus petit squelette exécutable (page hello, endpoint health, ou un écran).
• Proposez une structure de dossiers et expliquez chaque dossier en 1 phrase.
• Ajoutez des scripts qui fonctionnent sur une machine fraîche (install, dev, test, build) et énoncez les prérequis.
• Gardez les changements dans un seul morceau de la taille d'une PR et listez exactement quels fichiers seront créés ou modifiés.
• Arrêtez après le scaffolding et dites-moi comment l'exécuter.

Voici un prompt réutilisable et modifiable :

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder's README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my "ran it" confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

Puis gardez la boucle courte. Ne demandez pas cinq changements en même temps. Générez une petite modification, exécutez-la, collez l'erreur exacte (ou le succès), puis demandez une correction minimale. Ce rythme générer-exécuter-ajuster garde le projet prévisible et réduit la dérive de la structure.

Étape par étape : du dépôt vide à un squelette exécutable

Commencez par une promesse : n'importe qui peut cloner le repo et exécuter une commande pour voir quelque chose fonctionner. Cela vous donne une base stable avant de demander à une IA d'ajouter de vraies fonctionnalités.

Créez le repo et écrivez un README minime pendant que tout est frais. Restez pratique : prérequis, la commande dev unique, et comment lancer les tests (même si les tests sont vides pour l'instant).

Ensuite, choisissez une disposition de haut niveau qui correspond à la forme d'app que vous avez choisie.

Si vous construisez plusieurs pièces déployables (par exemple frontend + API), une disposition workspace peut aider :

/
  apps/
  packages/
  scripts/
  docs/
  README.md

Si vous construisez une application unique, faites plus simple et évitez des niveaux supplémentaires tant que vous n'en avez pas besoin.

Ajoutez maintenant les garde-fous minimaux pour que le code reste cohérent. Choisissez un formateur et un linter, acceptez leurs défauts, et ajoutez un seul fichier de config pour chacun. L'objectif est d'avoir des diffs propres, pas des règles parfaites dès le jour un.

Rendez l'expérience développeur prévisible avec une commande qui marche toujours depuis la racine du repo. Voici une forme simple :

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

Avant de générer autre chose, exécutez cette commande dev, confirmez qu'elle s'exécute proprement (ou lance un serveur placeholder), puis faites votre premier commit contenant seulement le scaffolding. Si un coéquipier (ou votre futur vous) peut reproduire la configuration depuis zéro, vous êtes prêt à construire la première tranche.

Une structure de dossiers qui tient à mesure que l'app grandit

Une bonne structure greenfield fait deux choses : elle aide à retrouver le code rapidement, et elle donne moins de liberté à Claude pour inventer de nouveaux patterns à chaque requête. L'objectif n'est pas la perfection. C'est la stabilité.

Si vous travaillez dans une application unique (ou dans un dossier apps/<name>/), une disposition interne simple tient généralement bien :

• src/ code applicatif (features, éléments partagés, points d'entrée)
• config/ configuration non secrète
• tests/ tests de haut niveau qui lisent comme un comportement utilisateur
• scripts/ scripts utilitaires (setup dev, reset BDD, tâches de release)
• docs/ notes et checklists courtes que vous maintenez réellement

Dans src/, séparez le code feature du code partagé selon les schémas de changement. Le code feature change souvent et doit rester proche. Le code partagé doit être terne et réutilisable.

Règle pratique : mettez les écrans UI, handlers et logique spécifique dans src/features/<featureName>/.... Mettez des éléments comme le logging, clients API, composants de design system et utilitaires génériques dans src/shared/.... Si un helper n'a de sens que pour une feature, gardez-le dans cette feature même s'il semble réutilisable. Déplacez-le plus tard quand vous aurez un second vrai usage.

Les noms de dossiers doivent décrire le but, pas la techno. « features » et « shared » restent signifiants quand votre stack change. Évitez des noms comme « misc » ou « new ».

Gardez docs/ petit. Un bon démarrage est docs/checklists.md avec quelques lignes : comment lancer, comment tester, comment ajouter un nouveau dossier feature, et ce que « fini » signifie.

Scripts de build qui rendent le projet prévisible

Un repo paraît réel quand n'importe qui peut exécuter les mêmes commandes et obtenir le même résultat. Les scripts sont des garde-fous : ils réduisent les hypothèses, rendent les changements petits et rendent évident quand quelque chose casse.

Commencez par un petit ensemble de commandes et gardez-les ennuyeuses. Si quelqu'un de nouveau rejoint (ou que vous revenez dans deux semaines), il ne devrait pas avoir besoin d'options spéciales ou d'étapes cachées.

Voici une base simple adaptable à n'importe quel stack :

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

Faites du script dev le chemin heureux. Il doit démarrer l'app, afficher où elle tourne et garder les logs lisibles. Si le serveur ne peut pas démarrer, échouez vite avec un message clair (variable d'env manquante, port déjà utilisé, base de données inaccessible).

Le script build doit toujours créer un répertoire de sortie propre. Supprimez l'ancien output d'abord, puis produisez des artefacts frais. Cela évite des bugs étranges causés par des fichiers laissés par hier.

Pour les tests, séparez les vérifications rapides des vérifications lentes. Les tests rapides s'exécutent à chaque changement (unit tests, vérifs de types). Les tests complets incluent les checks d'intégration et s'exécutent avant une merge.

Gardez le style cohérent avec une commande unique. Une règle simple : format corrige, lint se plaint.

Enfin, ajoutez une vérification smoke qui valide les bases avant que vous perdiez du temps à déboguer :

• Les vars d'env requises sont définies (et non vides)
• Les ports choisis sont libres
• L'app peut démarrer et répondre à une requête simple
• La connexion à la base fonctionne (si utilisée)
• La sortie de build existe après build

Construire la première fonctionnalité tranche verticale

Votre première tranche verticale doit prouver que l'app fonctionne bout en bout, pas seulement que l'UI est jolie. Cela signifie une petite fonctionnalité qui touche l'écran, la logique et une forme de stockage, même temporaire.

Choisissez quelque chose d'ennuyeux et utile, comme « Ajouter une note » ou « Créer une tâche ». Gardez-le assez petit pour être fini en une session, mais complet pour pouvoir cliquer et voir un changement d'état réel.

Une bonne tranche a quatre parties : une route ou un écran, un formulaire, une action de sauvegarde et un affichage. Exemple : une page « Nouvelle Tâche » avec un champ titre, un bouton Enregistrer qui appelle une seule fonction, et une liste qui affiche les tâches sauvegardées.

Commencez par un magasin placeholder pour aller vite. Un tableau en mémoire, un fichier JSON local ou une interface stub simple suffisent. L'important est de créer la frontière que vous remplacerez plus tard. Si aujourd'hui votre code appelle taskRepository.save(task), passer à une vraie base plus tard devient un petit changement, pas une réécriture.

Gardez l'UI basique. Ignorez les débats sur le design system, les états vides et les animations.

Vérifications d'acceptation rapides à faire en deux minutes :

• La page s'ouvre sans erreurs
• Vous pouvez saisir une valeur et presser Enregistrer
• Le nouvel élément apparaît immédiatement
• Le rechargement affiche le comportement attendu (persisté si stockage réel, réinitialisé si fake)
• Les mauvaises entrées sont gérées (titre vide affiche un message et ne sauvegarde pas)

Rendre le projet suffisamment stable pour itérer

Après avoir un squelette exécutable et une tranche verticale, l'objectif change : rendre les pannes évidentes et les corrections rapides. C'est là que beaucoup de démarrages greenfield échouent, non pas parce que la fonctionnalité est difficile, mais parce que de petits changements commencent à créer des surprises.

Fixez une petite barre de stabilité à atteindre chaque fois que vous ajoutez une tranche :

• Un smoke test qui prouve que l'app démarre et que la route/écran principal se rend
• Un smoke test qui exerce la tranche bout en bout (même si ça utilise une base de test)
• Des messages d'erreur clairs qu'un utilisateur normal peut comprendre (pas des traces de pile)
• Des logs dev qui expliquent ce qui s'est passé sans exposer de secrets
• Dépendances minimales, versions figées, mises à jour faites volontairement

Exemple concret : votre première tranche permet à un utilisateur de créer un « Projet » et de le voir dans une liste. Ajoutez un test qui démarre le serveur, appelle l'endpoint de création, puis récupère la liste et vérifie que le nouvel élément apparaît. Si ça échoue, que ça échoue bruyamment avec un message utile, comme « Create Project endpoint returned 500 », pas un mur de texte.

Pour la gestion des erreurs, limitez-vous à un petit ensemble de réponses cohérentes. Les erreurs de validation retournent un message court (« Le nom est requis ») et le nom du champ. Les erreurs inattendues retournent « Quelque chose s'est mal passé. Réessayez. » Détaillez dans les logs.

Le logging est le plus utile quand il répond : quelle requête, quel utilisateur (ou anonyme), qu'est-ce qui a échoué et où. En dev, incluez un id de requête et la durée, mais évitez de dumper tokens, mots de passe, clés API ou payloads complets par défaut.

Ajoutez une petite vérification de santé. Sur le web, cela peut être un endpoint /health qui retourne ok. Sur mobile, un état « Connecté » qui bascule sur « Hors ligne » quand l'app ne peut pas joindre le backend. C'est un signal rapide avant de déboguer la mauvaise chose.

Pièges courants lors de l'utilisation d'IA pour des projets greenfield

La manière la plus rapide de gaspiller un démarrage greenfield est de demander au modèle une app complète, puis de l'exécuter plus tard. Les grosses générations cachent de petites erreurs : dépendances manquantes, chemins d'import incorrects, scripts qui supposent des outils non installés. Traitez chaque sortie comme quelque chose que vous devriez pouvoir exécuter en quelques minutes.

Un autre piège est de concevoir l'architecture parfaite avant d'avoir une fonctionnalité. Débattre des noms de dossiers semble productif, mais sans une vraie tranche vous ne saurez pas ce qui est gênant. Une structure simple qui supporte un chemin fonctionnel vaut mieux qu'une structure intelligente non testée.

La dérive des commandes arrive aussi. L'IA ajoute une nouvelle façon de démarrer le serveur, vous en ajoutez une autre pour les tests, et bientôt personne ne sait quelle est « la » commande. Si un coéquipier clone le repo et demande « Comment je lance ça ? », vous payez déjà les intérêts.

Erreurs qui causent le plus de retouches :

• Générer plusieurs services, écrans et configs en une fois au lieu de construire un chemin exécutable d'abord
• Intégrer auth, paiements, styling complexe et un modèle de données complet avant que la première fonctionnalité ne marche bout en bout
• Laisser les instructions de setup dans le chat au lieu de scripts (ou d'un README)
• Oublier un template env propre, si bien que la machine suivante ne peut pas démarrer sans deviner

Un exemple simple : vous générez une app « complète » avec login, theming et facturation, mais la première exécution échoue parce qu'une clé secrète manque et il n'y a pas de .env.example. Vous passez alors une heure à réparer le setup au lieu d'apprendre si la fonctionnalité est utile.

Restez honnête : une commande exécutable, une petite feature, un template env, puis étendez.

Checklist rapide avant d'itérer

Avant d'ajouter « une fonctionnalité de plus », assurez-vous que le projet est facile à reprendre demain (ou par quelqu'un d'autre). La rapidité n'est pas le seul but. La prévisibilité l'est.

• Une commande unique : un nouveau dev peut copier un template env, définir les quelques valeurs requises et démarrer l'app avec une seule commande. Si des étapes supplémentaires sont nécessaires (setup BDD, migrations, données seed), capturez-les dans un script.
• Les scripts couvrent l'essentiel : commandes claires pour dev, test, build, et une vérification smoke rapide.
• Structure évidente : la disposition raconte une histoire (code app, config, scripts, tests) sans lire tout le code.
• Chemin de démo tranche verticale : vous pouvez décrire la démo en une phrase, comme « créer un élément, le voir dans une liste, rafraîchir, il est toujours là. »
• Point de rollback : avant gros changements, vous avez un point sûr pour revenir (un commit propre, un tag ou un snapshot/mécanisme de rollback).

Si un item échoue, corrigez-le maintenant. Reserrer scripts et noms coûte peu quand le repo est petit.

Étapes suivantes : transformer le workflow en habitude répétable

Un démarrage greenfield ne paye que si vous pouvez le répéter. Après que votre première tranche verticale fonctionne bout en bout, figez les bonnes parties dans un petit template : mêmes patterns de dossiers, mêmes noms de scripts et même façon de relier UI, API et données.

Considérez votre première tranche comme une implémentation de référence. Quand vous démarrez la tranche #2, copiez la forme, pas le code. Si la tranche #1 a une route, un handler, une couche d'accès aux données et un test basique, la tranche #2 doit suivre le même chemin.

Gardez la planification légère. Une note d'une page suffit pour les 2–3 tranches suivantes : l'objectif et l'action utilisateur pour chaque tranche (une phrase), les données nécessaires, les critères de « done » et les risques à tester tôt.

Puis faites de la maintenance une habitude. Une fois par semaine, faites une courte passe : resserrez les scripts, mettez à jour le README avec les nouveaux pas de setup, et rafraîchissez votre fichier env example pour que l'onboarding reste simple.

Si vous préférez une boucle de construction centrée chat, Koder.ai (koder.ai) est une option qui prend en charge le mode planning plus les snapshots et rollback, et peut exporter le code source quand vous voulez déplacer le projet ailleurs.

Le but est un workflow que vous pouvez exécuter sans réfléchir : planifiez 2–3 tranches, construisez une tranche, stabilisez, répétez.