Tous les tutoriels Claude Code enseignent les mêmes 5 choses. Aucune ne fonctionne en production.
Six mois. Deux apps SaaS. Environ 400 sessions. Et ce qui empêche vraiment mon code de partir en fumée ? Absent de tous les tutoriels.
TL;DR : Les tutoriels Claude Code vous apprennent l'installation et les fonctionnalités. La production vous apprend la discipline, la gestion du contexte, et quand tuer vos propres sessions. Le fossé entre "ça marche en démo" et "ça part en prod" fait perdre des semaines à la plupart des devs. Voici ce que j'ai appris à mes dépens pour que vous n'ayez pas à le faire.
La Checklist des Tutoriels (et Pourquoi Elle Plafonne à la Deuxième Semaine)
Tous les guides suivent le même schéma. Installer Claude Code. Créer un CLAUDE.md. Apprendre les commandes slash. Peut-être configurer un flux multi-worktree si l'auteur se sent ambitieux. La démo fonctionne. Le lecteur se sent puissant. Le tutoriel se termine.
Deux semaines plus tard, la réalité défonce la porte.
Je le sais parce que j'ai vécu cette trajectoire. Mon premier mois avec Claude Code était la lune de miel — tout semblait magique, chaque fonction générée ressemblait à du travail gratuit. Puis la migration Convex est arrivée.
J'ai demandé à Claude de refactoriser mon middleware d'auth d'un flux Supabase custom vers Clerk. Tâche simple. Instructions claires. Claude a produit 380 lignes de code propre, typé, bien documenté. Il a même ajouté des commentaires expliquant pourquoi chaque fonction existait.
Un problème : il importait depuis @clerk/nextjs/server au lieu de @clerk/nextjs/api — une distinction qui compte si vous utilisez les fonctions serveur Convex, qui n'ont pas accès à l'objet request de Next.js. Le code compilait très bien en local. Les tests passaient parce qu'ils mockaient le mauvais contexte. J'ai déployé, le dashboard est devenu blanc, et j'ai passé 4 heures à débugger un chemin d'import.
Aucun tutoriel ne m'avait préparé à ça. Parce que les tutoriels testent les fonctionnalités. La production teste les hypothèses.
Votre CLAUDE.md Est Probablement Trop Long
Le sujet de tutoriel le plus populaire dans l'écosystème Claude Code est "comment écrire un bon CLAUDE.md". Et presque tous les exemples que j'ai vus font la même erreur : ce sont des romans.
Je comprends. Vous voulez que Claude connaisse tout de votre projet. Votre stack, vos conventions, votre philosophie de test, votre schéma de nommage de variables préféré, vos opinions sur tabs vs espaces (espaces, évidemment — je ne suis pas un animal).
Mon premier CLAUDE.md faisait 847 lignes. J'en étais fier. J'avais documenté chaque pattern de fonction Convex. Chaque handler de webhook Clerk. Chaque format de politique RLS Supabase. Je pensais donner à Claude le contexte ultime.
Ce que je faisais en réalité, c'était diluer chaque instruction au point de la rendre insignifiante.
Claude lit votre CLAUDE.md à chaque session. Tout. Et si vous avez déjà regardé le compteur de tokens, vous savez qu'un fichier de contexte de 847 lignes bouffe environ 3 000 tokens avant que Claude n'écrive un seul caractère. C'est 3 000 tokens de votre fenêtre de contexte qui disparaissent. Sur une session de refactoring complexe, vous atteindrez la limite 30-40% plus vite — ce qui signifie que Claude oublie votre vraie conversation plus tôt tout en se souvenant parfaitement de vos opinions sur les points-virgules.
Mon CLAUDE.md actuel fait 127 lignes. Je l'ai réduit de 85%.
Ce qui a survécu :
- Déclaration de stack (8 lignes) — Convex, Clerk, Supabase, Next.js 15, Tailwind. Pas d'explications. Juste les noms et versions.
- Limites strictes (12 lignes) — des trucs qui déclenchent un
git checkout .immédiat s'ils sont violés. Mauvais provider d'auth. Mauvais client de base de données. Mauvaise cible de déploiement. Ce ne sont pas des préférences. Ce sont des murs porteurs. - Règles de structure de fichiers (15 lignes) — où vont les choses. Fonctions Convex dans
/convex, routes API dans/app/api, types partagés dans/lib/types. Claude adore inventer de nouveaux répertoires. Ça l'arrête. - Le template de contrat (20 lignes) — Objectif, Contraintes, Format de Sortie, Conditions d'Échec. Chaque tâche commence par là. J'ai écrit tout un article là-dessus, donc je ne vais pas répéter — mais ce seul ajout a fait passer mon taux de revert de 1 sur 3 à 1 sur 10.
Tout le reste — le guide de style, la philosophie de test, les 40 lignes sur les patterns de gestion d'erreur — a été déplacé vers des prompts spécifiques à la tâche que je colle seulement quand c'est pertinent. Claude n'a pas besoin de vos opinions sur la gestion d'erreur quand il écrit un composant UI.
CLAUDE.md plus court = plus de place pour la vraie conversation = moins d'hallucinations en milieu de tâche. Les tutoriels ne vous le diront pas parce que "écrivez moins" n'est pas un titre sexy.
La Boucle de Checkpoint
Une tâche, une session. Commit avant, commit après. Tuer la session quand la tâche est finie.
C'est tout le système. Laissez-moi expliquer pourquoi chaque partie compte.
Les sessions Claude Code ont une durée de vie. Pas une limite stricte — vous pouvez techniquement continuer pendant des heures. Mais quelque part autour de la barre des 45 minutes, ou après 15-20 messages d'aller-retour, la qualité chute. Pas dramatiquement. Subtilement. Claude commence à répéter des patterns du début de la conversation. Il référence du code qu'il a écrit 30 messages plus tôt que vous avez depuis modifié. Il "se souvient" des contraintes du début de session mais oublie les raffinements que vous avez ajoutés en cours de route.
J'appelle ça la dégradation du contexte. La fenêtre de contexte est techniquement toujours là, mais l'attention du modèle est étalée sur trop de messages, et les instructions les plus récentes commencent à rivaliser avec les déchets accumulés d'une session d'une heure.
Et voici la partie dont j'ai honte : pendant mon premier mois, je committais une fois par fonctionnalité. Parfois une fois par jour. Je faisais assez confiance à la sortie de Claude pour continuer à construire dessus, session après session, sans checkpoints.
Puis un jeudi après-midi, Claude a refactorisé une query Convex qui a cascadé dans quatre composants, cassé le server-side rendering sur trois pages, et je n'avais aucun état propre vers lequel revenir. Le dernier commit datait de 6 heures de travail. J'ai passé la soirée à faire git diff ligne par ligne, en cherry-pickant manuellement quels changements garder.
Maintenant le workflow ressemble à ça :
git add -A && git commit -m "checkpoint before claude session"- Ouvrir Claude Code. Coller le contrat pour cette tâche spécifique.
- Faire le truc. Revoir la sortie. Lancer les tests.
git add -A && git commit -m "task: clerk webhook handler"- Fermer la session. En ouvrir une nouvelle pour la tâche suivante.
Pas "une fonctionnalité". Une tâche. "Ajouter le handler de webhook pour la création d'utilisateur Clerk" est une tâche. "Construire tout le flux d'auth" est un projet qui devrait être 4-6 sessions.
Mon git log a l'air dérangé — 15-20 commits par jour, des messages comme "checkpoint before auth refactor" et "task: add clerk webhook, tests pass". C'est moche. C'est aussi une machine à remonter le temps. Quand Claude fait quelque chose de mal et que vous revertez, la session suivante commence depuis un état connu-bon avec zéro confusion résiduelle. Session fraîche + git propre = Claude opérant sur la réalité au lieu des débris de sa tentative précédente.
Les tutoriels vous montrent une seule session glorieuse où tout clique. La production, c'est cinquante sessions courtes où chacune commence proprement et finit committée.
Déclarez Vos Surfaces Adjacentes (ou Perdez une Journée)
Avant toute tâche Claude Code, écrivez trois lignes comme ça :
## Code Adjacent
- /convex/payments.ts → gère le webhook Stripe, écrit dans la table "payments"
- /app/dashboard/revenue.tsx → lit depuis la table "payments", groupe par mois
- /convex/notifications.ts → se déclenche sur l'insertion de payment via fonction Convex programmée
C'est tout. Chemins de fichiers et une ligne sur ce qui les intéresse. Deux minutes. Collez ça dans votre contrat de prompt sous "Code Adjacent".
Pourquoi ? Parce que tous les tutoriels font la démo de Claude Code sur des fonctionnalités isolées. "Construisons une app todo !" "Ajoutons l'authentification !" En production, rien n'est isolé. Votre webhook Clerk parle à votre mutation Convex qui déclenche une edge function Supabase qui envoie un email via Resend qui log vers votre composant dashboard. Touchez-en un, et trois autres tressaillent.
J'ai appris ça à mes dépens. Claude a fait une refactorisation correcte de mon flux de paiement — code propre, tous les tests passés — qui a silencieusement cassé le graphique de revenus du dashboard. Parce qu'il ne savait pas (et je ne lui avais pas dit) que le dashboard lisait depuis la même table Convex avec un pattern de query différent. Le fix a pris 20 minutes. Trouver le bug a pris un jour et demi.
Claude n'a pas besoin de lire les fichiers adjacents. Il a juste besoin de savoir qu'ils existent. C'est suffisant pour qu'il signale "changer ce schéma de table va affecter ces 3 fichiers" au lieu de bulldozer silencieusement votre dashboard.
La Récupération d'Erreur, C'est Là Que Vous Perdez Vraiment du Temps
Les tutoriels montrent le chemin heureux. Demande de fonctionnalité → Claude génère du code → les tests passent → on ship. L'hypothèse implicite est que ce flux est la norme.
Dans mon expérience, le flux fonctionne proprement peut-être 60% du temps. Les autres 40% sont de la récupération d'erreur — Claude génère du code, quelque chose casse, et maintenant vous débuggez avec Claude, ce qui est une compétence fondamentalement différente de construire avec Claude.
Le problème avec les sessions de debugging : Claude devient apologétique et sur-correcteur. Dites-lui "le handler de webhook lance une 500 sur l'événement Clerk user.created" et il va réécrire tout le handler au lieu de fixer la seule ligne qui est fausse. J'ai vu Claude supprimer du code qui marchait pour "repartir de zéro" plus de fois que je ne peux compter parce que son instinct de récupération d'erreur est de nuker depuis l'orbite.
Ma solution de contournement est moche mais efficace. Quand quelque chose casse :
- Ne décrivez pas l'erreur dans la même session. Tuez la session. Commencez-en une nouvelle.
- Collez le message d'erreur et le fichier spécifique, pas la description de tâche. "Cette fonction dans
/convex/webhooks.tslanceTypeError: Cannot read properties of undefined (reading 'email_addresses')en recevant un événement Clerkuser.created. Le payload entrant ressemble à ça : [coller payload]. Fixez seulement cette fonction. Ne modifiez aucun autre fichier." - Verrouillez tout le reste. Ajoutez "NE modifiez PAS de fichier sauf
/convex/webhooks.ts" à la contrainte. Claude en mode fix a la gâchette facile.
La différence entre "hey Claude, l'auth est cassée, tu peux fixer" et un prompt scopé, mono-fichier, spécifique à l'erreur, c'est la différence entre un fix de 5 minutes et un trou de lapin d'une heure où Claude réécrit votre auth from scratch.
Les tutoriels n'enseignent pas la récupération d'erreur parce que ce n'est pas photogénique. Mais c'est là qu'au moins un tiers de votre temps Claude Code passe vraiment.
Ce Que J'ai Essayé et Abandonné
Tout n'a pas survécu. Des trucs dont j'étais convaincu qu'ils marcheraient, sur lesquels j'ai passé du vrai temps, et que j'ai finalement abandonnés. Ça vaut le coup de documenter pour que vous ne répétiez pas l'expérience.
"Think hard" sur chaque prompt. Pendant un moment j'ajoutais "think hard" ou "think step by step" à chaque prompt Claude Code parce qu'un thread Reddit disait que ça améliorait la qualité de sortie. Ça marche — sur les décisions architecturales complexes. Sur "ajoute un spinner de loading à ce bouton" ? Ça fait juste écrire à Claude un plan de 400 mots pour un changement de 3 lignes. Maintenant je l'utilise seulement pour les tâches avec une vraie ambiguïté. Peut-être 1 prompt sur 5.
Sessions parallèles multi-worktree. Le concept est beau — trois instances Claude travaillant sur trois fonctionnalités simultanément, chacune dans son propre git worktree. J'ai configuré ça, fait tourner, et utilisé exactement un après-midi. Le problème n'est pas technique, il est cognitif. Revoir trois sorties concurrentes, garder trace de quel worktree est en avance, merger sans conflits — c'est de l'overhead de gestion de projet déguisé en productivité. Si vous avez une équipe, peut-être. Solo ? Vous générez juste des conflits de merge plus vite. Mais je digresse — j'ai nommé les worktrees d'après des Pokémon pendant environ 48 heures, et honnêtement cette partie était fun.
Utiliser Claude pour revoir son propre code. Le CEO de Y Combinator a tout un prompt pour ça — système de review en quatre étapes, check d'architecture, passe de qualité de code, tout le bazar. Je l'ai fait tourner pendant deux jours. La sortie était minutieuse et j'ai vraiment appris quelque chose du format structuré. Mais les maths ne marchaient pas : 30-45 minutes de dialogue de review par fonctionnalité, en plus du temps de génération. Je passais plus de temps à superviser le reviewer que j'en aurais passé à revoir le code moi-même. Claude qui attrape ses propres erreurs sonne élégant. En pratique, vous devenez un manager QA pour un robot qui ne se souvient pas de la review à la session suivante de toute façon.
Instructions de personnalité dans CLAUDE.md. "Tu es un ingénieur TypeScript senior qui valorise l'architecture propre." "Réponds de manière concise." "Sois opinionné." J'avais 15 lignes de ce truc. Tout supprimé après avoir réalisé que ça avait zéro impact mesurable sur la qualité du code. Claude ne code pas différemment parce que vous lui avez dit d'être senior. Il code différemment quand vous lui donnez les bonnes contraintes et le bon contexte. Économisez ces tokens.
Chacun de ces trucs semblait intelligent à l'époque. C'est le piège — l'écosystème Claude Code est plein de conseils qui sonnent raisonnables dans un article de blog et s'effondrent à la session 200.
🔄 Update : Il y a en fait une 6ème chose qu'aucun tutoriel ne couvre, et c'est sans doute la plus importante : la sécurité. Claude Code a une commande slash /security-review depuis août 2025. Vous la tapez, il scanne votre code pour les vulnérabilités. Douze mots pour expliquer. Zéro tutoriel ne la mentionne. Anthropic vient de construire tout un produit enterprise autour et a fait crasher 15 milliards de dollars d'actions cybersécurité dans le processus. Les tutoriels enseignent encore comment configurer CLAUDE.md.
Les tutoriels vendent la magie. La production facture le nettoyage.
J'écris sur Claude Code, l'automatisation IA, et les parties peu sexy du shipping de vrais produits avec des outils IA. Prochainement : pourquoi j'ai reconstruit toute ma config OpenClaw pour 15$ après qu'Anthropic ait tué l'ancienne — et l'architecture qui marche vraiment. Abonnez-vous (pas juste follow — l'email c'est ce qui vous donne l'article, le bouton follow c'est basiquement un trophée de participation) si vous voulez ça dans votre inbox.
Dans la bataille entre les tutoriels Claude Code et la réalité de la production, découvrez les vraies leçons qui font la différence entre un démo et un produit qui tient la route.