Construire un projet complet piloté par Claude Code

Vous maîtrisez les briques de Claude Code une par une : CLAUDE.md, mode plan, skills, hooks. Reste la question qui compte : comment les enchaîner pour construire un projet entier, pas juste une tâche isolée. Ce guide donne la méthode de bout en bout, illustrée par un déroulé réel sur lab-claude. C'est le fil qui relie toute la formation.

Ce que vous allez apprendre

Découper un projet en tranches verticales livrables une à une
Dérouler la boucle plan, implémentation, validation sur chaque tranche
Mettre CLAUDE.md, skills et hooks au service du projet
Garder le contrôle et livrer proprement

Prérequis

Le projet fil rouge lab-claude en place
Un premier workflow borné déjà déroulé
Claude Code à jour (déroulé vérifié en v2.1.152)

La règle d'or : penser en tranches verticales

La pire façon de piloter Claude Code sur un projet est de lui demander « construis l'application ». Le résultat dérive, le diff devient illisible, et vous perdez le contrôle. La bonne méthode consiste à découper en tranches verticales : des morceaux complets et livrables qui traversent toute la pile, du modèle de données au test.

Une tranche verticale, c'est par exemple « ajouter la suppression d'un item » : le store, la route, et les tests, ensemble. Pas « écrire tous les modèles », puis « écrire toutes les routes ». Chaque tranche est petite, validable et réversible par un commit. Vous construisez le projet tranche par tranche, en gardant le projet vert à chaque étape.

Les phases d'un projet piloté

Sur l'ensemble du projet, six phases s'enchaînent. Les quatre premières se font une fois, les deux dernières se répètent à chaque tranche.

Cadrer : décrire l'intention, les contraintes et le périmètre. Ce que fait le projet, pour qui, avec quelle pile.
Scaffolder : créer le squelette (dépendances, structure, outils de test), comme le fil rouge lab-claude.
Poser les règles : un CLAUDE.md qui donne conventions, commandes et garde-fous, pour ne pas les répéter à chaque session.
Installer les garde-fous : une skill de validation, des hooks qui lancent lint et tests automatiquement.
Boucler par tranche : pour chaque tranche, plan, implémentation, validation (la section suivante).
Livrer : revue, préparation de PR, intégration CI.

Lab : une tranche verticale de bout en bout

Le projet lab-claude gère des items (création, liste, lecture) mais pas la suppression. On ajoute cette tranche en pilotant Claude Code, en deux temps.

Temps 1, le plan. On demande un plan sans coder, pour valider l'approche avant tout changement :

> Sans modifier aucun fichier, établis un plan court pour ajouter
  DELETE /items/{id} (204 si supprimé, 404 si absent) plus le test.

Claude produit un plan situé et précis, qui montre qu'il a compris le projet :

## Fichiers à toucher
- app/routers/items.py - méthode _Store.delete + handler DELETE /{item_id}
- tests/test_items.py - 2 tests (204 happy path, 404 absent)

## Points de vigilance
- L'isolation est déjà assurée par la fixture autouse _reset_items_store
- Garder l'ordre CRUD des handlers (list, create, get, delete)

Le plan repère seul la fixture de test existante et l'ordre des handlers : c'est l'intérêt de passer par le plan, il révèle ce que Claude a compris avant d'écrire une ligne.

Temps 2, l'implémentation validée. On laisse Claude implémenter et valider dans la foulée :

> Implémente la suppression selon le plan, puis lance
  uv run ruff check . et uv run pytest -q. Résume.

## Résumé
Fichiers modifiés :
- app/routers/items.py - méthode _Store.delete + route DELETE /items/{item_id}
- tests/test_items.py - 2 tests ajoutés

Résultat :
- uv run ruff check .  -> All checks passed
- uv run pytest -q     -> 12 passed in 0.06s

La tranche est complète et verte : code, tests, lint, en un cycle borné. C'est l'unité de travail à répéter pour construire tout le projet. Chaque tranche se termine par un commit, et le projet reste livrable en permanence.

Mettre les briques au service du projet

Le pilotage devient fluide quand les briques travaillent pour le projet :

CLAUDE.md porte les faits : « on utilise FastAPI, uv, Ruff, pytest ». Claude n'a plus à les redécouvrir.
Une skill /valider rejoue lint et tests à la demande, et une skill /prep-pr prépare la revue. Ce sont les routines réutilisables du projet.
Des hooks lancent ruff et pytest automatiquement après chaque modification, sans y penser.
Les subagents isolent une exploration lourde (comprendre un module inconnu) sans polluer le contexte de la tranche en cours.

Ces briques transforment chaque tranche en routine sûre : le projet se construit vite parce que les garde-fous tournent en arrière-plan.

Garder le contrôle

Piloter ne veut pas dire déléguer en aveugle. Trois disciplines, détaillées dans le mode plan, diff et validations, tiennent le cap :

Le plan d'abord sur toute tranche non triviale : vous validez l'approche avant le code.
Le diff systématique : vous relisez chaque changement. Une tranche petite rend cette relecture possible.
Le périmètre strict : une tranche = un objectif. Si Claude veut en faire plus, vous recadrez.

Livrer

Une fois quelques tranches en place, la livraison s'industrialise. La skill /prep-pr résume le diff et propose un titre de PR ; le mode headless en CI rejoue lint, tests et revue automatique sur chaque pull request. Le projet passe du poste local au pipeline sans changer de méthode : ce sont les mêmes tranches, validées par les mêmes garde-fous.

Pièges fréquents

Piège	Conséquence	Correction
« Construis l'application »	Diff illisible, dérive	Découper en tranches verticales
Coder sans plan	Mauvaise approche découverte trop tard	Demander le plan d'abord
Tranches horizontales (tous les modèles, puis toutes les routes)	Rien n'est livrable avant la fin	Tranches verticales, vertes à chaque étape
Pas de garde-fous	Régressions silencieuses	Skill de validation + hooks lint/tests
Relire un diff énorme	Revue bâclée	Garder chaque tranche petite

À retenir

Construisez par tranches verticales : petites, complètes, vertes, réversibles.
Sur chaque tranche : plan, puis implémentation, puis validation dans le même cycle.
Le plan d'abord révèle ce que Claude a compris avant d'écrire du code.
CLAUDE.md, skills et hooks font tourner les garde-fous en arrière-plan.
Gardez le contrôle par le diff systématique et un périmètre strict.
La même méthode sert du poste local à la CI.

Prochaines étapes

Mode plan, diff et validations La discipline de contrôle sur chaque tranche

Skills : routines réutilisables Vos /valider et /prep-pr au service du projet

Hooks Claude Code Lancer lint et tests automatiquement à chaque tranche

Mode headless et CI Industrialiser la livraison sur chaque PR