Gestion du contexte - Erreurs courantes

La gestion du contexte dans Claude Code est la compétence qui sépare les utilisateurs productifs de ceux qui perdent du temps. Voici les erreurs les plus fréquentes qui sabotent votre fenêtre de contexte (jusqu'à 1 million de tokens sur les modèles actuels), avec des correctifs concrets pour optimiser chaque session et éviter les pièges de saturation.

La gestion du contexte dans Claude Code est le mécanisme qui détermine quelles informations l'IA conserve en mémoire pendant une session de travail. Les modèles actuels (Opus 4.6+ et Sonnet 4.6) offrent une fenêtre allant jusqu'à 1 million de tokens, tandis que les modèles plus anciens, ainsi que les défauts sur Bedrock, Vertex et Foundry, restent à 200 000 tokens (soit environ 150 000 mots). Quelle que soit la capacité disponible, elle est souvent gaspillée par des pratiques inefficaces.

De nombreuses sessions longues échouent à cause d'une saturation de contexte évitable. Chaque token consommé inutilement réduit la capacité de Claude Code à produire des réponses pertinentes.

Les ordres de grandeur ci-dessous sont des estimations indicatives, pas des mesures officielles de Claude Code :

Comment la surcharge de fichiers détruit-elle votre contexte ?

Sévérité : Critique

Charger un projet entier dans le contexte est l'erreur la plus fréquente. Vous perdez une grande partie de votre fenêtre avant même de poser une question utile. Un gros dépôt peut facilement dépasser la capacité disponible (estimation indicative, pas une mesure officielle).

En pratique, Claude Code lit alors des fichiers non pertinents et perd en précision sur ceux qui comptent. Si vous travaillez sur un bug dans auth.ts, les 50 fichiers de tests unitaires d'autres modules n'apportent rien.

# ❌ Incorrect - charger tout le projet
$ claude "Analyse tout le code dans /src et donne-moi un résumé"

# ✅ Correct - cibler les fichiers pertinents
$ claude "Analyse src/auth/login.ts et src/auth/middleware.ts pour trouver le bug d'authentification"

Pour comprendre comment structurer vos requêtes, consultez le tutoriel complet sur la gestion du contexte qui détaille les bonnes pratiques de chargement.

Lancez toujours votre session avec un périmètre précis. Trois à cinq fichiers ciblés donnent de meilleurs résultats que cinquante fichiers chargés en vrac.

À retenir : limitez chaque session à 5-10 fichiers pertinents pour conserver une large part de votre fenêtre disponible.

Pourquoi ignorer le mode Plan vous coûte-t-il des tokens ?

Sévérité : Critique

Le mode Plan (Shift+Tab ou Alt+M pour basculer entre les modes de permission) laisse Claude explorer le code et proposer un plan avant toute modification. En validant l'approche en amont, vous réduisez les allers-retours et le travail à refaire, ce qui limite le gaspillage de tokens lié aux corrections successives.

Concrètement, beaucoup d'utilisateurs lancent directement des modifications sans phase de planification. Résultat : Claude Code génère du code, vous le rejetez, il recommence, et chaque itération brûle une quantité non négligeable de tokens.

# ❌ Incorrect - exécuter directement
$ claude "Refactorise le module de paiement en microservices"

# ✅ Correct - planifier d'abord
$ claude "Propose une architecture de refactoring du module de paiement"

Le tableau ci-dessous est une illustration indicative (et non des mesures officielles de Claude Code) de la tendance observée :

Activez le mode Plan pour toute tâche impliquant plus de deux fichiers. Vous économiserez des tokens à chaque session.

Pour découvrir d'autres techniques d'économie, explorez les astuces de gestion du contexte compilées par SFEIR Institute.

À retenir : le mode Plan réduit nettement la consommation de tokens sur les tâches de refactoring complexes.

Quels problèmes cause l'absence de compaction automatique ?

Sévérité : Critique

La compaction automatique (auto-compact) résume les échanges passés quand le contexte atteint un seuil critique. Sans elle, Claude Code perd ses premières instructions dès que la fenêtre sature : un phénomène appelé « context amnesia ».

En pratique, la majorité des utilisateurs ne configurent pas la compaction et se retrouvent avec des réponses incohérentes après une longue session. Claude Code (2025) a introduit les hooks PreCompact pour personnaliser ce comportement.

// ❌ Incorrect - aucune configuration de compaction
{}

// ✅ Correct - configuration .claude/settings.json
{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          { "type": "command", "command": "echo \"Compaction at $(date)\" >> .claude/compaction.log" }
        ]
      }
    ]
  }
}

La compaction automatique se déclenche automatiquement lorsque le contexte approche de sa limite ; ce seuil n'est pas configurable via une variable d'environnement documentée. Le hook PreCompact ne fixe aucun seuil, il exécute seulement votre logique avant la compression. Ce hook vous permet par exemple de sauvegarder un résumé structuré avant chaque compaction. Consultez le guide approfondi de la gestion du contexte pour maîtriser les hooks avancés.

Le hook PreCompact est un script exécuté automatiquement avant la compression du contexte. Il permet d'extraire et stocker les décisions clés prises durant la session.

À retenir : la compaction automatique se déclenche automatiquement lorsque le contexte approche de sa limite ; utilisez les hooks PreCompact pour ne jamais perdre d'informations critiques.

Comment les prompts trop vagues gaspillent-ils votre fenêtre ?

Sévérité : Avertissement

Un prompt vague force Claude Code à « deviner » votre intention. Il génère alors des réponses longues couvrant plusieurs interprétations possibles, chacune consommant des tokens sans valeur ajoutée.

un prompt précis génère des réponses plus courtes et plus pertinentes qu'un prompt générique, et consomme nettement moins de tokens par échange.

# ❌ Incorrect - prompt vague
$ claude "Améliore ce code"

# ✅ Correct - prompt précis avec contraintes
$ claude "Dans src/api/users.ts, remplace les callbacks par async/await et ajoute un try/catch sur la fonction fetchUser (ligne 42)"

Précisez toujours le fichier, la fonction, le numéro de ligne et l'action attendue. Vous réduirez nettement la consommation de tokens à chaque échange en limitant les allers-retours inutiles. La technique du « contexte minimal suffisant » est détaillée dans les erreurs courantes des premières conversations.

Le tableau ci-dessous illustre la tendance (estimations indicatives, pas des mesures officielles) :

À retenir : un prompt précis réduit nettement la consommation de tokens tout en améliorant sensiblement la pertinence des réponses.

Pourquoi ne pas utiliser les sessions multiples est-il une erreur ?

Sévérité : Avertissement

Travailler dans une seule session pour un projet complexe est comparable à ouvrir 200 onglets dans un navigateur. Le scaling horizontal (répartir le travail sur plusieurs sessions parallèles) est la stratégie utilisée par les équipes performantes.

En pratique, répartir le travail entre une session dédiée au frontend et une autre au backend garde le contexte de chacune plus léger et évite de saturer une session unique surchargée. Claude Code permet d'exécuter plusieurs sessions en parallèle, via plusieurs terminaux et/ou des agents en arrière-plan, sans limite fixe imposée par projet.

# ❌ Incorrect - tout dans une session
$ claude "Corrige le bug frontend ET refactorise l'API backend ET mets à jour les tests"

# ✅ Correct - sessions dédiées
# Terminal 1 : session frontend
$ claude "Corrige le rendu du composant UserCard dans src/components/"

# Terminal 2 : session backend
$ claude "Refactorise l'endpoint /api/users dans src/routes/"

Ouvrez des sessions séparées pour chaque domaine fonctionnel. Vous pouvez consulter les erreurs liées aux commandes slash pour maîtriser le lancement de sessions multiples.

À retenir : le scaling horizontal via multi-sessions augmente nettement votre capacité effective de traitement.

Quels sont les risques de ne pas surveiller la consommation de tokens ?

Sévérité : Avertissement

Sans monitoring, vous dépassez le seuil critique sans le savoir. La qualité des réponses se dégrade progressivement à mesure que le contexte se remplit, et la perte de cohérence s'accentue nettement à l'approche de la saturation.

La commande /context affiche le remplissage de votre fenêtre de contexte (et /context all détaille la répartition par élément). La commande /cost, alias de /usage, sert plutôt à suivre le coût et les limites de plan. Concrètement, de nombreux utilisateurs ne vérifient jamais leur niveau de contexte et découvrent le problème quand Claude Code produit des réponses hors sujet.

# ❌ Incorrect - travailler à l'aveugle
$ claude "Continue le refactoring..." # Après 45 minutes sans vérification

# ✅ Correct - monitorer régulièrement, dans la session interactive Claude Code
> /context     # visualiser le remplissage de la fenêtre de contexte
> /cost        # afficher coût et limites de plan
> /compact     # compresser la conversation si le contexte se remplit

Pour approfondir le monitoring, les best practices avancées couvrent les stratégies de surveillance proactive.

À retenir : vérifiez régulièrement le remplissage de votre contexte avec /context et compactez avec /compact lorsque la fenêtre se remplit.

Comment éviter la perte d'instructions système après compaction ?

Sévérité : Critique

Lors de la compaction, Claude Code résume les échanges passés pour libérer de l'espace. Si vos instructions initiales (ton, format, contraintes) ne sont pas protégées, elles disparaissent du résumé. Vous vous retrouvez avec un assistant qui a « oublié » vos consignes.

Le fichier CLAUDE.md à la racine de votre projet est la solution. Son contenu est rechargé à chaque compaction et persiste indéfiniment. Concrètement, la plupart des pertes d'instructions sont évitables via ce fichier.

<!-- ❌ Incorrect - instructions dans le premier message -->
"Tu es un expert React, utilise TypeScript strict, 
pas de any, préfère les composants fonctionnels..."

<!-- ✅ Correct - fichier CLAUDE.md à la racine du projet -->
# CLAUDE.md
## Conventions
- TypeScript strict, jamais de `any`
- Composants fonctionnels React uniquement
- Tests avec Vitest, couverture > 80%
- Commits conventionnels (feat:, fix:, chore:)

Créez un fichier CLAUDE.md dès le premier jour sur chaque projet. Les commandes personnalisées et skills vous montrent comment enrichir ce fichier avec des conventions d'équipe.

À retenir : le fichier CLAUDE.md est votre ancrage permanent : il survit à toutes les compactions et garantit la cohérence de vos sessions.

Pourquoi le copier-coller massif est-il contre-productif ?

Sévérité : Avertissement

Coller 500 lignes de logs ou un fichier entier dans le chat est un réflexe naturel, mais destructeur. Un bloc de 500 lignes consomme plusieurs milliers de tokens (ordre de grandeur indicatif), souvent pour des informations en grande partie non pertinentes.

Claude Code sait lire les fichiers directement depuis votre système. Utilisez les références de fichiers plutôt que le copier-coller pour préserver votre contexte.

# ❌ Incorrect - coller tout le log d'erreur
$ claude "Voici mon log d'erreur : [500 lignes de stack trace]..."

# ✅ Correct - référencer le fichier et filtrer
$ claude "Analyse les erreurs dans logs/error.log, concentre-toi sur les lignes contenant 'TypeError' après le timestamp 14:30"

En pratique, la référence de fichier consomme bien moins de tokens que le copier-coller car Claude Code lit uniquement les sections pertinentes. Les erreurs d'intégration Git illustrent d'autres situations où le copier-coller de diffs volumineux sature le contexte.

À retenir : référencez les fichiers au lieu de les coller : vous économiserez la quasi-totalité des tokens pour la même information.

Peut-on utiliser Claude Code efficacement sans connaître l'anatomie des tokens ?

Sévérité : Mineur

Un token n'est pas un mot. En français, un mot courant représente 1,3 à 1,8 token en moyenne. Les termes techniques (noms de fonctions, chemins de fichiers) consomment 2 à 4 tokens chacun. Ignorer cette réalité fausse votre estimation de la capacité restante.

La tokenisation est le processus de découpage du texte en unités compréhensibles par le modèle. Le tokenizer de Claude découpe le texte en sous-unités, souvent plus petites qu'un mot, selon un algorithme propre à Anthropic qui n'est pas documenté publiquement.

# Exemple de consommation de tokens
"hello" # → 1 token
"authentication" # → 2 tokens 
"src/components/UserDashboard.tsx" # → 7 tokens
"const handleUserAuthenticationCallback = async (req, res) =>" # → 15 tokens

Le tableau suivant donne des ordres de grandeur indicatifs (la tokenisation réelle varie selon le contenu et le modèle) :

Pour une maîtrise complète du sujet, la page dédiée à la gestion du contexte couvre l'anatomie de la fenêtre de contexte en détail.

À retenir : le code consomme sensiblement plus de tokens que le texte : intégrez ce facteur dans votre estimation de capacité.

Quand faut-il lancer une nouvelle session plutôt que continuer ?

Sévérité : Avertissement

Persister dans une session saturée est l'erreur la plus coûteuse en temps. Au-delà de 85 % de remplissage, chaque réponse prend nettement plus de temps à générer et sa qualité chute. Pourtant, de nombreux utilisateurs continuent jusqu'à l'échec total.

Voici comment identifier le moment de basculer :

1. Les réponses deviennent répétitives ou hors sujet
2. Claude Code « oublie » des instructions données plus tôt
3. La commande /context indique plus de 80 % de remplissage de la fenêtre
4. Le temps de réponse dépasse 30 secondes pour des requêtes simples
5. Les blocs de code générés contiennent des erreurs de syntaxe inhabituelles

# ❌ Incorrect - forcer la continuation
$ claude "Je répète : utilise TypeScript, pas JavaScript !"

# ✅ Correct - nouvelle session avec contexte résumé
$ claude "Reprends le refactoring de src/api/.
Contexte : on migre les callbacks vers async/await.
Fichiers restants : userService.ts, orderService.ts"

Vérifiez les signaux de saturation et n'hésitez pas à relancer une session propre. Les erreurs du mode headless montrent que cette discipline est encore plus critique en environnement CI/CD.

À retenir : au-delà de 80 % de contexte utilisé, une nouvelle session est plus efficace que la compaction.

Comment structurer un fichier CLAUDE.md pour maximiser la rétention de contexte ?

Sévérité : Mineur

Un fichier CLAUDE.md mal structuré gaspille des tokens sur des informations secondaires. La structure optimale priorise les conventions critiques en haut du fichier, car Claude Code accorde plus de poids aux premières lignes.

un CLAUDE.md bien structuré réduit les erreurs de convention et économise des tokens à chaque session.

<!-- ❌ Incorrect - CLAUDE.md fourre-tout -->
# Mon projet
Ceci est un projet React créé en 2024...
[200 lignes d'historique du projet]
Ah oui, utiliser TypeScript strict.

<!-- ✅ Correct - CLAUDE.md structuré par priorité -->
# CLAUDE.md
## Règles critiques (toujours respecter)
- TypeScript strict, `noAny: true`
- Composants fonctionnels + hooks uniquement
- Pas de console.log en production

## Conventions de code
- Nommage : camelCase pour variables, PascalCase pour composants
- Imports : relatifs pour le projet, absolus pour node_modules

## Stack technique
- React 19, Next.js 15, Vitest 3.0
- Node.js 22 LTS, pnpm 9

Organisez votre CLAUDE.md en sections par ordre de priorité décroissante. Les règles critiques doivent apparaître dans les 20 premières lignes.

SFEIR propose la formation Claude Code sur une journée complète : vous y apprendrez à configurer le fichier CLAUDE.md, à maîtriser la compaction et à piloter des sessions multi-contextes avec des exercices pratiques sur des projets réels.

Pour aller plus loin, la formation Développeur Augmenté par l'IA (2 jours) couvre l'intégration de Claude Code dans un workflow de développement complet, du pair programming à la revue de code. Et si vous maîtrisez déjà les bases, la formation Développeur Augmenté par l'IA – Avancé (1 jour) approfondit les stratégies avancées de gestion de contexte et d'orchestration multi-agents.

À retenir : structurez votre CLAUDE.md avec les règles critiques en premier : les 20 premières lignes ont le plus d'impact.

Y a-t-il un résumé des erreurs classées par gravité ?

Voici la synthèse des 10 erreurs les plus fréquentes en gestion du contexte Claude Code, classées par sévérité :

1. Surcharge de fichiers (Critique) : charger tout le projet sature une grande partie du contexte avant toute question utile.
2. Ignorer le mode Plan (Critique) : l'exécution directe consomme davantage de tokens.
3. Absence de compaction (Critique) : sans auto-compact, le contexte sature rapidement sur les longues sessions.
4. Perte d'instructions après compaction (Critique) : sans CLAUDE.md, les consignes disparaissent.
5. Prompts vagues (Avertissement) : un prompt imprécis augmente fortement la consommation de tokens.
6. Session unique pour tout (Avertissement) : refuser le multi-sessions réduit fortement la capacité effective.
7. Pas de monitoring (Avertissement) : de nombreux utilisateurs ne vérifient jamais leur consommation.
8. Copier-coller massif (Avertissement) : coller 500 lignes gaspille plusieurs milliers de tokens inutilement.
9. Persister en session saturée (Avertissement) : au-delà de 85 % de remplissage, la qualité des réponses se dégrade nettement.
10. CLAUDE.md non structuré (Mineur) : un fichier mal organisé gaspille des tokens à chaque session.

Pour une vision complète des bonnes pratiques, consultez les astuces de gestion du contexte et l'analyse approfondie du fonctionnement interne.

À retenir : corrigez les 4 erreurs critiques en priorité - elles représentent à elles seules la majorité des pertes de productivité liées au contexte.