Ce chapitre t'apprend la méthode de planification en 2 documents qui transforme une idée vague en feature livrée sans surprise. Ce qui fait la différence entre un résultat aléatoire et un résultat prévisible. Temps de lecture : 10 minutes.
Pourquoi c'est non négociable
La plus grosse erreur des débutants : demander directement "construis-moi cette feature". Sans plan, Claude va :
- Faire des choix techniques sans te consulter (et tu les découvriras trop tard)
- Potentiellement casser des fonctionnalités existantes sans s'en rendre compte
- Produire quelque chose qui ne correspond pas à ta vision parce qu'il a interprété différemment
- T'obliger à tout refaire en perdant le travail déjà fait
Le ratio magique : 10 minutes de planification = 2 heures de retravail évitées. Ratio vérifié sur des dizaines de features construites.
La méthode en 2 documents
On part d'un exemple concret : un système de streak de publication pour freelances. On le tire du brainstorm initial jusqu'au plan exécutable.
Document 1, le Design Doc (le QUOI)
La vision produit. Il répond à : qu'est-ce qu'on construit, pour qui, et pourquoi ?
Tu démarres par un brainstorm :
"Brainstorme un système de streak de publication. Contexte : les freelances publient 1-2 fois puis abandonnent. Je veux un système gamifié qui les pousse à publier régulièrement."
Claude propose 3-4 approches avec les avantages et inconvénients de chacune :
Streak quotidien (style Duolingo)
Simple à comprendre mais punitif, un jour raté = tout perdu. Inadapté aux freelances qui ne peuvent pas publier tous les jours.
Streak hebdomadaire (recommandé par Claude)
Plus flexible, adapté au rythme freelance (1-2 posts/semaine). Tolérant sur les jours, exigeant sur la régularité.
Système de points + niveaux
Gamification riche avec progression visible, mais plus complexe à implémenter et potentiellement distrayant par rapport au cœur de l'app.
Toi tu choisis. Ta connaissance métier fait la différence, tu sais ce qui motivera tes utilisateurs. Claude rédige ensuite le design doc final avec ton choix.
Ce que contient le design doc
Exemple concret pour le streak hebdomadaire :
- Problème : 80% des freelances qui s'inscrivent arrêtent de publier après 2 semaines. On veut installer une habitude.
- Solution choisie : streak hebdomadaire, se valide avec 1 publication par semaine du lundi au dimanche.
- User stories : "Quand je publie un contenu, mon compteur passe à +1. Quand j'atteins 4 semaines consécutives, je reçois un badge. Quand je rate une semaine, le compteur repart à 0 mais je vois mon best streak."
- Règles métier : une semaine = lundi 00h à dimanche 23h59 (fuseau user). Le streak se casse si aucune publication valide sur une semaine complète.
- Hors périmètre : pas de classement entre users, pas de notification push, pas de rewards monétaires. Reporté en v2.
Document 2, le Plan d'implémentation (le COMMENT)
La feuille de route technique. Il répond à : quelles tâches, dans quel ordre, avec quelles vérifications ?
Tu demandes :
"Écris le plan d'implémentation détaillé pour le streak hebdomadaire décrit dans docs/plans/2026-03-01-streak-design.md. Liste chaque tâche avec les fichiers à créer ou modifier, les commandes de vérification, et l'ordre d'exécution."
Claude produit un plan numéroté :
Tâche 1 : Migration SQL, créer la table streaks avec colonnes user_id, current_streak, best_streak, last_publication_date
Fichier : supabase/migrations/20260301_streaks.sql
Vérification : npx supabase migration up --local
Tâche 2 : Régénérer les types TypeScript
Commande : npx supabase gen types typescript --local > src/lib/types/database.types.ts
Vérification : npm run typecheck
Tâche 3 : Server Action, calculer et mettre à jour le streak courant
Fichier : src/lib/actions/streak.ts
Vérification : npm run typecheck && npm run lint
Tâche 4 : Composant UI, flamme animée + compteur
Fichier : src/components/dashboard/publishing-streak.tsx
Vérification : npm run typecheck + vérification visuelle
Tâche 5 : Intégration dans le dashboard
Fichier : src/app/app/page.tsx
Vérification : tester visuellement sur localhost:3000
Tâche 6 : Tests unitaires
Fichier : tests/unit/actions/streak.test.ts
Vérification : npm run test
Ce qui rend un plan solide
- Chaque tâche a un seul objectif clair
- L'ordre respecte les dépendances (la base de données avant la logique, la logique avant l'UI)
- Chaque tâche a une commande de vérification spécifique
- Les tâches indépendantes sont identifiées (peuvent tourner en parallèle)
Où sauvegarder les plans ?
Crée un dossier docs/plans/ dans ton projet. Nomme chaque fichier avec la date et le nom de la feature :
docs/plans/
2026-03-01-streak-design.md ← le design doc
2026-03-01-streak-plan.md ← le plan d'implémentation
2026-02-28-notifications-design.md
2026-02-28-notifications-plan.md
Ces fichiers servent de documentation vivante du projet. Quand tu te demandes "pourquoi on a fait ce choix ?", la réponse est dans le design doc.
Alternative rapide : le mode plan natif
Pour les features de taille moyenne, Claude Code intègre un mode plan natif qui évite de créer des fichiers séparés :
- Shift+Tab dans le chat pour activer le mode plan
- Ou tape
/plansuivi de ta description
Claude produit un plan directement dans le chat, attend ta validation, puis exécute. Plus rapide que la méthode design doc + plan pour les features qui n'ont pas besoin de documentation durable.
Quand utiliser quoi ? Feature complexe ou structurante → design doc + plan
dans docs/plans/. Feature moyenne ou correction → mode plan natif
(Shift+Tab).
Exécuter le plan
Une fois le plan validé (fichier ou chat), une seule phrase suffit :
"Exécute le plan dans docs/plans/2026-03-01-streak-plan.md"
Claude lit le plan, exécute chaque tâche séquentiellement, vérifie entre chaque étape, et te demande validation aux moments clés (typiquement : choix de design UI, logique métier ambiguë).
Tu supervises au lieu de piloter ligne par ligne. La différence entre un manager qui fait le travail lui-même et un manager qui délègue efficacement.
Gérer les imprévus pendant l'exécution
Parfois, le plan ne survit pas au contact avec la réalité. Voici comment gérer les cas courants :
| Situation | Réaction |
|---|---|
| Une vérification échoue | Claude corrige automatiquement et recommence. Si ça échoue 2 fois, il te demande de l'aide. |
| Tu changes d'avis sur un choix de design | Dis-le immédiatement. Claude s'adapte et ajuste le reste du plan en conséquence. |
| Une tâche est plus complexe que prévu | Claude la découpe en sous-tâches et continue. |
| Tu découvres un besoin non prévu | Ajoute-le au plan : "Ajoute une tâche 7 : envoyer un email de félicitations quand le streak atteint 4 semaines." |
À retenir : brainstorm → design doc → plan → exécution. Cette séquence est imbattable. Elle transforme une idée vague en feature livrée, prévisible, et conforme à ta vision.