Comment fonctionne Claude Code, vraiment

En début de session, tu lui as donné une consigne précise. Le format des dates, le dossier auquel il ne touche pas, la bibliothèque que vous n’utilisez plus. Pendant une heure, il l’a respectée. Puis, sans prévenir, il ne la respecte plus — et tu ne t’en aperçois pas en relisant son code, tu t’en aperçois parce que quelque chose s’affiche de travers à l’écran.

Tu remontes le fil de la conversation et tu ne trouves aucun moment où ça a basculé.

C’est là qu’on se dit que Claude Code est capricieux. Il ne l’est pas : il travaille sur autre chose que ce que tu crois, et cette leçon sert à voir quoi.

Ce qui se passe vraiment

Trois pièces, et elles s’emboîtent : une boucle, des outils, et un plan de travail qui se remplit.

La première pièce : une boucle, pas une commande

Quand tu lui donnes une tâche, il passe par trois temps : rassembler le contexte, agir, vérifier le résultat. Ces trois temps ne se suivent pas sagement — ils se mélangent et se répètent jusqu’à la fin de la tâche.

L’image à garder pour tout le parcours : le cuisinier goûte son plat pendant qu’il le fait. Il goûte, il rectifie, il regoûte, et il ne sert pas sans avoir goûté. Ce n’est pas une recette qu’on déroule du début à la fin, c’est un aller-retour permanent entre faire et constater.

La boucle s’adapte à ce que tu demandes. Une question sur ton code peut ne demander que du rassemblement, sans rien modifier. Une correction de bug repasse plusieurs fois par les trois temps. Une réorganisation demande énormément de vérification. Ce n’est pas une séquence fixe, et c’est pour ça qu’aucun schéma ne te dira à l’avance combien d’étapes il va falloir.

Sur « répare les tests qui échouent », l’enchaînement ressemble à ceci :

lancer les tests pour voir ce qui casse ;
lire la sortie d’erreur ;
chercher les fichiers sources concernés ;
les lire ;
les modifier ;
relancer les tests.

Chaque usage d’outil renvoie une information qui détermine l’étape suivante. Des dizaines d’actions s’enchaînent comme ça, avec des corrections de trajectoire en route — et c’est la première explication des moments où il « part ailleurs » : il a lu quelque chose, à l’étape trois, qui a changé son idée de la tâche.

Tu es dans la boucle, toi aussi, et les deux gestes qui te le permettent ne font pas la même chose :

Échap l’arrête tout de suite : l’outil en cours est annulé et il attend ta consigne. Une réserve, et elle tombe souvent : si une fenêtre est ouverte, typiquement une demande d’autorisation, Échap ferme cette fenêtre au lieu de l’interrompre. Il faut alors appuyer une seconde fois.
Taper une correction et faire Entrée l’envoie sans arrêter l’outil en cours : elle est lue dès l’action terminée, avant qu’il décide de la suivante.

Dans les deux cas, le travail déjà fait est conservé. Le premier geste sert quand il part franchement dans le mur ; le second quand la direction est bonne mais qu’il manque une contrainte.

La deuxième pièce : cinq familles d’outils

Sans outils, un modèle ne peut que répondre du texte ; avec eux, il agit. Les outils intégrés se rangent en cinq familles, chacune correspondant à un genre de pouvoir différent :

Famille	Ce qu’elle permet
Fichiers	lire, modifier, créer, renommer, réorganiser
Recherche	trouver un fichier par motif, chercher dans le contenu, explorer un dépôt
Exécution	lancer des commandes, démarrer un serveur, lancer les tests, se servir de git
Web	chercher sur le web, aller lire une documentation, retrouver un message d’erreur
Intelligence de code	voir les erreurs de type après modification, aller à une définition, retrouver tous les endroits qui utilisent une même fonction

Ce sont les capacités principales, pas la liste complète : il en existe d’autres, pour déléguer une tâche ou pour te poser une question.

La dernière ligne n’est pas fournie d’office, et elle se paie en deux fois. Il faut installer un plugin (l’emballage qui permet de réutiliser tout ça ailleurs) et, séparément, le petit programme qui sait analyser ton langage : le plugin ne l’installe pas pour toi. Si tu ne poses que la moitié, rien ne te le dira dans le fil ; le message Executable not found in $PATH s’affiche dans l’onglet Errors de /plugin, et c’est là qu’il faut aller le lire. Sans cette famille d’outils, quand il cherche où une fonction est définie, il se rabat sur ses outils de recherche intégrés et lit ce qu’ils remontent — ce qui a un coût dont on parle plus bas. C’est l’un des moments recensés par la leçon 5, qui associe à chaque situation courante l’outil qui la règle.

Une distinction utile pendant qu’on y est : ce qui précède n’a rien à voir avec un assistant de complétion, celui qui propose la fin de ta ligne dans ton éditeur et ne voit que le fichier ouvert. Ici, une même modification peut être coordonnée sur plusieurs fichiers à la fois. Ce n’est pas une question d’être ou non dans l’éditeur, où Claude Code existe aussi. C’est une question de lire et d’exécuter.

Ce à quoi il a accès quand tu le lances dans un dossier

Tes fichiers : ceux du dossier et de ses sous-dossiers, plus d’autres avec ton autorisation.
Ton terminal : tout ce que tu pourrais y taper toi-même.
Ton état git : la branche courante, les modifications non enregistrées, l’historique récent.
Ton fichier de règles, le CLAUDE.md (le fichier de règles du projet, relu à chaque session).
La mémoire automatique : ce qu’il note tout seul au fil du travail — tes corrections, tes préférences, les régularités qu’il remarque dans le projet.
Ce que tu as branché toi-même, s’il y a lieu : services extérieurs, procédures réutilisables, ouvriers spécialisés. Le vocabulaire vient en leçon 4, les moments de s’en servir en leçon 5.

La troisième pièce : le plan de travail

Tout ce qui précède finit au même endroit : la fenêtre de contexte. C’est un plan de travail. Il y pose l’historique de votre conversation, le contenu des fichiers qu’il a lus, les sorties des commandes qu’il a lancées, ton fichier de règles, sa mémoire automatique, les skills chargés (un skill est une fiche réutilisable : du savoir ou une procédure), et les instructions système.

C’est le mot qu’on emploiera partout dans le parcours : le plan de travail, c’est la fenêtre de contexte.

À retenir — ce qui n’est pas sur le plan de travail n’existe pas. Et il y a deux façons de ne pas y être, qui ne se soignent pas pareil : ça n’y a jamais été (il ne l’a pas lu, tu ne l’as pas dit), ou ça y était et ça n’y est plus (le plan a débordé, on a fait de la place). Le premier cas se règle en le disant. Le second est le sujet de cette leçon.

Le plan est déjà bien encombré avant que tu tapes ton premier mot. Instructions système, mémoire automatique, informations d’environnement, descriptions des procédures disponibles, règles globales, règles du projet : tout ça est chargé à l’ouverture. Ton message, à côté, est minuscule. Quand tu écris trois lignes et qu’il te répond en tenant compte d’une convention que tu n’as pas citée, ce n’est pas de la divination — c’était déjà sur le plan.

Deux précisions à ne pas perdre, parce qu’elles décrivent des filets moins solides qu’ils n’en ont l’air :

La mémoire automatique est plafonnée au chargement : ses 200 premières lignes, ou ses 25 kilo-octets, au premier atteint. Ce qui est en dessous n’entre pas.
La taille du plan dépend du modèle, et elle vient de changer d’ordre de grandeur. L’unité est le token. C’est la mesure de la place occupée, un morceau de mot plutôt qu’un mot. La valeur standard a longtemps été de 200 000 tokens ; sur les modèles récents, c’est un million, et il arrive sans que tu le demandes : rien à sélectionner, aucun crédit à payer. Deux cas te ramènent à 200 000 sans le dire non plus : un modèle d’avant cette génération, ou un modèle dont le million se paie encore en crédits d’usage selon ton offre. Sur l’offre Pro, c’est le cas d’Opus, alors que le modèle proposé par défaut, lui, est déjà à un million. Tape /model pour savoir sur lequel tu travailles, et /context pour voir la place réellement disponible dans la session en cours. Le premier des deux n’est pas qu’un constat : depuis la version 2.1.153, choisir un modèle dans son sélecteur écrit ce choix dans tes réglages personnels et en fait le défaut de tes nouvelles sessions — s sur la ligne choisie ne change que la session courante. Le chiffre que tu retiens aujourd’hui sera faux au prochain modèle : c’est la commande qu’il faut retenir, pas le nombre.

Et un plan plus grand n’est pas un plan neutre : la documentation officielle prévient que chaque chose ajoutée consomme du contexte, mais qu’elle peut aussi « ajouter du bruit qui rend Claude moins efficace ». Les skills se déclenchent moins bien, tes conventions se perdent. Et ça ne commence pas à partir d’un seuil, ça commence à la première chose posée. Le seuil auquel la session se résume d’elle-même dépend d’ailleurs de ta configuration, et il n’est pas toujours la limite annoncée : sur Sonnet 5, elle se résume vers 967 000 tokens sans attendre d’être pleine — ailleurs, c’est bien la limite du modèle, et plusieurs configurations te ramènent à 200 000 sans le dire. Le million est donc de la place, pas une permission de tout charger.

Quatre cases de visibilité, et c’est le nœud

Tu ne vois pas ce qu’il voit. Chaque chose qui entre sur le plan de travail se range dans l’une de ces quatre cases :

Ce que ton écran en montre	Exemples
Rien — mais tu peux le demander	tout ce qui est chargé, catégorie par catégorie (`/context`), y compris ce que coûtent en place tes services branchés, dont il signale les plus lourds ; les emplacements de tes fichiers de mémoire (`/memory` les ouvre) ; l’état de tes services branchés et de leur connexion (`/mcp`)
Rien du tout	les instructions système, les déclenchements automatiques attachés à un événement — les hooks
Une ligne	« Read auth.ts » : le contenu du fichier ne s’affiche pas ; une règle chargée s’annonce sans son contenu ; une suite de tests affiche son verdict, pas sa sortie complète
Le contenu	ton message, l’analyse qu’il rédige, les modifications qu’il propose

Relis la troisième ligne, c’est celle qui coûte le plus cher. Le poste de dépense principal, ce sont les fichiers lus. Une ligne à l’écran peut représenter quelques centaines de tokens comme quelques milliers, posés sur le plan de travail — et tu n’as aucun moyen, en regardant ton terminal, de deviner lesquels sont gros.

Quand le plan déborde

Il ne s’arrête pas : il fait de la place. Quand la fenêtre approche de sa limite, une compaction se déclenche automatiquement. Les vieilles sorties d’outils sont vidées d’abord, puis la conversation est résumée. Le résumé garde tes demandes et les extraits de code importants ; les instructions détaillées que tu as données tôt dans la conversation peuvent être perdues.

Ça se voit, et c’est le seul repère dont tu disposes : un message « Conversation compacted » apparaît dans le fil au moment où ça arrive. Le résumé, lui, se fabrique sans rien afficher. Un avertissement est également montré quand la conversation approche du seuil.

Et voici le mécanisme complet, celui qui explique la scène du début : ce qui survit ne dépend pas de l’importance de la chose, ni de son âge, mais de la façon dont elle est arrivée là. Ce qui a une copie sur le disque est remis en place ; ce qui n’existait que dans la conversation est résumé en trois mots.

Un mot de vocabulaire avant le tableau, parce qu’il en faut deux lignes : un fichier de règles peut vivre ailleurs qu’à la racine du projet, dans un sous-dossier, et une règle peut être attachée à certains chemins, c’est-à-dire ne se charger que lorsqu’il ouvre un fichier correspondant. Si tu n’as rien fait de tel, tu n’es concerné que par la première ligne du tableau. La leçon 6 y revient.

Comment c’est chargé	Après compaction
Instructions système	inchangées — elles ne sont pas dans l’historique
CLAUDE.md à la racine du projet et règles sans portée	rechargés depuis le disque
Mémoire automatique	rechargée depuis le disque (dans la limite vue plus haut)
Règles attachées à certains chemins	perdues jusqu’à ce qu’un fichier correspondant soit relu
CLAUDE.md placé dans un sous-dossier	perdu jusqu’à ce qu’un fichier de ce sous-dossier soit relu
Corps des skills utilisés	réinjectés, mais plafonnés à 5 000 tokens par skill et 25 000 au total, les plus anciens jetés en premier ; la troncature garde le début du fichier
Liste des skills disponibles	non réinjectée — seuls ceux déjà utilisés survivent
Hooks	sans objet : ce sont des programmes, pas du contexte

La dernière ligne mérite qu’on s’y arrête, parce qu’elle décrit un dispositif qui meurt en silence : après une compaction, une procédure que tu n’avais pas encore utilisée dans la session n’est plus annoncée, donc il ne peut plus la déclencher de lui-même. Rien ne casse, rien ne prévient — elle cesse simplement d’exister pour lui. C’est le sujet entier de la leçon 13.

Piège — « c’est écrit dans mon fichier de règles, donc il le sait » n’est vrai que du fichier placé à la racine du projet. Une règle attachée à des chemins, ou un fichier de règles posé dans un sous-dossier, disparaît à la première compaction et ne revient qu’au prochain fichier lu qui la déclenche.

Et pour la scène du début, celle de la consigne donnée à l’oral : elle n’a jamais eu de copie sur le disque. Une heure de conversation plus tard, le résumé l’a réduite à rien.

Ce qu’on fait

Rien à installer. Quatre gestes, tous disponibles maintenant.

Regarder ce qui occupe la place. Avant de conclure qu’il est bête :

/context

Il affiche ce qui consomme la place, par catégorie : instructions système, outils, fichiers de mémoire, skills, conversation. C’est la commande qui répond à « qu’est-ce qui est réellement chargé ». Une réserve, faute de quoi tu vas être déçu : il montre l’état présent, pas celui d’il y a vingt minutes — lancé après une compaction, il te montrera un plan bien rangé qui n’explique rien.

C’est cette réserve qui appelle le geste suivant : le remplissage peut aussi rester sous tes yeux en permanence. La ligne d’état, en bas de ton terminal, peut afficher le pourcentage occupé en continu ; /statusline la configure, et lui demander simplement d’y mettre le pourcentage de contexte suffit. Ce n’est pas un raffinement : un chiffre qu’on voit monter prévient, là où une commande qu’on pense à lancer ne sert qu’après. Pour le détail d’une catégorie, il existe ensuite des commandes dédiées : /memory ouvre tes fichiers de mémoire, /mcp montre tes services branchés et l’état de leur connexion, /permissions affiche les autorisations en vigueur. Attention à ne pas demander à /mcp ce qu’il ne fait pas : il gère les connexions, il ne chiffre rien. Ce que ces services te coûtent en place est dans /context, qui signale les outils les plus lourds ; et ce qu’ils ont consommé après coup est dans /usage, ventilé service par service.

Le faire lire moins. Deux leviers. Être précis dans ta demande, pour qu’il ouvre trois fichiers au lieu de trente. Et déléguer à un subagent (un ouvrier isolé qui travaille à part et ne rend qu’un résumé) quand la tâche va lire beaucoup : il lit dans sa fenêtre à lui, pas sur ton plan. Le geste exact est en leçon 5 ; retiens pour l’instant que le levier existe.

Reprendre la main sans tout perdre. Échap pour l’arrêter net — deux fois si une fenêtre est ouverte. Une phrase tapée puis Entrée pour corriger la trajectoire sans interrompre l’action en cours. Annuler, ou infléchir : choisis.

Décider du moment du ménage plutôt que le subir. Deux commandes, à taper telles quelles :

/compact garde le travail sur l'authentification

/clear

La première résume tout de suite, en gardant ce que tu lui dis de garder — la consigne se met sur la même ligne. La seconde vide le plan, et c’est ce qu’on fait en changeant complètement de sujet. Enchaîner trois sujets sans rien vider, c’est empiler trois chantiers sur le même plan de travail, puis s’étonner qu’il attrape le mauvais outil.

Il existe une troisième commande, /autocompact, qui règle à quel niveau de remplissage le ménage se déclenche. Elle est mise à part exprès : elle demande une version récente sortie en août 2026, et surtout elle enregistre un réglage durable, valable pour tes prochaines sessions et tous tes projets. Baisser le seuil pour sauver la session du jour, c’est se condamner à compacter plus tôt partout — l’inverse de ce qu’on cherche. /autocompact auto revient au réglage d’origine.

Sortir de la conversation ce qui doit durer

Une consigne donnée à l’oral tient le temps d’une session, et pas toujours jusqu’au bout. Une consigne écrite dans un fichier nommé CLAUDE.md, à la racine de ton projet, est relue depuis le disque à chaque session et après chaque compaction. Si le fichier n’existe pas, la commande /init te le crée.

Mais y être ne garantit pas d’être suivi, et c’est la deuxième moitié de l’histoire. Un fichier de règles n’est pas un réglage qu’on applique : c’est du contexte, posé sur le plan de travail comme le reste. La documentation officielle le dit sans détour — il n’y a « aucune garantie de conformité stricte, surtout pour les instructions vagues ou conflictuelles ». Deux conséquences pratiques, mesurables :

La longueur dégrade le suivi. L’objectif affiché est de rester sous 200 lignes ; au-delà, les fichiers « consomment plus de contexte et réduisent l’adhérence ». Le fichier n’est pas coupé : il est chargé en entier quelle que soit sa longueur. Mais plus il est long, moins il est suivi.
Deux règles qui se contredisent font choisir au hasard. Relire ses règles pour retirer l’obsolète fait partie du travail.

Autrement dit : la racine achète la persistance, elle se paie en place et en dilution. Tout y verser parce que « c’est ce qui survit » finit par produire exactement le symptôme du début de cette leçon. C’est d’ailleurs pour ça que l’outil de diagnostic intégré, /doctor, pousse dans l’autre sens : il repère dans un fichier de règles versionné ce que Claude pourrait déduire du code tout seul, et propose de faire passer le reste vers des contenus qui se chargent à la demande. Cette vérification-là demande la version 2.1.206 ou plus récente. Et il propose, au sens strict : il rapporte d’abord et ne change rien sans que tu confirmes. La leçon 6 traite ce partage.

Deux gestes pour finir, qui répondent à « pourquoi ma règle ne s’applique pas » :

/context te dit si elle est chargée, tout simplement. Il liste les fichiers de mémoire présents dans la fenêtre. Si le tien n’y est pas, il n’existe pas pour lui — et tu viens de gagner vingt minutes de suppositions. Attention à ne pas confondre avec /memory, qui liste des emplacements de fichiers, y compris de fichiers que tu n’as pas encore créés : il sert à ouvrir et modifier, pas à savoir ce qui est chargé.
Si elle est bien chargée et qu’il ne la suit pas, c’est qu’une règle de conduite ne s’applique pas toute seule. Ce qui s’applique vraiment, indépendamment de ce que le modèle décide, ce sont les autorisations que tu as posées, les réglages imposés par ton organisation, le bac à sable, et les hooks. Un hook est le bon outil quand une chose doit arriver à un moment fixe et sans exception — avant chaque envoi de code, après chaque modification. Leçon 5 pour le moment de s’en servir, leçon 8 pour les autorisations.

Ce que ça ne fait pas

Goûter ne garantit pas que ce soit bon. La boucle contient sa propre vérification, et c’est une bonne nouvelle — mais le cuisinier s’habitue à son assaisonnement. Un plat peut être goûté et raté quand même. La vérification interne ne remplace pas un jugement extérieur : c’est la question que pose la leçon 10, « comment tu sais que ça marche, si tu ne lis pas le code ».

Comprendre la boucle ne te dit pas ce qu’il a lu. Tu vois passer des lignes, pas des contenus. Tu ne sauras pas, en regardant ton écran, s’il a ouvert le bon fichier de configuration ou celui d’à côté. Ce que tu peux faire : réduire l’incertitude en étant précis, et regarder quels fichiers ont été touchés quand c’est fini.

Une session ne reprend pas là où la précédente s’est arrêtée — mais rien n’est perdu. Chaque nouvelle session démarre avec une fenêtre vierge. Ce qui traverse tout seul, c’est le fichier de règles à la racine et la mémoire automatique. Le reste est à redonner, ou à rouvrir : une session se reprend, et se duplique. C’est la leçon 7.

Changer de branche ne change pas la conversation. Il verra bien les fichiers de la nouvelle branche, mais il se souvient de tout ce qui a été dit avant le changement. Ce qu’il croit du code et ce que le code est peuvent alors diverger sans que rien ne te prévienne.

La compaction automatique n’est pas infaillible. Si un seul fichier ou une seule sortie de commande est si gros que le contexte se remplit à nouveau juste après chaque résumé, elle s’arrête au bout de quelques tentatives et affiche une erreur, plutôt que de tourner en rond.

Ce n’est pas un réglage de performance. Garder le plan de travail court change ce qu’il a dessus, donc ce qu’il arrive à suivre. Mais ça ne produit pas la même réponse plus vite, et personne ne peut chiffrer ce que ça t’apporte : aucune mesure publiée ne porte sur une session de travail comme la tienne. Ce que ça te donne, c’est de savoir ce qu’il avait sous les yeux au moment où il a décidé — c’est-à-dire de transformer « il fait n’importe quoi » en une phrase qui se vérifie.

Où c’est écrit

Le fond de cette leçon vient de deux pages officielles, et il vaut mieux les avoir en signet que de nous croire sur parole :

Comment fonctionne Claude Code — la boucle, les outils, les sessions ;
Explorer la fenêtre de contexte — le tableau de ce qui survit, et une simulation où l’on voit le plan de travail se remplir.

Ces liens pointent vers les pages anglaises, et c’est délibéré. La documentation existe en français : remplace /en/ par /fr/ dans l’adresse. Mais la traduction est en retard sur l’originale, et surtout elle traduit certains termes que ce parcours garde en anglais : tu y liras « compétences » pour skills et « jetons » pour tokens, alors que le glossaire, lui, garde les mots anglais. Deux pages officielles, deux vocabulaires. Lis-la si tu préfères, en sachant ça.

Ce que cette leçon ajoute, c’est l’ordre : un symptôme, puis le mécanisme, puis le geste.

Le point de bascule

Tu as compris le jour où, devant une réponse absurde, ta première question n’est plus « pourquoi il est bête ? » mais « qu’est-ce qu’il avait sur son plan de travail à ce moment-là ? ».

Vérifier que c’est passé

En début de session, tu lui as dit de ne jamais toucher au dossier des migrations. Deux heures plus tard, il y touche. Que s'est-il passé, et qu'est-ce qui l'aurait évité ?

Une compaction est passée. Ta consigne n’existait que dans la conversation : elle n’avait aucune copie sur le disque, donc le résumé l’a réduite à rien. L’indice est dans le fil, sous la forme d’un message « Conversation compacted ». Ce qui l’aurait évité : la même phrase écrite dans le fichier CLAUDE.md à la racine du projet, qui est relu depuis le disque après chaque compaction et à chaque nouvelle session.

Il est en train de lire une série de fichiers et tu vois qu'il va corriger le mauvais module. Tu appuies sur Échap ou tu tapes ta correction ?

Ça dépend de ce que tu veux. Échap l’arrête immédiatement : l’outil en cours est annulé et il attend — mais si une fenêtre de demande d’autorisation est ouverte, la première pression la ferme et il faut appuyer une seconde fois. Taper une correction puis Entrée l’envoie sans interrompre l’action en cours ; il la lira dès qu’elle sera terminée, avant de décider de la suivante. Pour une erreur de cible franche, arrête. Pour ajouter une contrainte alors que la direction est bonne, écris.

Il vient de te répondre à côté de la plaque. Tu lances `/context` pour comprendre — bonne ou mauvaise idée ?

À moitié bonne, et c’est la moitié qui manque qui compte. /context montre l’état présent du plan de travail : s’il vient d’y avoir une compaction, tu verras un plan bien rangé qui n’explique rien de ce qui s’est passé. Le bon réflexe est de remonter le fil pour chercher le message « Conversation compacted », qui date l’incident. /context reste utile pour la suite : savoir ce qui occupe la place t’évite la compaction suivante.