Réduire le contexte sans perdre les décisions

Donner « tout le contexte » à un agent paraît être la solution la plus sûre. En pratique, c’est souvent une manière coûteuse de mélanger le pertinent, l’ancien et le secondaire.

Le problème ne se limite pas au prix des tokens. Un contexte trop large augmente aussi le risque qu’une instruction obsolète, une exception ancienne ou une idée jamais validée pèse autant qu’une décision actuelle.

J’essaie donc de traiter le contexte comme une mémoire de travail, pas comme une sauvegarde complète du projet. La question n’est pas « qu’est-ce que je pourrais lui donner ? », mais « quel est le plus petit ensemble qui permet une décision correcte ? ».

Les quatre couches de contexte

Je charge généralement le projet en quatre couches, dans cet ordre.

1. La carte et l’état actuel

La première couche répond à deux questions :

• où trouver les informations ;
• où en est réellement le projet aujourd’hui.

Dans un repo agent-friendly, cela correspond souvent à AGENTS.md et CURRENT.md.

Cette première lecture doit suffire à identifier le domaine de la tâche sans charger immédiatement tous les contrats du projet.

2. Les décisions du domaine concerné

Une fois la zone identifiée, je charge uniquement les décisions qui peuvent contraindre le travail.

Pour une tâche UI, cela peut être le design system et quelques décisions d’interface. Pour un changement de facturation, ce seront les règles métier et les tests de billing. Pour un moteur de jeu, le contrat du module concerné.

Le principe est important : la pertinence est déterminée par la tâche, pas par l’existence du document.

3. L’implémentation et les preuves

Ensuite seulement viennent :

• les composants concernés ;
• les types ;
• les tests ;
• les données ou fixtures ;
• éventuellement le comportement réellement observé en production.

Cette couche permet de confronter la documentation à ce que le système fait réellement.

4. L’historique, si une ambiguïté subsiste

Git history, anciennes PR, discussions et conversations sont utiles lorsqu’une contradiction existe encore.

Je ne les considère pas comme une lecture de démarrage. Si un agent doit systématiquement reconstruire une règle depuis trente commits, le problème n’est plus le contexte de la session : c’est l’absence de source de vérité actuelle.

Exemple : une correction responsive

Imaginons une mission : « Sur iPad, deux blocs se chevauchent sur la page projet. »

Un plan de lecture raisonnable peut être :

1. AGENTS.md
2. CURRENT.md
3. docs/design-system.md
4. composant de la page projet
5. styles du composant
6. responsive.css

On peut ensuite élargir si un composant partagé ou une décision de design l’exige.

Lire dès le départ la roadmap, les décisions backend, tous les projets, les logs de déploiement et l’historique Git n’améliore pas cette correction. Cela augmente seulement le bruit.

Exemple : une règle métier ambiguë

À l’inverse, supposons que l’on modifie une règle de quota.

Le plan de lecture peut devenir :

1. AGENTS.md
2. CURRENT.md
3. contrat / décisions du domaine quota
4. tests existants
5. code de calcul
6. historique uniquement si les sources se contredisent

Ici, ignorer la décision durable pour économiser quelques centaines de tokens serait une fausse économie : le risque de modifier la mauvaise règle est bien supérieur.

Le contexte minimal n’est pas un contexte maigre

Réduire le contexte ne veut pas dire résumer chaque décision jusqu’à la rendre inutilisable.

Une décision importante doit conserver suffisamment de pourquoi pour ne pas être rediscutée sans raison.

Par exemple :

« Pas de backend en V0 » est faible.

« La V0 reste local-first tant que l’usage quotidien n’a pas démontré un besoin de synchronisation multi-device ; ajouter auth + backend avant ce signal déplacerait l’effort hors de la question produit actuelle » est beaucoup plus utile.

La deuxième phrase coûte plus de tokens, mais elle évite davantage de mauvaises décisions.

L’économie se fait en ne chargeant cette décision que lorsqu’elle est pertinente, pas en la vidant de son sens.

Une hiérarchie de confiance

Lorsque plusieurs sources existent, j’essaie d’avoir une hiérarchie explicite.

Par exemple :

1. contrat ou décision actuelle ;
2. tests et comportement du code ;
3. état courant du projet ;
4. documentation historique ;
5. mémoire de conversation.

Cette hiérarchie n’est pas universelle. Sur un audit de replatform, le code de production peut justement être une preuve plus forte qu’une vieille documentation.

Ce qui compte est de savoir quelle source possède la vérité pour ce domaine.

Sans cette hiérarchie, l’agent peut trouver deux phrases contradictoires et choisir simplement celle qui apparaît en dernier dans son contexte.

Le protocole de démarrage d’une session

Avant une grosse mission, j’aime que l’agent formule un mini-plan de lecture.

Pas un rapport de dix pages. Quelques lignes suffisent :

• ce que j’ai lu ;
• ce que j’ai compris de la tâche ;
• les sources supplémentaires dont j’ai réellement besoin ;
• la raison de chaque lecture.

Ce petit exercice a deux avantages.

D’abord, il rend visible un éventuel excès de contexte. Ensuite, il détecte très vite un repo mal structuré : si l’agent ne sait pas où chercher une règle de scoring ou une décision produit, le problème mérite peut-être d’être corrigé à la source.

Élargir le contexte à la demande

Pendant l’exécution, de nouvelles inconnues apparaissent forcément.

La bonne discipline n’est pas de refuser de lire davantage. C’est d’élargir le contexte à partir d’une question précise.

Quelques exemples :

• « Ce composant a-t-il une primitive commune ? » → chercher le design system.
• « Pourquoi cette limite vaut-elle 10 ? » → chercher la décision ou le test propriétaire.
• « Ce comportement est-il volontaire ou accidentel ? » → consulter le contrat puis l’historique si nécessaire.
• « Ce modèle est-il encore utilisé ? » → rechercher les références dans le code.

Chaque nouvelle lecture doit fermer une inconnue. Sinon elle devient de la consommation de contexte préventive.

Le vrai gain se joue à la fin de la session

Le meilleur plan de lecture du monde ne sert pas à grand-chose si la mission découvre une information importante puis la laisse mourir dans le chat.

À la fin, j’essaie de classer ce qui a été appris :

État temporaire

Exemple : « la branche de refactor est prête mais le preview est rouge ».

Cette information appartient à CURRENT.md et disparaîtra lorsqu’elle ne sera plus vraie.

Décision durable

Exemple : « les repos privés ne doivent jamais être exposés comme CTA publics ».

Cette information doit aller dans DECISIONS.md ou le document propriétaire du domaine.

Preuve ou contrat de domaine

Exemple : une règle de billing, un modèle de contenu, un invariant de runtime.

Elle doit vivre près du domaine concerné, pas dans un résumé de session générique.

Historique pur

Exemple : détail d’un bug déjà corrigé qui n’influence plus la suite.

Git et les PR le conservent. Inutile de le recopier dans les instructions actives.

La compression utile

« Compacter le contexte » ne signifie pas produire un résumé monolithique de toute la conversation.

Une bonne compression redistribue l’information :

• l’état actif vers CURRENT.md ;
• les décisions vers leur source durable ;
• les tâches vers le backlog approprié ;
• le bruit vers l’historique Git ;
• rien ailleurs si l’information n’a pas besoin de survivre.

C’est cette redistribution qui réduit réellement le coût des futures sessions.

Quand lire l’historique Git

Git est extrêmement utile, mais je le garde en lecture ciblée.

Je l’utilise notamment lorsque :

• le code et la documentation se contredisent ;
• une règle paraît étrange et aucun rationale actuel n’existe ;
• une régression semble avoir été introduite récemment ;
• une migration doit préserver un comportement ancien ;
• la tâche consiste justement à comprendre une évolution historique.

Je ne l’utilise pas pour apprendre systématiquement « tout ce qui s’est passé sur le projet » avant une petite correction.

Le piège du résumé universel

Une solution fréquente consiste à maintenir un énorme résumé « à donner à chaque agent ».

Ce fichier finit généralement par accumuler :

• l’architecture ;
• l’état courant ;
• des décisions ;
• des idées futures ;
• l’historique ;
• les préférences de travail ;
• des extraits de backlog.

À court terme, c’est pratique. À long terme, c’est un second projet à maintenir.

Le bon résumé universel est souvent un routeur court, pas un condensé exhaustif.

Le piège inverse : trop peu de contexte

L’économie de contexte peut devenir une obsession.

Si une tâche touche une décision structurante, la charger est obligatoire même si elle coûte cher. Si le produit possède un contrat de sécurité, l’ignorer pour gagner des tokens est évidemment une mauvaise optimisation.

J’utilise donc cette règle :

économiser le contexte inutile, jamais le contexte décisionnel nécessaire.

Une manière simple de mesurer la qualité du système

Je ne mesure pas seulement le nombre de tokens chargés. Je regarde surtout le nombre de fois où une session doit refaire une enquête déjà menée.

Un bon système devrait progressivement réduire :

• les questions « où est la vérité ? » ;
• les contradictions entre docs ;
• les relectures d’historique ;
• les prompts qui réexpliquent tout le projet ;
• les décisions répétées parce que leur rationale a été perdu.

Si ces coûts diminuent, l’économie de contexte fonctionne même si certains documents deviennent ponctuellement plus riches.

Checklist pour une mission ciblée

Avant de commencer :

• Ai-je lu la carte du repo et l’état actuel ?
• Quel domaine la tâche touche-t-elle réellement ?
• Quelles décisions peuvent contraindre ce domaine ?
• Ai-je une question précise pour chaque document supplémentaire que je vais lire ?

Pendant la mission :

• Une nouvelle lecture répond-elle à une inconnue réelle ?
• Suis-je en train de charger de l’historique simplement « au cas où » ?
• Une contradiction indique-t-elle qu’une source de vérité doit être corrigée ?

Avant de terminer :

• L’état courant a-t-il changé ?
• Une nouvelle décision doit-elle survivre ?
• Une information importante existe-t-elle encore uniquement dans le chat ?
• Puis-je supprimer ou remplacer un contexte devenu obsolète ?

Ce que l’on cherche vraiment à optimiser

L’économie de tokens est utile, mais elle n’est qu’un symptôme d’une organisation plus importante : la capacité à reprendre le projet sans reconstruire sa logique.

Un bon système de contexte permet à une tâche simple de rester simple, tout en donnant accès à la profondeur nécessaire lorsqu’un sujet devient réellement complexe.

C’est cette progressivité qui permet de travailler longtemps avec plusieurs agents sans transformer chaque nouvelle conversation en session d’archéologie.