Ce chapitre t'apprend la méthode de planification en 2 documents qui transforme une idée vague en feature livrée sans surprise. C'est 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. Ce ratio est vérifié sur des dizaines de features construites.
La méthode en 2 documents
Document 1, le Design Doc (le QUOI)
C'est 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 va proposer 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 n'ont pas le temps de publier tous les jours.
Streak hebdomadaire (recommandé par Claude)
→ Plus flexible, adapté au rythme des freelances (1-2 posts/semaine). Tolérant sur les jours mais 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.
C'est toi qui choisis. C'est là que ta connaissance métier fait toute 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
- Problème : pourquoi cette feature est nécessaire
- Solution choisie : l'approche retenue avec justification
- User stories : ce que l'utilisateur voit et fait à chaque étape
- Règles métier : la logique précise (ex: "un streak est cassé si aucun contenu publié pendant 14 jours")
- Hors périmètre : ce qu'on ne fait PAS dans cette version (important pour éviter le scope creep)
Document 2, le Plan d'implémentation (le COMMENT)
C'est 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. 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érifier visuellement
Tâche 5 : Intégration dans le dashboard
Fichier : src/app/app/page.tsx
Vérification : vérifier 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 métier, 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. C'est plus rapide que la méthode design doc + plan pour les features qui ne nécessitent pas 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é (qu'il soit dans un fichier ou dans le 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. C'est 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.