Context engineering avec Claude Code : éviter le context rot

Il est 16 heures. Depuis le matin, tu fais avancer une migration avec Claude Code et tout allait bien. Puis l'agent réintroduit un bug corrigé à 10 heures, ignore une convention posée en début de session, et propose pour la troisième fois la même approche, légèrement reformulée. Tu corriges. Il s'excuse, change deux lignes, retombe dans le même schéma. Tu corriges encore, avec un message un peu plus sec. Tu n'as changé ni de modèle ni de dépôt, et ton prompt initial était bon. La session, elle, n'est plus la même.

Anthropic donne un nom à ce phénomène : le context rot. Le context engineering consiste à décider ce que Claude Code voit, quand il le voit et combien il en voit, pour garder une fenêtre courte et pertinente. Cet article traite de la qualité des réponses ; l'angle coût est couvert dans l'article sur les leviers natifs d'économie de tokens, auquel je renvoie pour le cache, la compaction au repos et la taille de CLAUDE.md.

Qu'est-ce que le context rot ?

Le context rot désigne la baisse de précision du modèle à mesure que la fenêtre de contexte se remplit : plus elle contient de tokens, moins il rappelle fidèlement ce qu'elle contient. Le billet Effective context engineering for AI agents (29 septembre 2025) parle d'un « attention budget » fini, que chaque nouveau token consomme, et en tire un principe : chercher le plus petit ensemble possible de tokens à fort signal qui maximise la probabilité du résultat voulu. La doc des bonnes pratiques le dit plus sèchement : la fenêtre se remplit vite, et les performances baissent à mesure qu'elle se remplit.

Conséquence pratique : la fenêtre de contexte n'est pas un disque dur, c'est une ressource d'attention. Un cat de 3 000 lignes de logs ne coûte pas que des tokens, il dilue l'attention portée à la règle de ton CLAUDE.md. Trois leviers en découlent : réduire le bruit qui entre, élaguer ce qui est déjà entré, externaliser ce qui doit survivre.

Comment reconnaître une session qui se dégrade ?

Une session ne tombe pas en panne d'un coup, elle se dégrade. Avant de la traiter, vérifie que c'est bien elle le problème. Les symptômes, du plus courant au plus trompeur :

• Il réintroduit une règle déjà posée : il remet new \DateTime() alors que tu as imposé ClockInterface. Les instructions du début sont noyées sous les sorties d'outils.
• Il refait une exploration déjà faite : il relit les mêmes fichiers, redécouvre l'architecture. L'information est dans le contexte, mais n'est plus rappelée correctement.
• Il corrige, tu recorriges, il recasse : c'est l'anti-pattern que la doc nomme « correcting over and over ». Chaque correction ratée reste dans le contexte, avec l'approche fausse qu'elle contredit.
• Il répond à côté parce que tu as changé de sujet en cours de route : feature, puis bug sans rapport, puis question sur la CI. C'est la « kitchen sink session ».
• Il ignore une ligne claire du CLAUDE.md : le fichier est probablement trop long, les règles importantes se perdent dans le bruit.
• Tout est devenu étrange d'un coup, sur toutes les sessions : ce n'est pas ta session. Vérifie /effort et ta version (voir plus bas).

Pour objectiver, suis le remplissage avec une statusline et regarde /context pour voir ce qui domine : un CLAUDE.md, un serveur MCP, un gros résultat d'outil. Ne te fie pas à un seuil magique en pourcentage : la doc n'en donne aucun. Le bon réflexe est de repérer la tendance. Si la qualité baisse avant que la fenêtre soit pleine, le problème est le bruit, pas la taille.

Quand faire /clear plutôt que corriger encore ?

Après deux corrections ratées sur le même point, fais /clear et repars avec un meilleur prompt de départ. C'est la règle officielle, et la doc la justifie en une phrase : « A clean session with a better prompt almost always outperforms a long session with accumulated corrections. » Ça coûte à l'ego, on a l'impression de perdre une heure. Mais cette heure est justement le problème : elle contient des essais faux qui polluent la suite.

Le prompt de redémarrage s'écrit avec ce que tu sais maintenant et que tu ignorais au début : le fichier concerné, la contrainte découverte en route, l'approche écartée et pourquoi. Trois phrases écrites après l'échec valent mieux que quarante messages de rattrapage. Nuance : la doc précise qu'il faut parfois laisser le contexte s'accumuler, quand tu es au cœur d'un problème complexe et que l'historique a de la valeur. Le but est un contexte à fort signal, pas un contexte vide.

Comment donner du contexte sans le saturer ?

Par des pointeurs plutôt que par des copier-coller. Anthropic appelle cela la récupération just-in-time : l'agent garde des références légères (chemins, requêtes, liens) et charge les données au moment voulu, avec ses outils. Les mentions @ et les chemins précis évitent aussi l'autre anti-pattern officiel, l'exploration infinie, où un « investigate » non borné lit des centaines de fichiers.

# À éviter : 400 lignes de code et de stacktrace collées dans le prompt
Voici le contrôleur, le service et la stacktrace : <...400 lignes...>

# Mieux : des références, un critère de fin, une commande de vérification
Les messages de la file invoice_export échouent après timeout.
Regarde @src/Invoice/Handler/ExportInvoiceHandler.php et sa config
dans @config/packages/messenger.yaml. Écris d'abord un test qui
reproduit l'échec, puis corrige. Vérifie avec :
docker compose exec php vendor/bin/phpunit --filter ExportInvoice

La même logique vaut pour CLAUDE.md, lu à chaque session. Le billet d'Anthropic parle de prompt système à la « bonne altitude » : ni logique fragile codée en dur, ni consignes vagues qui supposent un contexte partagé. En pratique : pars minimal, et n'ajoute une règle qu'après un échec observé. Pour chaque ligne, demande-toi si la retirer ferait faire des erreurs à Claude ; si non, coupe. La méthode complète est dans l'optimisation avancée de CLAUDE.md.

Quels outils pour élaguer le contexte sans tout jeter ?

• /btw : pour une question dont la réponse n'a pas à rester. Question et réponse n'entrent jamais dans l'historique. Limite : /btw n'a aucun accès aux outils et répond uniquement depuis ce qui est déjà en contexte. Pour aller chercher une information nouvelle, passe par un sous-agent.
• /rewind (ou double Échap) : revient à un point de la conversation et propose une compaction partielle. « Summarize from here » condense les messages à partir du point choisi et garde le début intact ; « Summarize up to here » condense l'ancien et garde le récent. Cas typique : un long détour de debug réglé, tu résumes à partir du début du détour. Les checkpoints ne suivent que les éditions faites par les outils d'édition de Claude, pas les changements via Bash : ce n'est pas un remplaçant de git.
• /compact ciblé : /compact Garde la liste des fichiers modifiés, les décisions d'architecture et la commande de test. Sans critère, c'est le modèle qui décide de ce qui compte.
• Sous-agents : l'exploration lourde se fait dans leur fenêtre, et seul un résumé revient, de l'ordre de 1 000 à 2 000 tokens selon Anthropic. Le pattern rédacteur et relecteur en deux contextes séparés est détaillé dans le workflow sous-agents et worktrees.

Comment garder la mémoire hors de la session ?

D'abord en traitant les sessions comme des branches : une session par chantier, nommée avec /rename migration-orm3, reprise avec claude --continue ou claude --resume. C'est la parade directe à la kitchen sink session. Mais une session reprise garde tout son historique, bruit compris. Ce qui doit survivre à un /clear, à une compaction ou à une nuit doit être écrit hors contexte.

Anthropic appelle cela la prise de notes structurée. Le billet Effective harnesses for long-running agents (26 novembre 2025) en donne le patron éprouvé : un fichier de progression, une liste de fonctionnalités en JSON (format que les modèles écrasent moins volontiers que du Markdown), un script d'initialisation et un commit descriptif en fin de session. Version quotidienne pour un projet Symfony, en trois lignes dans CLAUDE.md :

## Chantiers longs
- Un chantier multi-sessions a un fichier docs/work/<chantier>/PROGRESS.md.
- Au démarrage : lis-le. En fin de lot (tests verts) : mets-le à jour
  (fait / décisions / reste à faire / commande de vérif), puis commit.
- Ne modifie jamais la section « Critères de fin » sans me demander.

# docs/work/migration-orm3/PROGRESS.md

## Objectif
Migrer de Doctrine ORM 2.x vers 3.x sans régression.

## Critères de fin (ne pas modifier)
- docker compose exec php vendor/bin/phpunit : vert
- docker compose exec php vendor/bin/phpstan analyse : aucune nouvelle erreur

## Décisions
- On migre module par module, Billing d'abord (le moins couplé).

## Fait
- [x] Billing : entités et repositories

## Reste à faire
- [ ] Catalog (attention aux types custom)
- [ ] Reporting (requêtes DQL natives)

## Pièges rencontrés
- Les colonnes de type "array" ne passent plus : voir App\Doctrine\Type\JsonList.

Ce fichier de quelques dizaines de lignes, versionné et lisible par un humain, remplace un historique de 150 000 tokens. Le nom PROGRESS.md est une convention proposée ici, pas un nom officiel. Pour aller plus loin sur les spécifications versionnées, voir le spec-driven development avec CLAUDE.md et AGENTS.md.

Comment réinjecter le contexte critique après une compaction ?

Avec un hook SessionStart filtré sur le matcher compact. Une compaction résume, donc elle perd. Le guide des hooks a une section « Re-inject context after compaction » : tout ce que la commande écrit sur la sortie standard est ajouté au contexte de Claude après chaque compaction. La doc montre un echo de rappels, et précise qu'on peut le remplacer par n'importe quelle commande à sortie dynamique. Version « notes de chantier », dans .claude/settings.json :

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "cat docs/work/CURRENT.md 2>/dev/null; echo '---'; git log --oneline -5; git status --short"
          }
        ]
      }
    ]
  }
}

docs/work/CURRENT.md est un lien symbolique vers le PROGRESS.md du chantier actif : une seule ligne à changer quand tu bascules de chantier. Le 2>/dev/null évite une erreur bruyante si le fichier n'existe pas. Garde la sortie courte : réinjecter 2 000 lignes après une compaction annulerait le bénéfice. Ce qui doit être présent à chaque démarrage de session, pas seulement après une compaction, a sa place dans CLAUDE.md. Teste le hook une fois avant de t'y fier : un hook mal branché échoue en silence.

À quoi ressemble une migration Symfony de plusieurs jours ?

• Jour 1, exploration dans un sous-agent : « Utilise un sous-agent pour lister les dépréciations bloquantes et regroupe-les par bundle. » Seul le résumé revient dans la session principale.
• Jour 1, plan puis fichier : en plan mode, fais produire le plan, puis écris-le dans PROGRESS.md avec des critères de fin vérifiables (PHPUnit, PHPStan, lint:container). Nomme la session.
• Implémentation par lots : un lot égale un module, un commit, une mise à jour de PROGRESS.md. Les questions de détail passent par /btw.
• Quand un lot déraille : à la deuxième correction ratée, /clear, puis « lis PROGRESS.md, reprends le lot Catalog » avec le message d'erreur exact. Si le détour est derrière toi, un « Summarize from here » via /rewind suffit.
• Jours 2 et 3 : une session neuve qui relit PROGRESS.md est souvent meilleure qu'une session reprise, car elle n'a pas le bruit de la veille. Le hook compact garantit que les décisions survivent aux compactions automatiques.
• Fin de chantier : revue du diff en sous-agent, contre PROGRESS.md, en demandant de signaler les écarts de correction et pas les préférences de style.

Et si ce n’était pas ta session ?

Parfois, la dégradation vient d'ailleurs. Le postmortem Anthropic du 23 avril 2026 décrit trois changements côté Claude Code, sans effet sur l'API, qui ont dégradé la qualité perçue pendant plusieurs semaines : un effort par défaut abaissé de high à medium du 4 mars au 7 avril ; un bug distinct, du 26 mars au 10 avril, qui effaçait le raisonnement ancien à chaque tour et rendait Claude « forgetful and repetitive » ; et une consigne de concision ajoutée puis retirée en quatre jours parce qu'elle nuisait au code. Leçons pratiques : si la dégradation arrive dès les premiers échanges, sans contexte volumineux, regarde /effort avant d'accuser la session, et remonte tes observations avec /feedback. Anthropic indique que ces retours ont été déterminants.

Dernier point : tes réflexes dépendent du modèle. Dans Harness design for long-running apps (24 mars 2026), l'auteur rapporte que Sonnet 4.5 montrait une « context anxiety » assez forte pour exiger des remises à zéro de contexte, comportement largement disparu avec Opus 4.5. Réexamine tes habitudes à chaque changement de modèle, et retire ce qui ne porte plus de charge.

Quelle routine adopter au quotidien ?

• Une session nommée par chantier, /clear entre deux tâches sans rapport.
• Des chemins et des mentions @, jamais de fichiers ou de logs collés en entier.
• /btw pour les questions jetables, /rewind partiel pour élaguer un détour.
• Un PROGRESS.md que l'agent tient à jour, réinjecté par un hook SessionStart sur compact.
• Deux corrections ratées sur le même point : /clear et un meilleur prompt de départ.
• Une dégradation soudaine sur toutes les sessions : /effort, version, /feedback.

Ce qui marche sur un poste doit devenir une convention du dépôt : les trois lignes de CLAUDE.md, le hook de réinjection et la structure de PROGRESS.md se versionnent et se partagent. Un contexte propre n'est cependant qu'une moitié de l'hygiène. L'autre moitié, c'est ce que tu fais lire en permanence à l'agent : CLAUDE.md, règles, skills et hooks accumulés au fil des mois. Le prochain article fait le ménage dans cette configuration pour les modèles 5.x.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours