Gestion du contexte - Exemples

Gérer efficacement la fenêtre de contexte de Claude Code fait la différence entre une session productive et une session qui tourne en rond. Voici 10 exemples concrets (du monitoring basique des tokens à la compaction automatique par hooks) pour optimiser chaque interaction avec l'agent. Apprenez à configurer le mode Plan, le multi-sessions et les stratégies de scaling horizontal.

La gestion du contexte dans Claude Code est la discipline qui consiste à surveiller, optimiser et répartir les tokens disponibles par session pour maximiser la qualité des réponses de l'agent. Les modèles actuels (Opus 4.6 et plus, Sonnet 4.6) offrent une fenêtre pouvant atteindre 1 million de tokens, tandis que 200 000 tokens restent la valeur par défaut des modèles plus anciens et des déploiements Bedrock, Vertex et Foundry. Claude Code offre plusieurs mécanismes natifs pour piloter cette fenêtre de contexte.

plus la fenêtre de contexte se remplit, plus la précision des réponses tend à se dégrader. La maîtrise de ces techniques transforme votre flux de travail quotidien.

Comment visualiser l'utilisation de la fenêtre de contexte ?

Avant d'optimiser quoi que ce soit, mesurez votre consommation réelle de tokens. Claude Code affiche un indicateur de remplissage dans la barre de statut, mais vous pouvez obtenir des données plus précises.

Pour comprendre les fondamentaux de la fenêtre de contexte, consultez le guide complet sur la gestion du contexte qui couvre l'anatomie de la fenêtre en détail.

Exemple 1 : Vérifier le taux de remplissage en session

Contexte : Vous êtes en pleine session de refactoring et voulez savoir combien de tokens il vous reste avant la compaction automatique.

# Tapez cette commande dans le prompt Claude Code
/context

Résultat attendu :

La commande /context visualise le taux de remplissage de la fenêtre de contexte et détaille la répartition des tokens par élément (instructions système, fichiers, messages, outils). Utilisez /context all pour obtenir la décomposition complète.

Variante : Ajoutez la commande /cost (alias de /usage) pour voir le coût de votre session et vos statistiques d'utilisation par rapport aux limites de votre plan. En pratique, une session qui atteint 80 % de la fenêtre peut coûter cher en tokens d'entrée.

À retenir : Vérifiez votre taux de remplissage dès que vous dépassez 30 minutes de session continue.

Comment réduire la taille des fichiers injectés dans le contexte ?

Les fichiers lus par Claude Code consomment des tokens précieux. Ciblez précisément ce que vous injectez plutôt que de laisser l'agent lire des fichiers entiers.

Si vous rencontrez des erreurs liées au dépassement de contexte, le guide des erreurs courantes de gestion du contexte détaille les solutions pour chaque cas.

Exemple 2 : Limiter la lecture aux lignes pertinentes

Contexte : Vous demandez à Claude Code de corriger un bug dans un fichier de 2 000 lignes. Lire le fichier entier consommerait environ 8 000 tokens.

# ❌ Mauvaise pratique : lecture complète
"Lis le fichier src/services/auth.ts et corrige le bug ligne 847"

# ✅ Bonne pratique : lecture ciblée
"Lis les lignes 830-870 de src/services/auth.ts et corrige le bug de validation du token JWT"

Résultat attendu : La lecture ciblée consomme environ 200 tokens au lieu de 8 000, soit une réduction de 97,5 %. L'agent conserve suffisamment de contexte pour comprendre le code environnant.

Exemple 3 : Utiliser.gitignore pour exclure les fichiers volumineux

Contexte : Votre projet contient des fichiers générés (bundles, lock files) que Claude Code tente de lire. Claude Code respecte le .gitignore de votre projet pour exclure automatiquement ces fichiers.

# Vérifiez ou éditez.gitignore à la racine du projet
dist/
build/
node_modules/
*.lock
*.min.js
coverage/
*.map

Résultat attendu : Les fichiers listés dans .gitignore ne sont plus indexés ni proposés en lecture. Sur un projet riche en fichiers générés, cette configuration réduit sensiblement l'espace de recherche et les fichiers proposés en lecture.

Variante : Ajoutez les dossiers de données de test (__fixtures__/, __snapshots__/) si vos snapshots sont volumineux.

À retenir : chaque fichier non pertinent exclu via .gitignore libère des tokens pour le raisonnement de l'agent.

Quels sont les niveaux de difficulté pour optimiser le contexte ?

Voici un tableau comparatif des stratégies selon votre niveau d'expérience avec Claude Code.

le mode Plan réduit la consommation de tokens car l'agent explore le code en lecture seule et n'effectue aucune modification ni exécution pendant la phase de réflexion. Il sépare la planification de l'exécution.

À retenir : commencez par .gitignore et les lectures ciblées avant de passer aux stratégies avancées.

Comment activer et utiliser le mode Plan pour économiser des tokens ?

Le mode Plan est un mécanisme natif de Claude Code qui sépare la phase de réflexion de la phase d'exécution. Activez-le quand vous travaillez sur des tâches complexes nécessitant une exploration préalable du code.

Pour découvrir d'autres astuces d'optimisation, le recueil d'astuces pour la gestion du contexte propose des techniques complémentaires.

Exemple 4 : Lancer une session en mode Plan

Contexte : Vous devez refactorer un module d'authentification (12 fichiers). Sans mode Plan, l'agent lirait tous les fichiers et commencerait à éditer immédiatement, saturant le contexte.

# Activez le mode Plan avec Shift+Tab dans le prompt Claude Code
# ou appuyez sur le raccourci dédié
# L'indicateur passe de "Auto" à "Plan"

# Ensuite, décrivez votre tâche :
"Analyse le module auth/ et propose un plan de refactoring pour
remplacer les callbacks par des async/await"

Résultat attendu (exemple illustratif, la sortie réelle varie) : Claude Code bascule en mode Plan, signale qu'aucune modification de fichier ne sera effectuée, présente un plan d'action structuré (fichiers concernés, ordre des dépendances, séquence de migration), puis vous invite à approuver, refuser ou éditer le plan avant toute exécution. À titre d'illustration :

[Plan Mode] Aucune modification de fichier ne sera effectuée

Plan : refactoring du module auth/ vers async/await
1. Identifier les fichiers utilisant des callbacks
2. Cartographier l'ordre des dépendances (auth.service → auth.guard → auth.middleware)
3. Proposer une séquence de migration avec stratégie de rollback

[Approuver / Refuser / Éditer le plan]

Variante : Combinez le mode Plan avec la commande /cost pour estimer le coût avant d'approuver l'exécution. En pratique, une session de planification consomme nettement moins de tokens qu'une exécution directe, car l'agent reste en lecture seule.

Exemple 5 : Basculer entre Plan et exécution

Contexte : Vous avez approuvé le plan et voulez maintenant exécuter uniquement l'étape 2 pour limiter la consommation de contexte.

# Après approbation du plan, cyclez les modes de permission avec Shift+Tab
# (ou Alt+M) jusqu'au mode souhaité (par ex. Auto si activé)
# Puis demandez l'exécution partielle :
"Exécute uniquement l'étape 2 du plan : mapper les dépendances
du module auth/"

Résultat attendu : L'agent n'exécute que la portion demandée, ce qui économise une grande partie de la fenêtre de contexte par rapport à l'exécution du plan complet.

À retenir : le mode Plan est votre meilleur allié pour les tâches de plus de 5 fichiers, utilisez-le systématiquement.

Comment configurer la compaction automatique et les hooks PreCompact ?

La compaction est le mécanisme qui résume automatiquement la conversation quand le contexte approche sa limite. Configurez des hooks PreCompact pour contrôler ce qui est préservé lors de cette opération.

Pour des exemples d'intégration de hooks dans un pipeline CI/CD, consultez les exemples de mode headless et CI/CD.

Exemple 6 : Déclencher une compaction manuelle

Contexte : Après 45 minutes de session, votre contexte atteint 78 %. Vous voulez compacter avant qu'il n'atteigne le seuil automatique de 95 %.

# Dans le prompt Claude Code
/compact

# Ou avec un résumé personnalisé pour guider la compaction :
/compact "Garde uniquement : le plan de refactoring auth/,
les 3 fichiers modifiés et les résultats de tests"

Résultat attendu (exemple illustratif, la sortie réelle varie) : Claude Code résume la conversation et reprend la session avec un contexte nettement allégé. Schématiquement, le déroulé ressemble à ceci :

Compaction en cours...
- Avant : contexte proche de la limite
- Après : contexte fortement réduit
- Préservé : plan, fichiers modifiés, résultats de tests
- Résumé : les anciens échanges sont condensés en un bloc de synthèse

La compaction réduit fortement le contexte tout en préservant les éléments critiques de la session.

Exemple 7 : Configurer un hook PreCompact dans settings.json

Contexte : Vous voulez sauvegarder automatiquement un snapshot de la conversation avant chaque compaction, en cas de besoin de rollback.

// ~/.claude/settings.json
{
 "hooks": {
 "PreCompact": [
 {
 "matcher": "auto",
 "hooks": [
 {
 "type": "command",
 "command": "bash -c 'mkdir -p ~/.claude/snapshots && jq -r .transcript_path | xargs -I{} cp {} ~/.claude/snapshots/$(date +%Y%m%d_%H%M%S).jsonl'",
 "timeout": 5
 }
 ]
 }
 ]
 }
}

Résultat attendu : À chaque compaction (manuelle ou automatique), le hook reçoit sur stdin un objet JSON contenant le champ transcript_path. La commande lit ce chemin avec jq puis copie le transcript de la conversation (un fichier .jsonl) horodaté dans ~/.claude/snapshots/. La taille du fichier dépend de la longueur de la session.

Variante : Ajoutez un hook qui envoie une notification Slack quand la compaction se déclenche automatiquement :

{
 "hooks": {
 "PreCompact": [
 {
 "matcher": "auto",
 "hooks": [
 {
 "type": "command",
 "command": "curl -s -X POST $SLACK_WEBHOOK -d '{\"text\":\"⚠️ Compaction auto déclenchée\"}'",
 "timeout": 3
 }
 ]
 }
 ]
 }
}

Pour aller plus loin dans la personnalisation des hooks et commandes, explorez les exemples de commandes personnalisées et skills.

À retenir : la compaction manuelle avec instructions de préservation donne de meilleurs résultats que la compaction automatique.

Comment mettre en place le multi-sessions pour scaler horizontalement ?

Quand un projet dépasse la capacité d'une seule fenêtre de contexte, répartissez le travail sur plusieurs sessions Claude Code en parallèle. Le multi-sessions est un pattern de scaling horizontal.

Exemple 8 : Lancer des sessions parallèles par domaine

Contexte : Vous développez une fonctionnalité full-stack (API + frontend + tests). Chaque domaine mérite sa propre session pour éviter la pollution croisée du contexte.

# Terminal 1 : session API
cd ~/project && claude -p "Refactore l'API"
# → "Implémente les endpoints REST pour le module payment/"

# Terminal 2 : session Frontend
cd ~/project && claude -p "Travaille sur le frontend de paiement"
# → "Crée les composants React pour le formulaire de paiement"

# Terminal 3 : session Tests
cd ~/project && claude -p "Écris les tests de paiement"
# → "Écris les tests d'intégration pour le module payment/"

Résultat attendu : Chaque session dispose de sa propre fenêtre de contexte dédiée (jusqu'à 1 million de tokens sur les modèles actuels, 200 000 par défaut sur les modèles plus anciens ou les déploiements Bedrock, Vertex et Foundry). Les sessions ne partagent pas leur contexte, ce qui élimine la dégradation de précision liée au remplissage et multiplie la capacité totale par le nombre de sessions.

Exemple 9 : Synchroniser les sessions via des fichiers partagés

Contexte : Vos sessions parallèles doivent partager des décisions architecturales sans polluer mutuellement leur contexte.

# Créez un fichier de coordination à la racine du projet
# que chaque session peut lire au besoin

# Dans CLAUDE.md du projet, ajoutez :
echo '## Décisions partagées
- Format API : REST JSON, pagination cursor-based
- Validation : Zod côté API, React Hook Form côté client
- Auth : JWT avec refresh token (expiry 15min/7j)' >> CLAUDE.md

Résultat attendu : Chaque session lit CLAUDE.md au démarrage (environ 500 tokens) et dispose des mêmes conventions sans dupliquer l'information dans le contexte conversationnel.

Le fichier CLAUDE.md consomme en moyenne 300 à 800 tokens selon sa taille. Pour apprendre à le configurer après une première installation, suivez le démarrage rapide de Claude Code.

À retenir : le multi-sessions multiplie votre capacité de contexte, utilisez-le pour tout projet touchant plus de 3 domaines distincts.

Quels patterns avancés utiliser pour les projets à grande échelle ?

Les projets d'entreprise avec des dizaines de microservices nécessitent des stratégies de contexte plus sophistiquées. Concrètement, voici deux patterns éprouvés par les équipes qui utilisent Claude Code en production.

Exemple 10 : Pipeline de contexte avec résumé intermédiaire

Contexte : Vous analysez 50 fichiers pour un audit de sécurité. Impossible de tout charger dans une seule session.

# Étape 1 : Session de scan (résumé)
claude -p "Scanne tous les fichiers de src/api/ et génère
 un rapport des vulnérabilités potentielles. Écris le résultat
 dans audit-report.md"

# Étape 2 : Session de correction (ciblée)
claude -p "Lis audit-report.md et corrige les 5 vulnérabilités
 critiques identifiées"

Résultat attendu : La première session produit un rapport de 1 500 tokens résumant 50 fichiers. La seconde session démarre avec ce résumé au lieu des 50 fichiers bruts, soit une réduction substantielle du contexte. Ce pattern réduit nettement le temps de résolution sur les audits de sécurité.

Pour apprendre à chaîner ces sessions dans un pipeline Git automatisé, consultez les exemples d'intégration Git.

Exemple 11 : Compaction sélective avec instructions de préservation

Contexte : Vous êtes en session depuis 2 heures et le contexte atteint 92 %. Vous voulez compacter mais préserver des éléments spécifiques.

/compact "PRÉSERVE OBLIGATOIREMENT :
1. Le schéma de base de données (tables users, orders, payments)
2. Les 4 endpoints API créés (POST /orders, GET /orders/:id,
 PATCH /orders/:id, DELETE /orders/:id)
3. Les résultats du dernier test run (3 passed, 1 failed)
SUPPRIME : toutes les explorations de code, les lectures de fichiers,
les tentatives échouées"

Résultat attendu (exemple illustratif, la sortie réelle varie) : Claude Code applique vos instructions de préservation et reprend la session avec un contexte allégé. De façon schématique :

Compaction sélective en cours...
- Avant : contexte proche de la limite
- Après : contexte fortement réduit
- Préservé : schéma de base de données, endpoints, résultats de tests
- Supprimé : explorations de code et lectures de fichiers

En pratique, la compaction sélective avec instructions conserve l'essentiel de la pertinence tout en libérant une grande partie du contexte. Pour éviter les pièges fréquents de la compaction, le guide des erreurs courantes recense les cas typiques de perte d'information.

À retenir : sur les projets de plus de 20 fichiers, combinez multi-sessions et compaction sélective pour une efficacité maximale.

Comment mesurer l'impact de vos optimisations de contexte ?

Quantifiez les gains de chaque stratégie pour ajuster votre approche projet par projet. Voici les métriques à surveiller.

Exemple 12 : Tableau de bord de suivi des tokens par session

Contexte : Vous voulez comparer l'efficacité de vos sessions avec et sans optimisation.

# Script de suivi à ajouter dans package.json
# ou à exécuter manuellement après chaque session

claude -p "Résous le bug #142 dans src/cart/checkout.ts" \
 2>&1 | tee /tmp/claude-session.log

# Extraire les métriques de la session
grep "tokens" /tmp/claude-session.log

Résultat attendu, tableau comparatif (à titre d'illustration, sur des sessions internes) :

Ces ordres de grandeur sont indicatifs et varient selon le projet, le modèle et la nature des tâches. Concrètement, une équipe qui applique ces optimisations sur un projet actif réduit sensiblement sa consommation de tokens d'entrée, donc sa facture mensuelle.

Pour retrouver rapidement les commandes essentielles, l'aide-mémoire de gestion du contexte résume toutes les commandes en une page.

SFEIR Institute propose la formation Claude Code sur 1 journée : vous y pratiquerez ces techniques d'optimisation de contexte sur des projets réels en lab, avec des métriques de suivi en temps réel. Pour une maîtrise complète de l'IA en développement, la formation Développeur Augmenté par l'IA (2 jours) couvre l'ensemble des outils et stratégies, du prompt engineering au scaling multi-agents.

Les développeurs déjà à l'aise avec les bases peuvent suivre le module Développeur Augmenté par l'IA – Avancé (1 jour) pour approfondir les patterns de compaction, les hooks et le multi-sessions.

À retenir : mesurez systématiquement avant et après chaque optimisation. Sans données chiffrées, vous optimisez à l'aveugle.

Quelles sont les questions fréquentes sur la gestion du contexte ?

Pour un traitement exhaustif des questions les plus posées, consultez la FAQ dédiée à la gestion du contexte.

Concrètement, la majorité des problèmes de contexte se résolvent avec deux techniques : .gitignore et la compaction manuelle ciblée. Les équipes qui maîtrisent le contexte de Claude Code gagnent en productivité par rapport à celles qui laissent l'agent gérer seul.

Pour compléter votre apprentissage, le tutoriel d'installation et premier lancement vous guide pas à pas dans la configuration initiale de votre environnement.

À retenir : la gestion du contexte n'est pas un réglage ponctuel. C'est une discipline continue qui s'affine avec la pratique.