Aller au contenu principal

Module 2 — La boucle agentique, les outils intégrés et la fenêtre de contexte

Le module 1 a mis Claude Code entre vos mains ; ce module ouvre le capot. Comprendre la boucle agentique et ce que fait chaque outil intégré, c'est comprendre pourquoi une session peut coûter un dixième de sa voisine à travail équivalent. Suivent les commandes qui pilotent le contexte — /context, /compact, /clear, /btw, /usage — puis, sur Kiosque, une cartographie et une compaction ciblée.

La boucle : contexte, action, vérification​

Quand vous soumettez une tâche, Claude n'écrit pas de code immédiatement. Il déroule une boucle en trois phases qui se mélangent : collecter du contexte en lisant des fichiers et en cherchant, agir en appelant des outils qui éditent ou exécutent, vérifier en lançant des tests, un lint, une commande. Chaque appel d'outil renvoie un résultat que le modèle observe et qui informe la décision suivante. Ce n'est pas un pipeline : Claude peut lire, éditer, relire, corriger, relancer les tests, en une dizaine d'itérations sur un même tour.

Deux composants font tourner la boucle : le modèle qui raisonne (choisi via /model, effort réglé via /effort) et les outils qui agissent. Le reste — Claude Code — est un agentic harness : il fournit les outils, gère le contexte, exécute et remonte les résultats. Vous restez dans la boucle : Esc interrompt l'appel courant, taper une correction sans arrêter modifie la trajectoire au tour suivant sans perdre le travail en cours.

Catalogue des outils intégrés​

Les outils intégrés se répartissent en cinq familles fonctionnelles. Les noms cités ci-dessous sont les identifiants exacts utilisés dans les règles de permission (Outil(...)), les listes tools: des sous-agents et les matchers de hooks.

  • Fichiers : Read lit, Edit fait un remplacement ciblé, Write crée ou écrase, NotebookEdit modifie une cellule Jupyter. Read ne demande pas d'autorisation dans le répertoire de travail ; Edit et Write la demandent en mode manuel. Une règle Edit(...) accorde implicitement le Read correspondant.
  • Recherche : Grep (motif dans les contenus), Glob (patron de nom), LSP (définitions, références, diagnostics de type — via un plugin de code intelligence).
  • Exécution : Bash (shell Unix), PowerShell (Windows, quand activé), Monitor (processus en arrière-plan qui reflue chaque ligne de sortie à Claude).
  • Web : WebFetch (URL), WebSearch (recherche).
  • Orchestration : Agent (sous-agent avec sa propre fenêtre), Skill (charge une skill), AskUserQuestion (question à choix multiples), SendMessage et ListAgents (messagerie inter-sessions).

À cela s'ajoutent des outils utilitaires : EnterPlanMode / ExitPlanMode (mode plan, module 8), EnterWorktree / ExitWorktree (git worktrees), TaskCreate / TaskList / TaskUpdate (liste de tâches), CronCreate / CronList / CronDelete (prompts planifiés via /loop), RemoteTrigger (routines cloud via /schedule), ToolSearch (chargement à la demande des outils MCP différés), Workflow (workflow dynamique), PushNotification (notification desktop ou mobile). TodoWrite est désactivé par défaut au profit de la famille Task*.

Les outils qui demandent une permission par défaut sont ceux qui écrivent ou exécutent : Bash, Edit, Write, NotebookEdit, PowerShell, Monitor, WebFetch, WebSearch, EnterWorktree, Skill, Workflow, Artifact. Bash fait exception pour un ensemble prédéfini de commandes en lecture seule (ls, pwd, git status) qui ne posent pas de question ; Bash(git log *) ajoute ce qu'on veut à la liste blanche.

Chaque outil connaît son argument

Une règle de permission suit toujours le format Outil(spécifieur). Pour Bash, le spécifieur est un motif de commande (Bash(npm run *)) ; pour Read/Edit/Write, un chemin (Edit(app/**)) ; pour WebFetch, un domaine (WebFetch(domain:docs.example.com)) ; pour Skill, un nom (Skill(deploy *)). Le module 7 déroule toutes les combinaisons.

La fenêtre de contexte : ce qui la remplit​

La fenêtre de contexte est tout ce que Claude voit à chaque tour. Elle contient, dans l'ordre :

  1. Le prompt système : instructions de base, définitions d'outils, output-styles, texte de --append-system-prompt.
  2. Le contexte projet : CLAUDE.md fusionnés du haut de l'arborescence jusqu'à votre dossier, règles sans paths:, mémoire automatique (les 200 premières lignes ou 25 Ko de MEMORY.md), descriptions des skills.
  3. Les définitions d'outils MCP — seulement les noms et instructions serveur : les schémas complets sont différés par la tool search (module 11).
  4. La conversation : vos messages, réponses de Claude, résultats d'outils.

Les trois premières couches changent rarement d'un tour à l'autre : c'est là que le cache de prompt fait effet. La quatrième s'étend et se recompacte au besoin.

/context affiche une grille colorée de l'usage, avec suggestions d'optimisation, fichiers de mémoire chargés, coût des serveurs MCP, dépassement éventuel. Passez all pour développer chaque item. Lisez /context avant un compact : c'est le seul moyen fiable de savoir qui mange les jetons.

/compact, /clear, /btw : libérer sans repartir de zéro​

Trois commandes gèrent l'espace :

  • /compact [instructions] résume la conversation jusque-là et remplace l'historique. Sans argument, Claude choisit ce qu'il garde ; avec une consigne — /compact concentre-toi sur le bug de paiement, jette tout le reste — il cible. La commande produit une requête séparée avec le même prompt système, tous vos outils, l'historique, et une instruction de résumé.
  • /clear [nom] ouvre une conversation vide. La mémoire projet et le CLAUDE.md restent chargés. Un nom optionnel étiquette la conversation précédente dans /resume. Alias : /reset, /new.
  • /btw [question] pose une question annexe dont la réponse n'entre pas dans l'historique. Idéal pour « au fait, qu'est-ce qu'un lock optimiste ? » sans polluer la conversation. Sans argument, /btw réaffiche votre dernière question annexe (v2.1.212+ ; auparavant une question était obligatoire).

Autres commandes du même terrain : /autocompact <auto|tokens> règle quand l'auto-compaction se déclenche (/autocompact 500k, /autocompact auto) — v2.1.221+ ; /rewind (alias /checkpoint, /undo) rembobine ou résume depuis un message précis, détaillé au module 8 ; /recap génère un résumé d'une ligne sans toucher au contexte.

Ce qui survit à /compact​

Quand /compact s'exécute, Claude Code résume la conversation mais relit certaines choses depuis le disque :

  • Le prompt système et l'output style restent intacts (hors historique).
  • Le CLAUDE.md du dépôt, les règles sans paths:, la mémoire automatique et le plan de mode plan sont ré-injectés depuis le disque.
  • Les règles avec frontmatter paths: et les CLAUDE.md de sous-dossiers rechargent quand Claude relit un fichier qui les déclenche.
  • Jusqu'à cinq fichiers récemment modifiés sont relus ; un fichier de plus de 5 000 jetons revient en simple référence de chemin.
  • Les corps de skills invoquées reviennent, avec un plafond de 5 000 jetons par skill et 25 000 jetons au total.
  • Les hooks SessionStart qui matchent la source compact re-tournent, et leur sortie est ajoutée.

Corollaire : une consigne donnée seulement dans la conversation disparaît. Si vous voulez qu'elle persiste, elle appartient au CLAUDE.md — module 3.

Le cache de prompt : pourquoi certaines actions coûtent cher​

L'API réutilise la partie initiale — le préfixe — de chaque requête si elle est identique à la précédente. Claude Code range délibérément le prompt système au début, puis le contexte projet, puis la conversation. Un ajout en fin de conversation ne casse rien ; un changement dans le prompt système invalide tout ce qui suit. C'est pourquoi certaines commandes déclenchent un tour lent, plus cher, une seule fois, puis les tours suivants retrouvent leur rythme.

Actions qui invalident le cache :

  • Changer de modèle (/model) — chaque modèle a son cache ; confirmation demandée tant que le cache est chaud.
  • Changer de niveau d'effort sur la plupart des modèles (exception Fable 5.1 avec clé API ou abonnement).
  • Activer le mode rapide (/fast on) : un en-tête change le cache key.
  • Connecter ou déconnecter un serveur MCP dont les outils sont chargés dans le préfixe (rare depuis la tool search).
  • Refuser un outil entier via une deny-rule au nom nu (Bash, WebFetch) : la définition sort du prompt système.
  • Changer d'output style avec /config outputStyle=....
  • Compacter la conversation avec /compact.
  • Accumuler tant d'images que le CLI en retire les plus vieilles.
  • Mettre Claude Code à jour : la première requête après redémarrage rebâtit le cache.

Actions qui préservent le cache : éditer des fichiers du dépôt, éditer le CLAUDE.md en cours de session (relu seulement au démarrage ou après /clear / /compact), changer de mode de permission, invoquer une skill ou une commande, lancer /recap ou /rewind.

Choisissez au démarrage

Fixez le modèle et le niveau d'effort avant votre première question. Chaque bascule mid-session vous coûte un tour de préfixe complet. La règle simple : sonnet + high au démarrage, on ne bascule que pour un plan complexe.

Déléguer à un sous-agent pour épargner le contexte​

Quand une recherche va lire vingt fichiers, gonfler la fenêtre principale pour ne garder qu'un résumé est un mauvais calcul. Un sous-agent (module 10) tourne dans sa propre fenêtre de contexte : il lit, cherche, corrèle et ne rend que le résumé. Deux commandes déclenchent ce report : /subtask <tâche> lance un forked subagent qui hérite de la conversation et dont le résultat revient dans le fil courant ; /fork [prompt] copie la conversation dans une nouvelle session d'arrière-plan et vous garde ici (à suivre via claude agents ou /tasks).

Lire le coût : /usage​

/usage (alias /cost, /stats) donne pour la session : jetons d'entrée, de sortie, cache read et cache write par modèle, prix estimé, durée d'appels API. Une ligne Prompt cache (main) indique le pourcentage de jetons d'entrée servis depuis le cache, le nombre de misses, la cause probable du dernier (par exemple likely cause: tool definitions changed), et si le cache est chaud ou froid (v2.1.251+, libellés v2.1.260+).

Sur un abonnement, /usage ajoute la répartition récente par skill, sous-agent, plugin, serveur MCP (24 h ou 7 jours, bascule d/w), avec des drapeaux dès qu'une catégorie dépasse 10 %. /usage-credits ouvre l'écran des crédits ou envoie une demande à l'admin.

Fil rouge Kiosque : cartographier et compacter​

Dans le dépôt Kiosque, on lance une session en sonnet avec effort high et on demande :

Explique-moi le flux d'une commande de bout en bout : depuis la requête
HTTP `POST /commandes` jusqu'à la confirmation de paiement. Cite les
fichiers de app/ concernés et les tables SQLAlchemy touchées.

Claude appelle Read sur app/commandes.py, Grep sur les modèles, ouvre app/paiements.py, Read sur models.py, Grep sur les migrations. Chaque appel est visible dans le transcript (Ctrl+O). /context révèle que la conversation a atteint 60 000 jetons, dont la moitié en fichiers lus.

Avant d'attaquer la refonte de paiements.py, on compacte avec une consigne :

/compact garde uniquement le résumé du flux de commande et les modèles
de données ; jette tout le reste, notamment les extraits de code lus.

Le résumé revient à 8 000 jetons utiles. Le cache se reconstruit au tour suivant, puis /usage confirme que la ligne Prompt cache (main) est cachée à 90 %.

Erreur fréquente : /clear au lieu de /compact​

/clear jette toute la conversation, y compris ce que Claude vient de comprendre du dépôt : on repart sur des lectures identiques au tour suivant. Réservez /clear aux changements de tâche indépendants ; entre deux étapes d'une même tâche, /compact avec une consigne garde ce qui compte.

En résumé​

  • La boucle agentique enchaîne collecte, action et vérification ; chaque outil observe le résultat et informe l'étape suivante.
  • Les outils intégrés se rangent en cinq familles ; les identifiants exacts (Read, Bash, Edit…) sont ceux des règles de permission et des matchers de hooks.
  • La fenêtre de contexte empile prompt système, contexte projet, définitions d'outils, conversation ; /context la visualise.
  • /compact avec une consigne vaut mieux que /clear au milieu d'une tâche : on garde ce qui compte.
  • Le cache de prompt paie le préfixe une fois ; changer de modèle, d'effort ou d'output style oblige à tout recalculer.
  • /usage lit le coût réel, la ligne Prompt cache dit si votre session recycle bien son préfixe.
  • Un sous-agent garde les grosses lectures hors de votre fenêtre principale ; /subtask et /fork sont les portes d'entrée.

Module suivant : CLAUDE.md, règles et mémoire : apprendre le projet à Claude — pour que la moitié de ce contexte se recharge automatiquement à chaque session sans qu'on ait à taper quoi que ce soit.