Architecture de Claude Code
Comment Claude Code fonctionne sous le capot : sessions, gestion du contexte, persistance de la memoire. Comprendre ces mecanismes pour piloter l'agent efficacement.
Ce que fait Claude Code a chaque tour
Claude Code n’est pas un programme qui “se souvient” entre deux appels. C’est une boucle agentique : a chaque tour de conversation, il reconstruit un contexte complet et l’envoie au modele Claude via l’API.
La composition du contexte
A chaque tour, le contexte envoye au modele contient :
- Le system prompt — instructions d’Anthropic + le contenu de CLAUDE.md
- L’historique de conversation — tous les messages user et assistant precedents
- Les resultats d’outils — contenu des fichiers lus, sorties de commandes, resultats de recherche
Point cle : Le modele n’a pas de memoire entre les appels API. Tout ce qu’il “sait” est dans le contexte qu’on lui envoie a chaque tour. Pas de contexte = pas de connaissance.
La fenetre de contexte en pratique
Claude a une fenetre de contexte d’environ 200 000 tokens. Tout ce qui est envoye au modele — system prompt, conversation, resultats d’outils — consomme des tokens dans cette fenetre.
Ou partent les tokens
| Composant | Taille typique | Impact |
|---|---|---|
| System prompt + CLAUDE.md | 1 000 - 5 000 tokens | Present a chaque tour, beneficie du prompt caching |
| Historique de conversation | Croit a chaque tour | S’accumule, devient le poste principal en session longue |
| Resultats d’outils | Variable (un fichier = 500 - 10 000 tokens) | Chaque fichier lu ou commande executee ajoute au contexte |
Attention : Quand la fenetre est pleine, Claude Code doit elaguer les anciens messages. L’agent choisit ce qu’il garde et ce qu’il supprime — mais ce choix est imparfait. Des informations importantes peuvent etre perdues sans avertissement.
Sessions et persistance
Une session Claude Code = une conversation complete, du premier message au dernier. Entre deux sessions distinctes, le modele ne conserve rien de la conversation precedente.
Ce qui persiste entre les sessions
- Le filesystem — les fichiers modifies restent sur le disque
- CLAUDE.md — relu automatiquement a chaque nouvelle session
- Les settings —
.claude/settings.json(hooks, permissions, MCP)
Ce qui ne persiste pas
- L’historique de conversation
- Les decisions et raisonnements de l’agent
- Les fichiers lus (ils sont relus si necessaire)
Point cle :
claude --resumepermet de reprendre une session existante. L’historique est recharge dans le contexte. Bonne pratique : terminer une session par un resume que l’agent peut relire au prochain--resume.
Context rot : la degradation progressive
Plus une session dure, plus le contexte accumule du bruit : anciennes versions du code, instructions devenues obsoletes, resultats d’outils qui ne sont plus pertinents. C’est le context rot.
Symptomes
- L’agent “oublie” des conventions mentionnees plus tot
- Les reponses deviennent incoherentes ou contradictoires
- L’agent relit des fichiers qu’il a deja lus (il ne retrouve plus l’info dans le contexte)
Strategies de mitigation
- Sessions courtes et focalisees — une tache par session
- Prompts propres — reformuler plutot qu’enchainer des corrections
- CLAUDE.md comme memoire externe — les conventions qui comptent y sont toujours
- Sub-agents — chaque sub-agent demarre avec un contexte vierge
Recapitulatif
| Concept | A retenir |
|---|---|
| Contexte par tour | System prompt + historique + resultats d’outils, reconstruit a chaque appel API |
| Fenetre de contexte | ~200k tokens, elagage automatique quand la limite approche |
| Persistance | Filesystem + CLAUDE.md + settings. Pas l’historique. |
--resume | Recharge l’historique d’une session precedente |
| Context rot | Degradation progressive en session longue — sessions courtes et CLAUDE.md comme parade |
Remonte relire la fiche memo ci-dessus en pretant attention aux points rates, puis clique sur « Recommencer » pour retenter.