Claude Code lent : diagnostiquer la session et retrouver un flux rapide

Claude Code répondait vite au début de la matinée, puis chaque demande a commencé à prendre plusieurs minutes. Avant même de modifier un fichier, l’agent relisait des dossiers sans rapport, rappelait d’anciennes décisions et produisait des journaux interminables. Changer de modèle n’aurait pas corrigé le vrai problème : la session transportait trop de contexte et la consigne lui laissait un périmètre beaucoup trop large.

Ce ralentissement arrive souvent après avoir enchaîné recherche, développement, tests et déploiement dans la même conversation. La solution n’est pas un réglage secret. Il faut repérer ce qui remplit le contexte, conserver uniquement les informations utiles, puis donner à Claude Code une tâche dont les limites sont vérifiables.

Les cinq décisions qui accélèrent réellement une session

Examiner /usage et /context avant de conclure que le modèle est lent.
Employer /compact avec une consigne précise sur ce qui doit être conservé.
Indiquer les fichiers autorisés, les dossiers exclus et le test attendu.
Garder CLAUDE.md court, réservé aux règles nécessaires à presque toutes les tâches.
Comparer deux exécutions similaires au lieu de juger la vitesse au ressenti.

Ces actions réduisent surtout le travail inutile. Elles ne garantissent pas un temps identique à chaque requête : la taille du dépôt, les outils MCP, la latence réseau et la complexité du raisonnement restent des facteurs réels.

Distinguer le contexte lourd d’une commande réellement lente

Commencez dans Claude Code par /usage. Cette commande indique l’utilisation de la session ou du forfait selon le mode d’accès. Elle sert de compteur opérationnel, pas de facture définitive. Lancez ensuite /context pour voir la place occupée par la conversation, la mémoire, les outils et les autres instructions chargées.

/usage
/context

Si la conversation et les sorties d’outils occupent l’essentiel de la fenêtre, le problème vient probablement de l’historique. Si une commande de test prend elle-même trois minutes dans un terminal normal, réduire le contexte ne la rendra pas instantanée. Exécutez alors cette commande hors de Claude Code et mesurez-la séparément.

Symptôme observé	Cause probable	Première action
Longue exploration avant chaque réponse	Consigne trop large	Nommer les fichiers et dossiers autorisés
Répétition d’anciennes décisions	Conversation devenue trop longue	Utiliser `/compact` avec une liste à conserver
Beaucoup de règles chargées dès le départ	`CLAUDE.md` ou configuration MCP trop volumineux	Déplacer les procédures rares hors du contexte permanent
Même commande lente dans le terminal	Construction, test ou réseau réellement lent	Profiler la commande indépendamment
Réponse rapide mais correction souvent fausse	Vérification supprimée pour gagner du temps	Rétablir un test ciblé et un critère d’acceptation

La documentation officielle décrit plus précisément la fenêtre de contexte et le suivi de l’utilisation. Vérifiez ces pages lorsque le comportement d’une commande évolue, car Claude Code reçoit régulièrement des mises à jour.

Compacter sans perdre l’état du travail

/compact résume la conversation pour libérer de la place. Une demande vague comme /compact peut toutefois supprimer le détail qui explique un échec. Précisez les éléments qui doivent survivre : fichiers modifiés, commande en échec, décisions, contraintes de sécurité et prochaine action.

/compact Conserver les fichiers modifiés, la commande en échec, les décisions prises,
les contraintes de sécurité, les questions ouvertes et la prochaine action.

Utilisez /clear lorsque vous passez à une tâche sans rapport. Une nouvelle conversation coûte parfois moins cher qu’un long résumé chargé d’hypothèses inutiles. Avant d’effacer, laissez une courte note de transmission dans un fichier versionné si le travail doit être repris plus tard.

## État de la tâche
- Objectif : corriger la validation de session expirée
- Fichiers modifiés : src/api/auth.ts, tests/auth.test.ts
- Commande en échec : npm test -- tests/auth.test.ts
- Résultat attendu : une session expirée renvoie 401
- Risque restant : comportement du renouvellement automatique à vérifier
- Prochaine action : exécuter le test ciblé, puis la suite complète

Cette note contient des faits exploitables. Elle évite de conserver cent lignes de journal uniquement pour se souvenir d’une erreur.

Donner une tâche étroite et une preuve de fin

« Corrige l’authentification » oblige l’agent à découvrir seul le périmètre, parfois dans tout le dépôt. Une bonne consigne précise le fichier à lire, le comportement à corriger, les exclusions et la preuve attendue. Le résultat est plus rapide à produire et plus simple à relire.

claude -p "Corrige uniquement le contrôle de valeur nulle dans src/api/auth.ts.
Lis d'abord src/api/auth.ts et tests/auth.test.ts.
N'explore pas node_modules, dist, coverage ni les autres fonctionnalités.
Exécute npm test -- tests/auth.test.ts.
À la fin, indique les fichiers modifiés, les commandes exécutées et les risques restants."

Ne transformez pas cette délimitation en interdiction absolue de regarder une dépendance nécessaire. Ajoutez une règle de sortie : si la correction exige un autre fichier, Claude Code doit expliquer pourquoi avant de l’ouvrir ou de le modifier. Vous gardez ainsi le contrôle sans bloquer l’enquête.

Pour une tâche sensible, associez ce périmètre aux règles du guide des permissions Claude Code. La vitesse ne justifie jamais d’accorder plus de droits que nécessaire.

Garder un fichier CLAUDE.md court et utile

CLAUDE.md est chargé pour orienter le travail. S’il contient chaque incident passé, chaque procédure rare et de longues explications métier, cette masse accompagne toutes les requêtes. Gardez uniquement la carte stable du dépôt, les commandes essentielles et les interdictions permanentes.

# CLAUDE.md

## Commandes du projet
- Construction : npm run build
- Tests : npm test
- Vérification des types : npm run typecheck

## Repères
- API : src/api/
- Interface : src/components/
- Tests : tests/

## Chemins à éviter par défaut (consigne, pas blocage)
- node_modules/
- dist/
- coverage/
- .wrangler/

## Consigne de compactage
Conserver les fichiers modifiés, les tests en échec, les décisions,
la politique des secrets et la prochaine action.

CLAUDE.md donne des instructions à l’agent, mais ne constitue pas un contrôle d’accès. Une phrase comme « ne pas lire dist/ » guide Claude Code ; elle n’empêche pas techniquement un outil ou un autre processus d’ouvrir ce dossier. Pour imposer une limite, configurez les permissions Claude Code, utilisez des hooks de contrôle capables de refuser une opération, puis appliquez les droits de fichiers, comptes séparés, restrictions réseau ou mécanismes d’isolation du système d’exploitation. Les secrets qui ne doivent jamais être lus ne doivent pas dépendre de la seule bonne exécution d’une consigne.

Les longues procédures peuvent vivre dans des documents spécialisés ou des règles chargées seulement pour les chemins concernés. Le guide d’optimisation des jetons complète cette organisation avec des méthodes pour éviter les lectures et sorties superflues.

Mesurer deux consignes comparables

Une session « semble » parfois plus rapide simplement parce que la seconde demande profite des fichiers modifiés par la première. Pour obtenir un signal utile, prenez une petite tâche reproductible et lancez chaque variante depuis exactement le même commit propre. Notez le temps écoulé, la réussite du test, l’état final du dépôt et la qualité du compte rendu.

Le script PowerShell suivant crée un worktree détaché différent pour chaque variante, toujours depuis $fixtureCommit. Une modification laissée par la consigne large ne peut donc pas aider la consigne délimitée. Le script suppose que git et claude sont accessibles dans le terminal. Il supprime les worktrees temporaires après chaque mesure, même si une commande échoue.

$runs = @(
  @{ Name = "large"; Prompt = "Trouve et corrige le défaut d'authentification dans ce projet" },
  @{ Name = "délimité"; Prompt = "Corrige uniquement le contrôle nul dans src/api/auth.ts et exécute le test ciblé" }
)

$fixtureCommit = (git rev-parse HEAD).Trim()
$benchmarkRoot = Join-Path ([System.IO.Path]::GetTempPath()) `
  ("claude-speed-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path $benchmarkRoot | Out-Null

try {
  foreach ($run in $runs) {
    $worktree = Join-Path $benchmarkRoot $run.Name
    git worktree add --detach $worktree $fixtureCommit | Out-Null
    if ($LASTEXITCODE -ne 0) { throw "Impossible de créer $worktree" }

    try {
      Push-Location $worktree
      $watch = [System.Diagnostics.Stopwatch]::StartNew()
      $output = & claude -p $run.Prompt 2>&1
      $exitCode = $LASTEXITCODE
      $watch.Stop()
      $changes = @(git status --porcelain)

      [pscustomobject]@{
        Name = $run.Name
        Fixture = $fixtureCommit
        Seconds = [math]::Round($watch.Elapsed.TotalSeconds, 1)
        ExitCode = $exitCode
        ChangedEntries = $changes.Count
        OutputTail = ($output | Select-Object -Last 20) -join [Environment]::NewLine
      }
    }
    finally {
      Pop-Location
      git worktree remove --force $worktree | Out-Null
    }
  }
}
finally {
  git worktree prune
  Remove-Item -LiteralPath $benchmarkRoot -Force -ErrorAction SilentlyContinue
}

Vérifiez ExitCode, ChangedEntries, le test demandé et le contenu de $output avant de comparer les secondes. Une exécution rapide qui échoue ou ne modifie rien n’est pas une amélioration. Relancez l’ensemble au moins trois fois et comparez les médianes ; chaque passage recrée deux fixtures à partir du même commit.

Trois cas d’usage concrets

1. Corriger un petit défaut sans parcourir tout le dépôt

Donnez le message d’erreur, le fichier soupçonné, le test ciblé et la condition de réussite. Demandez d’abord un diagnostic court, puis la modification. Si le test échoue pour une autre raison, conservez uniquement les lignes qui montrent la cause au lieu de renvoyer tout le journal dans la conversation.

2. Mener une refactorisation en plusieurs étapes

Séparez l’exploration, la décision, l’implémentation et la revue. À la fin de chaque étape, demandez un reçu comprenant les fichiers concernés, la décision retenue et le risque restant. Compactez entre les étapes en conservant ce reçu. La session d’implémentation n’a alors pas besoin de transporter toutes les pistes abandonnées pendant l’enquête.

3. Produire et vérifier plusieurs contenus localisés

Confiez la traduction ou la vérification d’une langue à une tâche distincte, avec un seul fichier autorisé et une liste de contrôles. La session principale conserve le choix éditorial, les résultats de validation et l’état du déploiement. Cette séparation évite que dix versions complètes du même article saturent la conversation principale.

Ces trois scénarios suivent la même logique : l’humain fixe le périmètre, le niveau de risque et le critère de fin ; Claude Code explore, modifie et rapporte des preuves à l’intérieur de ces limites.

Répartir clairement les décisions entre l’humain et Claude Code

Claude Code peut mesurer le temps, rechercher les références, proposer une modification, lancer un test et résumer les écarts. L’humain doit décider si le test représente vraiment le besoin, si une permission supplémentaire est acceptable et si le gain de vitesse compense une éventuelle perte de couverture.

Claude Code peut prendre en charge	Une personne doit trancher
Repérer les fichiers et sorties volumineuses	Définir ce qui est hors périmètre
Préparer une consigne délimitée	Valider le comportement métier attendu
Exécuter les commandes autorisées	Autoriser un accès sensible ou un déploiement
Comparer les résultats de plusieurs essais	Décider si la preuve suffit pour publier

Cette répartition est un exemple de harnais : un ensemble de règles, d’outils et de preuves qui encadre l’agent. Le guide du harness engineering montre comment aller plus loin pour des flux répétés.

Pièges fréquents et corrections

Compacter sans préciser ce qui compte

Le résumé peut oublier la commande exacte qui échoue ou la raison d’un choix d’architecture. Corrigez le tir avec une liste explicite des faits à conserver et écrivez les décisions durables dans le dépôt.

Remplir CLAUDE.md avec toute la documentation

Chaque règle rare devient une taxe permanente. Déplacez les procédures occasionnelles vers un document ciblé et gardez dans CLAUDE.md ce qui est nécessaire à presque chaque session.

Supprimer les tests pour gagner quelques secondes

Une réponse plus rapide mais non vérifiée crée souvent un aller-retour plus coûteux. Réduisez le volume des journaux, pas la preuve : conservez le test ciblé, son code de sortie et les lignes utiles en cas d’échec.

Ouvrir trop de sous-tâches

La délégation aide lorsqu’une tâche est autonome. Elle ralentit lorsque plusieurs agents relisent les mêmes fichiers ou attendent la même ressource. Donnez à chaque tâche un fichier ou un livrable distinct, puis rassemblez seulement les conclusions.

Confondre contexte et performances du projet

Un build lent, une base de données distante ou un test d’intégration instable ne se corrigent pas avec /compact. Mesurez la commande seule. Si elle reste lente, profilez le programme ou le service concerné au lieu de modifier la conversation.

Liste de contrôle avant de changer de modèle

J’ai consulté /usage et /context.
J’ai distingué le temps de réflexion du temps pris par les outils.
Ma consigne nomme les fichiers, exclusions et critères de fin.
CLAUDE.md ne contient que des règles fréquemment nécessaires.
Le compactage conserve les décisions et échecs utiles.
Le test ciblé reste présent.
J’ai comparé plusieurs essais reproductibles.

Si ces points sont satisfaits et que les tâches restent trop lentes, le changement de modèle ou d’architecture devient une hypothèse raisonnable. Avant cela, il masque souvent un problème de méthode.

Mettre en place ce flux dans une équipe

Pour une équipe qui veut normaliser les consignes, les permissions, le compactage et les preuves de fin, la prochaine étape n’est pas d’ajouter dix outils. Il faut construire un petit protocole adapté au dépôt et aux risques métier.

Consulter l’offre de formation et d’accompagnement Claude Code

Vérification pratique effectuée pour cette version

Cette réécriture ne prétend pas démontrer un gain universel sur un projet réel et le benchmark n’a pas lancé d’appels Claude payants pendant la publication. Les commandes /usage, /context et /compact ont été recoupées avec les pages officielles consacrées aux commandes, à la mémoire et aux coûts et à l’utilisation. Le bloc PowerShell a été accepté par l’analyseur de syntaxe, puis exécuté avec une commande claude simulée : les deux variantes ont utilisé le même commit de fixture, chacune dans son propre worktree, avec une modification isolée et un code de sortie nul. Les clôtures de code, les liens internes, la langue et le score éditorial ont aussi été contrôlés. Le prochain test utile chez vous consiste à exécuter les deux variantes sur un petit défaut reproductible, puis à comparer leurs médianes et la réussite du test ciblé.