Gestion du contexte de Claude Code
La gestion du contexte est une compétence essentielle pour utiliser Claude Code efficacement.
La documentation officielle déclare explicitement :« La fenêtre de contexte est la ressource la plus importante de Claude Code »Au fur et à mesure que le contexte se remplit, les performances du modèle diminuent progressivement (appelé context rot) — c'est un problème central à combattre activement lors de l'utilisation de Claude Code.
Ce chapitre explique en détail comment utiliser les fichiers d'instructions CLAUDE.md, le système de mémoire automatique et les commandes d'optimisation de la fenêtre de contexte pour maintenir Claude efficace dans les sessions longues et entre les sessions.
Principes de base de la fenêtre de contexte
1. Ce que contient la fenêtre de contexte
La taille de la fenêtre de contexte de Claude Code est de1,000,000 tokens (1 million tokens)Elle contient tout ce que Claude « voit » dans la session en cours :
| Source du contenu | Moment de chargement | Utilisation des tokens |
|---|---|---|
| Prompt système (directives comportementales de Claude Code) | Chargé au démarrage de chaque session | Utilisation fixe |
| Fichier CLAUDE.md | Entièrement chargé au démarrage | Dépend de la taille du fichier |
| Mémoire automatique | Chargé au démarrage (200 premières lignes ou 25KB) | A une limite |
| Historique de conversation | S'accumule | Augmente en continu avec la session |
| Résultats des outils (lectures de fichiers, sorties de commandes, etc.) | Ajoutés après chaque appel d’outil | Les journaux/les fichiers volumineux consomment très rapidement des tokens |
| Noms des outils MCP, descriptions des Skills, etc. | Chargés au démarrage | Moyenne |
2. Dégradation du contexte
La documentation officielle indique explicitement : à mesure que le contexte se remplit,les performances des LLM vont diminuercar l’attention est répartie sur davantage de tokens, et le contenu ancien et non pertinent commence à interférer avec la tâche en cours. Les symptômes spécifiques incluent :
- Claude devient contradictoire et oublie des décisions convenues précédemment
- Les réponses deviennent vagues et générales, avec moins de détails
- Poser la même question de façon répétée alors qu’elle a déjà reçu une réponse
- Corriger le même problème plus de deux fois dans la même session
Si les symptômes ci-dessus apparaissent, cela signifie que le contexte est déjà « pollué ». À ce stade, vous devriez utiliser proactivement/compactou/clearpour le gérer, plutôt que de continuer à corriger dans la même session.
Utilisez la/contextcommande pour afficher à tout moment une analyse détaillée de l'utilisation du contexte actuel :
/context
Il répertorie l'utilisation des tokens par catégorie (prompt système, CLAUDE.md, fichiers de mémoire, historique de session, etc.) et fournit des suggestions d'optimisation. Il est recommandé de vérifier une fois avant de commencer des tâches importantes.
Fichier d'instructions CLAUDE.md
CLAUDE.md est le fichier central de Claude Code qui enregistre les instructions statiques et les conventions de projet. Au début de chaque session, Claude le charge automatiquement dans la fenêtre de contexte.
1. Emplacement de stockage et portée
CLAUDE.md prend en charge plusieurs emplacements,les emplacements plus spécifiques ont une priorité plus élevée:
| Portée | Chemin du fichier | Cas d'utilisation | Effectuer un commit dans git ? |
|---|---|---|---|
| Niveau organisation | macOS: /Library/Application Support/ClaudeCode/CLAUDE.mdLinux/WSL: /etc/claude-code/CLAUDE.md |
Normes de codage de l'entreprise, exigences de conformité | Géré de manière centralisée par l'IT |
| Niveau projet | ./CLAUDE.mdou./.claude/CLAUDE.md |
Architecture du projet, normes de codage, flux de travail | Oui, partagé avec l'équipe |
| Niveau utilisateur | ~/.claude/CLAUDE.md |
Préférences de codage personnelles, s'applique à tous les projets | Non, personnellement privé |
| Privé local | ./CLAUDE.local.md(ajouter à .gitignore) |
Configuration personnelle spécifique au projet, non commitée dans git | Non, ajouter à .gitignore |
CLAUDE.local.mdC'est la méthode officiellement recommandée pour la configuration privée personnelle : les URL de bac à sable, les comptes de test locaux, les habitudes de débogage personnelles et les autres contenus qui ne doivent pas être partagés doivent être placés ici plutôt queCLAUDE.mddans. Exécuter/initlors de la sélection de l'option « Personal », il ajoutera automatiquement le fichier à.gitignore。
2. Création de CLAUDE.md
Exécutez la commande suivante, et Claude analysera automatiquement le projet et générera un fichier CLAUDE.md initial :
/init
Si un CLAUDE.md existe déjà,/initil proposera des améliorations plutôt que de l'écraser directement. Après la génération, ajoutez manuellement le contenu que Claude ne peut pas découvrir automatiquement (comme les fichiers qui ne doivent pas être modifiés, les contraintes spécifiques, etc.).
Vous pouvez également utiliser dans la session#le raccourci clavier pour ajouter rapidement une mémoire à CLAUDE.md :
# 所有 API 错误响应必须使用 { code, message } 格式
Appuyez sur#après avoir saisi le contenu et appuyé sur Entrée, Claude l'écrira dans le CLAUDE.md au niveau correspondant et l'enregistrera comme instruction persistante.
3. Exigences relatives au contenu de CLAUDE.md
L'exigence officielle est que chaque fichier CLAUDE.mdsoit limité à 200 lignes. Plus le fichier est volumineux, plus il consomme de tokens au démarrage, et plus le taux de conformité de Claude diminue. Voici des recommandations de contenu :
Doit inclure :
- Commandes courantes pour la compilation, les tests et le déploiement
- Style de code : conventions de nommage, indentation, motifs interdits
- Contraintes clés : "toujours utiliser pnpm", "ne pas modifier le répertoire migrations/"
- Description de l'architecture du projet : l'objectif des répertoires principaux
Ne doit pas inclure :
- Flux de travail opérationnels en plusieurs étapes (doivent être placés dans le fichier Skills)
- Règles pertinentes uniquement pour une partie spécifique de la base de code (doivent utiliser
.claude/rules/un ciblage basé sur le chemin) - Informations que Claude peut découvrir par lui-même en lisant le code
Exemples
## Commandes courantes
- Gestion des paquets : toujours utiliser pnpm, ne pas utiliser npm ou yarn
- Exécuter les tests : pnpm test:watch
- Compilation : pnpm build
## Style de code
- Mode strict TypeScript, `any` n'est pas autorisé
- Les fichiers de composants utilisent la convention de nommage PascalCase (par exemple, UserProfile.tsx)
- Les horodatages de base de données utilisent systématiquement le format UTC
## Contraintes
- La modification directe des fichiers existants dans le répertoire prisma/migrations/ est interdite
- .env.local contient de véritables secrets ; il est interdit de lire ou d'afficher le contenu du fichier
- Les points de terminaison de l'API sont gérés uniformément dans le répertoire src/api/ ; n'effectuez pas de requêtes directement ailleurs
4. Règles de portée basées sur le chemin (.claude/rules/)
Pour les projets plus volumineux, vous pouvez utiliser.claude/rules/répertoire pour diviser les instructions en règles granulaires qui s'appliquent selon le chemin de fichier, en évitant que toutes les règles soient entassées dans le CLAUDE.md racine et consomment des tokens au démarrage :
.claude/
└── rules/
├── api.md # 只对 src/api/**/*.ts 文件生效
├── frontend.md # 只对 src/components/**/*.tsx 文件生效
└── testing.md # 只对 *.test.ts 文件生效
Les règles limitées à un chemin ne sont chargées que lorsque Claude lit des fichiers dans le répertoire correspondant ; elles n'occupent pas tout le contexte au démarrage.
Mémoire automatique
La mémoire automatique est un système de mémoire inter-sessions intégré à Claude Code v2.1.59 et versions ultérieures.Elle est activée par défautet ne nécessite aucune configuration. Elle permet à Claude d'enregistrer de manière autonome les informations découvertes pendant le travail, telles que les commandes de build, l'expérience de débogage et les préférences de style de code.
1. Comment ça fonctionne
- Claude n'écrit pas de mémoire à chaque session ; il juge si l'information vaut la peine d'être conservée (si elle sera utile dans de futures conversations).
- La mémoire est isolée par chemin de dépôt git et stockée dans
~/.claude/projects/<项目路径>/memory/ - Tous les worktrees d'un même dépôt partagent une même mémoire automatique.
- Lors de l'écriture de la mémoire, le terminal affiche « Writing memory » ; lors d'une récupération ultérieure, il affiche « Recalled memory ».
2. Affichage et modification de la mémoire (/memory)
Utilisez la/memorycommande pour afficher et modifier tout le contenu de mémoire, y compris les CLAUDE.md à différents niveaux et la mémoire automatique :
/memory
Dans l'éditeur, vous pouvez supprimer les entrées inexactes, ou utiliser l'interrupteur Auto memory pour désactiver la mémoire automatique. Vous pouvez aussi la désactiver temporairement via des variables d'environnement :
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude
3. Faire mémoriser proactivement du contenu à Claude
En conversation, vous pouvez demander directement à Claude d'écrire une mémoire :
记住:我们的 API 测试需要本地运行一个 Redis 实例
以后请记住:处理错误时,统一返回 { code, message } 结构
Si vous voulez la transformer en règle obligatoire plutôt qu'en simple mémoire de préférence, vous pouvez dire : « Écris cette règle dans CLAUDE.md », et Claude l'écrira dans le fichier CLAUDE.md correspondant.
Commandes d'optimisation de la fenêtre de contexte
1. Compactage automatique
Claude Code déclenche automatiquement le compactage lorsque lecontexte approche de la limite(à environ 75% d'utilisation), en résumant l'historique de conversation en un condensé et en poursuivant le travail. Cependant, la recommandation officielle est de ne pas attendre le compactage automatique ; à la place,déclenchez-le proactivement manuellement à 60~70%.Cela évite d'être interrompu au milieu de tâches critiques, et le compactage manuel vous permet de contrôler le contenu conservé via des instructions.
2. Compactage du contexte (/compact)
Compacter manuellement l'historique de conversation, en résumant les longues sessions en un résumé concis pour continuer à travailler :
/compact
/compactPrend en charge le passage d'instructions personnalisées pour contrôler le contenu à prioriser lors du compactage :
/compact Focus on the API changes
/compact 保留认证流程的架构决策,丢弃调试过程中的无效尝试
La compaction est une opération avec perte. Pendant la compaction, Claude se trouve dans l'état où le contexte est le plus rempli et les performances sont les plus faibles. Si vous ne donnez pas d'instructions, il peut supprimer du contenu que vous jugez important.Compactez proactivement immédiatement après les décisions majeures, et utilisez des instructions pour préciser ce qu'il faut conserver.Cela fonctionne bien mieux que d'attendre le compactage automatique.
3. Effacement du contexte (/clear)
Efface tout l'historique de conversation lors du passage à une toute nouvelle tâche :
/clear
Après l'effacement, CLAUDE.md et la mémoire automatique ne sont pas affectés et seront toujours chargés dans les nouvelles sessions. Recommandation officielle :Si vous avez corrigé le même problème plus de deux fois dans la même session, faites simplement /clear et redémarrez avec un prompt plus précis comportant les contraintes que vous avez apprises.—Une session propre avec un meilleur prompt vaut presque toujours mieux que de continuer à corriger dans un contexte pollué.
4. Retour à un point de contrôle (/rewind)
Claude Code crée automatiquement un point de contrôle avant chaque modification de fichier. Double-cliquezEscou exécutez/rewindpour ouvrir le menu de retour en arrière et sélectionner le point de contrôle à restaurer :
/rewind
(或双击 Esc 键)
Dans le menu de retour en arrière, vous pouvez choisir les actions suivantes :
| Action | Effet | Cas d'utilisation |
|---|---|---|
| Restaurer la conversation + le code | Restaure l'historique de conversation et les modifications de fichiers, en restaurant entièrement l'état. | Lorsque Claude a dévié et que les modifications posent problème ; annulez tout. |
| Restaurer la conversation uniquement | Rétablit l’historique de conversation, conserve les modifications de fichiers. | Lorsque vous voulez réessayer une approche différente tout en conservant les modifications de code. |
| Restaurer uniquement le code | Restaure les fichiers à l’état du point de contrôle, conserve la conversation. | Lorsque le code est cassé mais que l’analyse dans la conversation reste précieuse. |
| Résumer à partir d’ici | Compresse la conversation après le point de contrôle en un résumé, en préservant tout l’historique qui le précède. | Lorsque vous voulez simplement nettoyer la conversation redondante dans la dernière partie tout en conservant tout le contexte antérieur. |
Les points de contrôle persistent entre les sessions—vous pouvez toujours revenir à des points de contrôle précédents après avoir fermé le terminal. Ce n’est pas un remplacement de git, mais c’est plus pratique que le git stash manuel dans les expérimentations exploratoires.
5. Questions rapides sans polluer le contexte (/btw)
Si vous devez rapidement rechercher un petit détail mais que vous ne voulez pas que les questions-réponses entrent dans l’historique de conversation (ce qui consomme du contexte), utilisez/btw:
/btw 这个项目的 TypeScript 版本是多少?
La réponse s’affichera dans une couche flottante, et ni la question ni la réponse n’entreront dans l’historique de conversation. Convient pour rechercher la configuration, les numéros de version et autres informations ponctuelles qui n’ont pas besoin d’être conservées.
Commandes de gestion de session
| Commande | Fonction | Cas d'utilisation |
|---|---|---|
/context |
Afficher une analyse détaillée de l'utilisation des tokens pour chaque partie du contexte | Diagnostiquer quelle partie a consommé trop de tokens |
/compact [指令] |
Compresser l'historique de conversation en un résumé, avec l'option de préciser ce qu'il faut conserver | Compresser de manière proactive lorsque le contexte est à 60~70% |
/clear |
Effacer tout l'historique de conversation, en conservant CLAUDE.md et la mémoire | Passer à une nouvelle tâche, ou lorsque le contexte est gravement pollué |
/rewind(ou appuyez deux fois sur Esc) |
Ouvrir le menu des points de contrôle pour choisir de restaurer la conversation/le code/les deux, ou reprendre à partir d'un certain résumé | Claude a dévié, il faut revenir en arrière et réessayer |
/memory |
Afficher et modifier le contenu de CLAUDE.md et de la mémoire automatique | Vérifier si la mémoire est exacte, supprimer les entrées obsolètes |
/btw |
Question rapide, la réponse n'entre pas dans l'historique de conversation | Rechercher de petits détails sans polluer le contexte |
/init |
Analyser le projet et générer ou améliorer CLAUDE.md | Première utilisation dans un nouveau projet, ou lorsque le projet subit des changements majeurs |
#(raccourci) |
Ajouter rapidement une instruction persistante à CLAUDE.md | Enregistrer des conventions ou des accords à tout moment |
claude --continue |
Continuer la session la plus récente | Continuer à travailler après avoir rouvert le terminal |
claude --resume |
Choisir une session dans la liste de l'historique pour continuer | Reprendre une tâche spécifique d'il y a quelques jours |
Problèmes courants et solutions
Problème 1 : Claude ne suit pas les règles dans CLAUDE.md
- Vérifiez si CLAUDE.md est trop volumineux (le taux de conformité chute lorsqu'il dépasse 200 lignes)
- Remplacez les formulations vagues par des instructions précises : ne dites pas « écrivez du code propre », dites « utilisez une indentation de 2 espaces »
- use
/memoryVérifiez les entrées de mémoire automatique en conflit - Envisagez d'utiliser
.claude/rules/Répartissez les règles par chemin de fichier pour réduire la quantité chargée à chaque fois
Problème 2 : Claude commence à se contredire et « oublie » les décisions précédentes
- Il s'agit d'un symptôme typique de dégradation du contexte. Ne continuez pas à corriger dans la même session
- Exécutez
/compact 保留关键决策, ou directement/clearpuis redémarrez avec un résumé - À utiliser pour les conclusions importantes
#Écrivez dans CLAUDE.md via un raccourci pour garantir qu'il reste efficace lors de la prochaine session
Problème 3 : Informations clés perdues après /compact
- Passez des instructions précises lors du compactage :
/compact 保留认证流程的架构决策和已确认的 API 格式 - Écrivez les conclusions les plus importantes dans CLAUDE.md avant de compacter
- Les tentatives de débogage infructueuses ne méritent pas d'être conservées ; vous pouvez compacter plus agressivement ou utiliser /clear
Problème 4 : Comment reprendre le travail de la dernière fois après avoir fermé le terminal
- Utiliser
claude --continueContinuer la session la plus récente - Utiliser
claude --resumeSélectionnez une session spécifique dans la liste de l'historique - use
/renameDonnez un nom descriptif aux sessions importantes (par ex. « oauth-migration ») pour les retrouver plus facilement plus tard
Problème 5 : Une tâche volumineuse génère beaucoup de sorties d'outils. Comment éviter le débordement du contexte
- Utilisez des sous-agents pour la délégation : la conversation principale ne reçoit que le résumé, tandis que les sorties intermédiaires restent dans le contexte indépendant du sous-agent
- Par exemple :
Use sub-agents to analyze all log files, identify performance bottlenecks, and only report the conclusions to me.