Les 4 erreurs que font tous les devs avec Claude Code · Guide complet

🎁 Ce que tu reçois : la checklist des 4 erreurs pour faire ton score, puis le correctif exact de chacune · avec les fichiers à copier-coller. Syntaxe des hooks et du CLAUDE.md vérifiée sur la doc officielle Claude Code le 28 août 2026.

✅ La checklist · fais ton score sur 4

Coche ce qui est vrai chez toi aujourd'hui. Chaque case non cochée = une erreur qui te coûte du temps et des tokens.

• 1. J'ai un CLAUDE.md à la racine du projet, à jour, avec ma stack et mes règles
• 2. Je donne un critère de succès vérifiable AVANT de lancer Claude (« c'est fini quand npm test passe »)
• 3. J'ai au moins un hook qui valide automatiquement ce que Claude produit
• 4. Mes prompts partent d'un contexte propre (fichiers concernés + contraintes), pas d'un copier-coller générique

🔴 Erreur 1 · Pas de CLAUDE.md : l'IA improvise

Le symptôme · Claude réinvente ta stack à chaque session, recrée un fichier qui existe déjà, installe une lib que tu n'utilises pas, change ta convention de nommage.

Pourquoi · sans fichier de contexte, il repart de zéro à chaque nouvelle session. Tu payes des tokens juste pour lui réexpliquer ton projet, et tu oublies toujours un détail.

Le fix · un fichier CLAUDE.md à la racine du projet. Claude le charge automatiquement au démarrage de chaque session, tu n'as rien à faire.

Le template à copier

# Projet

Nom, en une phrase ce que fait l'app, et pour qui.

# Stack

- Framework : Next.js 15 (App Router)
- Base : Supabase (Postgres + Auth)
- Paiement : Stripe
- Style : Tailwind + shadcn/ui
- Package manager : pnpm (JAMAIS npm)

# Commandes

- Dev : pnpm dev
- Tests : pnpm test
- Lint : pnpm lint
- Build : pnpm build

# Règles

- Toujours proposer un plan avant de modifier plus de 2 fichiers
- Ne jamais inventer un fichier ou une fonction : vérifier qu'il existe
- Réutiliser les composants de src/components avant d'en créer un
- Aucune clé d'API en dur, tout passe par .env.local
- Ne jamais toucher aux migrations déjà appliquées

# Ce qu'il ne faut PAS faire

- Pas de refactor spontané non demandé
- Pas d'ajout de dépendance sans me demander

Les 3 niveaux (à connaître)

💡 Tu pars d'un projet existant ? Lance /init dans Claude Code : il analyse le repo et te génère un premier CLAUDE.md. Tu n'as plus qu'à le corriger · ne le laisse jamais tel quel.

Le test qui prouve que c'est réglé : ouvre une session neuve et demande « quelle est ma stack et mon package manager ? ». S'il répond juste sans que tu aies rien collé, c'est bon.

🔴 Erreur 2 · Pas de critère de succès : elle boucle, le compteur monte

Le symptôme · Claude dit « c'est fait ! », tu lances l'app, ça plante. Tu relances, il re-corrige, ça re-plante. Vingt minutes plus tard t'es plus loin qu'au début.

Pourquoi · tu lui as donné une tâche (« corrige le login »), pas une condition d'arrêt. Sans condition d'arrêt vérifiable, c'est lui qui décide quand c'est fini. Et il décide toujours trop tôt.

Le fix · chaque demande se termine par une commande qui doit passer au vert. Pas une opinion, une commande.

Le template de prompt

OBJECTIF
Corriger le login : l'utilisateur reste bloqué sur le loader après un mot de passe valide.

PÉRIMÈTRE
Uniquement src/app/(auth)/ et src/lib/supabase/. Ne touche à rien d'autre.

C'EST FINI QUAND
1. pnpm test passe (0 échec)
2. pnpm lint passe (0 erreur)
3. Tu me colles la sortie des deux commandes dans ta réponse

AVANT DE CODER
Propose-moi ton plan et attends ma validation.

Les 3 formes de critère qui marchent

⚠️ Le piège : « dis-moi si ça marche » n'est pas un critère. Claude te répondra que ça marche. Un critère, ça s'exécute.

Le test qui prouve que c'est réglé : ta dernière demande contenait-elle une commande à faire passer au vert ? Si non, tu fais encore l'erreur.

🔴 Erreur 3 · Pas de hook de validation : tu découvres le cassé en prod

C'est celle que presque personne corrige. Les deux premières, tout le monde en a entendu parler. Celle-là, non · et c'est la seule qui travaille pour toi pendant que tu fais autre chose.

Le symptôme · Claude modifie 8 fichiers, tout a l'air propre, et trois jours plus tard tu découvres une clé d'API en dur dans un commit, ou un fichier qui ne compile plus.

Pourquoi · tu relis à la main. Sur 8 fichiers, tu relis vraiment le premier et tu scrolles les autres.

Le fix · un hook. C'est un script que Claude Code déclenche tout seul à un moment précis (avant ou après un outil). S'il sort en code 2, Claude est bloqué ou averti, et il corrige de lui-même.

1. Le script de validation

Crée .claude/hooks/validate.sh :

#!/usr/bin/env bash
# Reçoit le JSON du hook sur stdin
input=$(cat)
file=$(echo "$input" | jq -r '.tool_input.file_path // empty')

[ -z "$file" ] && exit 0
[ -f "$file" ] || exit 0

# 1. Secrets en dur
if grep -Eq "(API_KEY|SECRET|PASSWORD|TOKEN)[[:space:]]*=[[:space:]]*['\"][^'\"]{8,}" "$file"; then
  echo "❌ Secret en dur détecté dans $file. Passe par .env.local." >&2
  exit 2
fi

# 2. JSON cassé
case "$file" in
  *.json) jq empty "$file" 2>/dev/null || { echo "❌ JSON invalide : $file" >&2; exit 2; } ;;
esac

# 3. Debug oublié
if grep -Eq "console\.log\(|debugger;" "$file"; then
  echo "⚠️ console.log/debugger oublié dans $file. Nettoie avant de finir." >&2
  exit 2
fi

exit 0

2. Le brancher

chmod +x .claude/hooks/validate.sh

Puis dans .claude/settings.json :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/validate.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Ce qu'il faut retenir sur les exit codes

💡 Deux événements à connaître : PreToolUse (avant l'outil · c'est le seul qui bloque) et PostToolUse (après · il avertit). Pour un garde-fou dur du type « interdit de toucher aux migrations », c'est PreToolUse avec "matcher": "Edit|Write".

Le test qui prouve que c'est réglé : demande à Claude d'écrire un fichier avec const API_KEY = "sk-test-123456789". Si le hook le rattrape et qu'il corrige tout seul, c'est bon.

🔴 Erreur 4 · Des prompts sans contexte : des résultats génériques

Le symptôme · tu colles un prompt trouvé sur X, tu obtiens du code qui ressemble à un tutoriel : générique, à côté de ton projet, à moitié réécrit à la main.

Pourquoi · deux causes opposées, et les deux font mal. Soit tu donnes trop peu (il devine), soit tu laisses une session de 3 heures charger 40 fichiers et il mélange tout.

Le fix · côté prompt : cinq blocs, toujours les mêmes.

1. CONTEXTE    → où on est, ce qui existe déjà
2. FICHIERS    → les 2-3 fichiers concernés, nommés
3. OBJECTIF    → une seule chose à obtenir
4. CONTRAINTES → ce qu'il ne doit PAS toucher
5. VALIDATION  → la commande qui doit passer au vert

Le fix · côté session : une session = un objectif.

⚠️ Le signal d'alerte : réponses plus vagues, oublis d'instructions, répétitions. Ne lutte pas 30 minutes contre un contexte saturé · /clear et tu repars. Tu récupères en 2 minutes ce que tu aurais perdu en une demi-heure.

Le test qui prouve que c'est réglé : ton dernier prompt nommait-il les fichiers concernés ? Si tu as écrit « corrige le bug du panier » sans dire où, tu fais encore l'erreur.

📋 Récap · les 4 erreurs en un tableau

🎯 Le principe : la compétence IA, c'est pas savoir prompter. C'est poser les garde-fous qui rendent l'IA fiable. Les erreurs 1 et 3 se règlent une fois et travaillent pour toi tous les jours. Commence par celles-là.

🚀 L'ordre dans lequel je le ferais

1. Aujourd'hui (15 min) · /init, tu corriges le CLAUDE.md généré, tu ajoutes tes règles et tes commandes.
2. Aujourd'hui (0 min) · sur ta prochaine demande, tu ajoutes le bloc « C'EST FINI QUAND ».
3. Cette semaine (20 min) · tu colles le validate.sh et tu branches le hook.
4. En continu · /clear entre deux objectifs. C'est une habitude, pas un réglage.