Debug Claude Code comme un pro : mes techniques pour comprendre ce qu’il fait vraiment

Bon, soyons honnêtes : Claude Code c’est puissant, mais des fois il fait des trucs bizarres. Genre il modifie 15 fichiers d’un coup, vous validez sans trop regarder, et bam, votre CI est en feu. La semaine dernière j’ai passé 2h à comprendre pourquoi il avait décidé de renommer toutes mes variables en camelCase alors que le projet était en snake_case depuis le début.

Le truc c’est que Claude Code, c’est pas magique. C’est un assistant qui prend des décisions basées sur le contexte qu’il voit. Et si vous savez pas comment il voit votre code, vous allez galérer. Voici mes techniques pour garder le contrôle.

Mon setup de base : git + verbose mode

Première règle : JAMAIS de session Claude Code sans Git propre. Avant chaque session, je fais ça :

# Status propre
git status
# Si y'a des modifs en cours, je stash
git stash
# Je crée une branche dédiée
git checkout -b claude/feature-name

Pourquoi ? Parce que ça me permet de voir EXACTEMENT ce que Claude touche avec un simple git diff. Et si ça part en couille, un git reset --hard et c’est reparti.

Mais le vrai hack, c’est d’activer le mode verbose de Claude. Dans votre .config/claude/config.json :

{
  "verbose": true,
  "logLevel": "debug",
  "logFile": "/tmp/claude-code.log"
}

Du coup, tout ce que Claude fait est loggé. Chaque fichier lu, chaque outil appelé, chaque décision. Je tail ce fichier dans un terminal à côté :

tail -f /tmp/claude-code.log | grep -E "(READ|WRITE|TOOL)"

Franchement, ça change la vie. Vous voyez en temps réel ce qu’il analyse.

Le CLAUDE_DEBUG.md : forcer Claude à penser à voix haute

Voici un truc que presque personne fait : j’ai un fichier CLAUDE_DEBUG.md à la racine de mes projets. Et dedans :

# Debug Instructions pour Claude

Quand tu travailles sur ce projet :

1. AVANT de modifier du code, écris dans ce fichier :
   - Les fichiers que tu vas modifier
   - Pourquoi tu fais ces choix
   - Les risques potentiels

2. APRÈS tes modifications, ajoute :
   - Ce que tu as changé exactement
   - Comment tester que ça marche

3. Si tu hésites entre plusieurs approches, documente-les ici

Ce fichier est un espace de réflexion, pas de la doc finale.

Et dans mon prompt initial à Claude, je dis explicitement : “Utilise CLAUDE_DEBUG.md pour documenter ton raisonnement au fur et à mesure.”

Résultat ? Claude écrit ses réflexions AVANT de coder. Genre :

## Session 2025-01-15 : Refacto auth

Je vais modifier :
- src/auth/middleware.ts (ajouter validation JWT)
- src/types/user.ts (typage refresh token)

Risques :
- Breaking change si d'autres services utilisent l'ancien format
- Need de migrer les tokens existants ?

Décision : je vais d'abord ajouter le nouveau format en parallèle (backward compatible)

C’est pas parfait, mais au moins vous pouvez intervenir AVANT qu’il code si vous êtes pas d’accord.

Tracer les appels MCP : voir ce que Claude va chercher

Si vous utilisez des MCP servers (base de données, APIs, file system), Claude fait des appels en arrière-plan. Le problème ? Vous voyez pas ce qu’il récupère comme data.

Moi j’ai wrappé mon MCP server avec un proxy de debug. C’est un petit script Node qui intercepte tous les appels :

// mcp-debug-proxy.ts
import { MCPServer } from '@modelcontextprotocol/sdk';

const originalServer = new MCPServer({
  name: 'my-db',
  version: '1.0.0'
});

// Wrapper qui log tout
const proxy = new Proxy(originalServer, {
  get(target, prop) {
    const original = target[prop];
    if (typeof original === 'function') {
      return async (...args: any[]) => {
        console.log(`[MCP DEBUG] ${String(prop)} called with:`, JSON.stringify(args, null, 2));
        const result = await original.apply(target, args);
        console.log(`[MCP DEBUG] ${String(prop)} returned:`, JSON.stringify(result, null, 2));
        return result;
      };
    }
    return original;
  }
});

proxy.start();

Vous lancez ça au lieu de votre MCP server normal, et vous voyez TOUT. Les queries SQL, les paramètres, les résultats. Super pratique quand Claude fait des requêtes bizarres.

D’ailleurs, j’ai découvert que Claude a tendance à faire des SELECT * au lieu de sélectionner les colonnes dont il a besoin. Du coup j’ai ajouté un guardrail dans mon MCP server qui refuse les SELECT * sur les grosses tables. Vous seriez surpris du nombre de fois où ça l’a forcé à être plus précis.

Diff avant validation : mon workflow pré-commit

Claude vous propose de valider ses changements ? Arrêtez de spam Enter comme un bourrin. Voici ce que je fais systématiquement :

# Voir les fichiers modifiés
git status

# Diff interactif fichier par fichier
git diff --color-words

# Si c'est gros, j'utilise un outil visuel
git difftool

# Vérifier que ça compile / les tests passent
npm run type-check
npm test -- --bail

Et j’ai un hook pré-commit qui force cette vérification :

#!/bin/bash
# .git/hooks/pre-commit

echo "🔍 Pre-commit check..."

# Liste les fichiers modifiés
FILES=$(git diff --cached --name-only)
echo "Fichiers modifiés :"
echo "$FILES"

# Demande confirmation si plus de 10 fichiers
COUNT=$(echo "$FILES" | wc -l)
if [ $COUNT -gt 10 ]; then
  echo "⚠️  Plus de 10 fichiers modifiés. C'est voulu ?"
  read -p "Continuer ? (y/N) " -n 1 -r
  echo
  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    exit 1
  fi
fi

# Run les checks
npm run type-check || exit 1
npm test -- --bail --onlyChanged || exit 1

echo "✅ Pre-commit checks passed"

Bref, ça m’a sauvé les fesses plus d’une fois.

Les erreurs classiques que je vois partout

Erreur #1 : Faire confiance à Claude sur les modifications de config. Les fichiers genre package.json, .env.example, tsconfig.json, Claude les modifie parfois sans comprendre l’impact. Je les mets systématiquement en read-only dans mon .claudeignore :

# .claudeignore
package.json
tsconfig.json
.env*
docker-compose.yml

Si j’ai besoin qu’il les modifie, je les unlock temporairement.

Erreur #2 : Pas de feedback loop. Claude fait une modif, vous validez, vous testez 10 minutes après. Trop tard. Maintenant y’a 50 autres changements et vous savez plus ce qui casse. Testez IMMÉDIATEMENT après chaque validation.

Erreur #3 : Utiliser Claude Code sur une codebase que vous connaissez pas. J’ai vu des juniors utiliser Claude pour modifier du legacy code qu’ils ont jamais lu. Résultat : Claude invente des patterns qui matchent rien du reste du projet. Lisez le code d’abord, PUIS utilisez Claude pour accélérer.

Erreur #4 : Oublier que Claude a une mémoire limitée. Si votre session dure 2h, il a peut-être oublié ce qu’il a fait au début. Du coup il peut créer des inconsistances. Ma règle : sessions de max 30-45 minutes, puis je restart avec un summary de ce qui a été fait.

Le debug ultime : reproduire sans Claude

Quand vraiment je capte pas ce que Claude a fait, je fais ça :

1. Je reviens à l’état avant ses modifs (git reset --hard HEAD~1)
2. Je lis ses changements dans le diff
3. J’essaie de les ré-implémenter moi-même à la main

Souvent, je me rends compte qu’il a fait un truc malin que j’avais pas vu. Ou au contraire, qu’il a fait une erreur de logique subtile.

Ah et aussi : gardez un fichier CLAUDE_WINS.md et CLAUDE_FAILS.md dans vos projets. Notez ce qui marche bien et ce qui marche pas. Avec le temps, vous allez apprendre quelles tâches vous pouvez lui déléguer en confiance et lesquelles nécessitent une surveillance de tous les instants.

En vrai, c’est un partenariat

Claude Code c’est pas un stagiaire à qui vous dites “débrouille-toi”. C’est un pair programmer qui a des forces (vitesse, connaissance large) et des faiblesses (pas de compréhension du contexte business, pas de mémoire long terme).

Du coup, votre job c’est pas de le laisser faire, c’est de le guider ET de vérifier. Ces techniques de debug, c’est votre filet de sécurité. Utilisez-les.

Et sérieux, le combo Git branches + verbose logs + CLAUDE_DEBUG.md, ça change tout. Vous passez de “j’espère que ça marche” à “je sais exactement ce qu’il fait”.