Que faut-il mettre dans le contexte d'un agent IA ?

C'est le choix, à chaque tour, de ce qu'un agent IA a sous les yeux : instructions, documents, historique, résultats d'outils. L'enjeu est contre-intuitif : plus on charge la fenêtre de contexte, moins le modèle retrouve l'information utile. Réduire le contexte est d'abord une question de fiabilité, avant d'être une question de coût.

Un arbitrage à chaque tour

Anthropic le définit dans son guide du 29 septembre 2025 par contraste avec l'écriture d'un prompt, qui est une tâche ponctuelle : le context engineering est itératif, et le tri se refait chaque fois qu'on décide de ce qu'on passe au modèle. Avec un agent qui enchaîne les tours, ce tri devient permanent.

Le guide pose le constat de départ : quand le nombre de tokens dans la fenêtre augmente, la capacité du modèle à rappeler précisément l'information diminue. Anthropic reprend le nom donné au phénomène, le context rot, la dégradation du contexte.

Plus on charge, moins ça marche

Chroma l'a mesuré en juillet 2025 sur 18 modèles, dont GPT-4.1, Claude 4, Gemini 2.5 et Qwen3, sur des tâches volontairement simples. Un seul passage proche de la réponse mais faux, un distracteur, fait déjà baisser les scores ; quatre aggravent la baisse, et l'écart se creuse à mesure que le texte s'allonge.

Chroma précise que l'écart des modèles Claude vient surtout de leurs abstentions : face à l'ambiguïté, ils préfèrent ne pas répondre. Le rapport porte sur des tâches contrôlées, et la dégradation varie d'un modèle à l'autre ; le travail d'un agent en entreprise reste à mesurer. Chroma édite par ailleurs une base de données vectorielle.

Le phénomène était connu avant les agents. L'article « Lost in the Middle » (Liu et al., publié en 2024 dans la revue TACL) montrait qu'avec 20 documents, GPT-3.5-Turbo passait de 75,8 % de bonnes réponses quand l'information utile était en tête à 53,8 % quand elle était au milieu, moins bien que sans aucun document (56,1 %). Le modèle date de 2023.

Une question de fiabilité avant d'être une question de coût

Pour nous, la conséquence est directe pour qui outille des agents : un parcours documentaire de plusieurs centaines de milliers de tokens est plus bruité que riche. Le ramener à quelques dizaines de milliers de tokens sert d'abord à ce que l'agent retrouve la bonne information. Le gain sur la facture vient en plus, puisque le contexte chargé se paie à chaque appel au modèle.

Trois niveaux à séparer

Trois sujets se mélangent souvent dans les discussions. Ce carnet les traite dans cet ordre, du plus outillé au moins mûr :

• Les fichiers de contexte d'un dépôt de code : AGENTS.md, CLAUDE.md et leurs équivalents.
• Les méthodes spec-driven, qui produisent des spécifications en markdown versionnées avec le code.
• La gouvernance documentaire de l'entreprise : documents de référence, classement, RAG.

C'est le pendant de notre carnet sur le loop engineering : là, on parlait de la boucle de l'agent ; ici, de ce qu'on met dedans.

En deux temps : des fichiers de contexte courts chargés d'office au démarrage, puis la recherche du reste par l'agent lui-même, au moment où il en a besoin. Anthropic décrit ce fonctionnement pour Claude Code. Cursor y ajoute la recherche sémantique, et l'arbitrage entre les deux approches n'est pas tranché.

Peu d'office, le reste à la demande

Le guide d'Anthropic décrit le fonctionnement de Claude Code : les fichiers CLAUDE.md sont déposés tels quels dans le contexte dès le départ, pendant que des commandes comme glob et grep permettent à l'agent de parcourir son environnement et de récupérer les fichiers au moment où il en a besoin. Anthropic qualifie ce modèle d'hybride : une partie des données chargée en amont pour aller vite, le reste exploré par l'agent.

Le bon dosage dépend de la tâche, précise le guide. Pour nous, on charge au départ ce que l'agent ne devinerait pas (les commandes, les conventions non standard) ; le reste attend qu'il le cherche.

Recherche sémantique ou recherche par mots ?

L'autre voie consiste à indexer le corpus pour une recherche sémantique, par embeddings. Cursor l'a mesurée en novembre 2025 sur son propre banc d'essai : 12,5 % de bonnes réponses en plus en moyenne quand son agent dispose de la recherche sémantique. Son agent se sert aussi beaucoup de grep, et Cursor conclut que la combinaison des deux donne les meilleurs résultats.

Dans l'autre sens, l'équipe de Claude Code a raconté en mai 2025, dans le podcast Latent Space, avoir utilisé un index vectoriel dans ses toutes premières versions, puis l'avoir abandonné pour la recherche par l'agent, qui marchait nettement mieux, sur une impression interne plus que sur une mesure publiée.

Zenika a échoué en février 2025 à consolider plusieurs documents avec un RAG classique, sur un petit corpus et des modèles locaux : le modèle ne reçoit que des morceaux de chaque document et ne voit jamais leur ensemble. Pour nous, l'arbitrage se tranche sur un pilote mesuré, avec vos documents et vos tâches.

Le contexte devient un sujet d'architecture

En France, OCTO a présenté à la Duck Conf 2026 la documentation comme le contexte de l'IA et l'architecte comme « Context Engineer du SI », avec trois niveaux de maturité (l'assistant de chat, les skills en markdown, les serveurs MCP) et un monorepo qui partage ce contexte à sa racine. Sur un projet de modernisation présenté à la même conférence, l'équipe dit passer environ 70 % de son temps à planifier et à spécifier.

Francis Eytan Dortort pousse la même logique dans le choix entre un dépôt unique et plusieurs dépôts : selon lui, avec des agents de code, la bande passante de contexte est devenue la contrainte déterminante. C'est une opinion argumentée, sans mesure.

Cela dépend de ce qu'il contient. La seule étude académique qui mesure la réussite, celle de l'ETH Zurich, ne trouve aucun gain significatif, mais un coût d'inférence accru de plus de 20 %. Vercel, sur ses propres tests, passe de 53 % à 100 % de réussite quand le fichier indexe une documentation que le modèle ne connaît pas.

Un format devenu standard

AGENTS.md est un fichier en markdown placé à la racine d'un dépôt de code, que les agents lisent avant de travailler. Publié par OpenAI en août 2025, il est revendiqué par plus de 60 000 projets open source, c'est-à-dire des dépôts qui contiennent le fichier, quel que soit l'usage qu'ils en font. Son site le dit compatible avec 23 agents et outils, dont Codex, Cursor, GitHub Copilot, Devin, Windsurf, Zed, VS Code et Junie. Claude Code lit son propre fichier, CLAUDE.md.

OpenAI l'a confié en décembre 2025 à l'Agentic AI Foundation, créée sous l'égide de la Linux Foundation avec MCP d'Anthropic et goose de Block. Sa position la plus utile est la séparation des publics : le README pour les humains, AGENTS.md pour le contexte dont les agents ont besoin (étapes de build, tests, conventions).

Ce que ces fichiers contiennent

L'étude « Agent READMEs » a recensé 2 303 fichiers de contexte dans 1 925 dépôts GitHub, puis en a annoté 332 à la main. Dans sa version d'août 2026, ces fichiers parlent surtout :

• de tests (75,9 % des fichiers annotés) ;
• de détails d'implémentation (70,8 %) ;
• d'architecture (68,1 %) ;
• de commandes de build et d'exécution (63,0 %).

Autrement dit, à peine un fichier sur sept donne des garde-fous pour que l'agent produise du code sûr ou rapide. Ces fichiers vivent : 67,0 % des CLAUDE.md sont modifiés sur plusieurs commits, avec environ un jour entre deux mises à jour en médiane (environ trois jours pour ceux de GitHub Copilot). Les traiter comme une documentation figée, c'est passer à côté de leur usage.

Ce qu'ils changent vraiment

L'étude de l'ETH Zurich est la mesure la plus solide : des agents de code sur 300 tâches de SWE-bench Lite et 138 tâches tirées de dépôts réels. Fournir un fichier de contexte n'améliore pas, en général, le taux de réussite, et augmente le coût d'inférence de plus de 20 % en moyenne. Les vues d'ensemble du dépôt, pourtant recommandées par les fournisseurs de modèles, n'aident pas.

Le détail compte. Dans la dernière version de l'étude (septembre 2026), les fichiers écrits par des développeurs améliorent la réussite de 2,4 %, ceux générés par un LLM la réduisent de 0,5 à 2 %, et aucun de ces écarts n'est significatif. Le surcoût atteint au plus 19 % pour les fichiers écrits à la main. Les auteurs leur gardent un usage : préciser les pratiques non standard du projet. La première version, de février 2026, donnait environ 4 % de gain pour ces fichiers.

Vercel a publié en janvier 2026 un résultat inverse, sur ses propres tests : des tâches qui utilisent des fonctions de Next.js 16 absentes des données d'entraînement des modèles. Sans aide, 53 % de réussite ; avec un AGENTS.md qui indexe en 8 Ko la documentation de Next.js, 100 %. Vercel édite Next.js, et l'article ne donne ni le nombre de tâches ni le modèle utilisé.

Pour nous, les deux résultats se lisent ensemble : le fichier aide quand il apporte ce que le modèle ignore (une documentation récente, des conventions maison) ; une vue d'ensemble de ce que le dépôt montre déjà n'aide pas.

Une étude plus petite mesure autre chose : le temps et les tokens. Sur 10 dépôts et 124 petites pull requests confiées à Codex, la présence d'un AGENTS.md va avec un temps d'exécution médian plus court de 28,64 % et 16,58 % de tokens de sortie en moins. Les tokens d'entrée ne baissent pas, et l'étude n'évalue pas la qualité du résultat.

LogRocket a raconté un cas en mars 2026, une même fonctionnalité développée trois fois avec Claude Sonnet 4.5 :

• sans contexte ajouté, 2,48 millions de tokens et 81 appels ;
• avec un AGENTS.md, 1,18 million et 42 appels, soit 53 % de tokens en moins ;
• avec un AGENTS.md et un skill, plus de 6 millions.

Une seule tâche et un seul essai : à lire comme un ordre de grandeur.

Court, écrit à la main, spécifique

Pour nous, un AGENTS.md sert donc à transmettre à l'agent ce qu'il ne devinerait pas : commandes, conventions, documentation récente. Les conseils de format vont dans ce sens. Un guide publié sur Red Hat Developer en juillet 2026 recommande moins de 150 lignes, et 30 à 50 pour un petit dépôt, sans mesure à l'appui.

Le Journal du Net conseille d'éviter les consignes génériques et d'y écrire plutôt :

• les commandes du projet ;
• les conventions de nommage ;
• les exigences de sécurité internes ;
• les choix d'architecture qui s'écartent des pratiques courantes.

Pas telles quelles. Un comparatif de trois outils, noté par son auteur, n'en juge aucun prêt pour une grande entreprise sans adaptation. Leur coût caché est la relecture : chez Scott Logic, une même fonctionnalité s'est faite dix fois plus vite en prompting itératif. Ce qui se transpose, ce sont les spécifications versionnées avec le code.

Un comparatif noté par son auteur

Itzhak Eretz Kdosha, ingénieur chez Palo Alto Networks, a testé en février 2026 trois outils sur une même fonctionnalité ajoutée à un service Python existant, avec Cursor et Claude Sonnet 4.5. Il les a notés sur 13 critères, de la qualité de la spécification à la santé du projet, en prévenant que ses notes sont très personnelles :

• OpenSpec : 4,00 sur 5, 3 heures de planification et un jour de mise en œuvre, 95 dollars ;
• BMAD : 3,74 en version rapide ; 3,65 en version complète, pour deux jours de planification, quatre de mise en œuvre et 200 dollars ;
• Spec Kit : 2,77, 4 heures de planification et un jour de mise en œuvre, 75 dollars.

Son verdict : aucun de ces outils n'est prêt pour une adoption en grande entreprise sans modification, du moins au moment du test. Les trois ont beaucoup évolué depuis, et Kiro, l'environnement de développement spec-driven d'AWS, ne faisait pas partie de l'essai.

Le coût caché de la relecture

Colin Eberhardt, directeur technique de Scott Logic, a développé en novembre 2025 une même fonctionnalité de son application personnelle de deux façons. Avec Spec Kit, le premier incrément a produit 689 lignes de code et 2 577 lignes de markdown, pour 33 minutes de travail de l'agent et 3 h 30 de relecture. En prompting itératif, toute la fonctionnalité a demandé 8 minutes d'agent, 15 minutes de revue de code et 9 minutes de tests.

C'est un développeur seul sur une application personnelle, qui doute lui-même d'être le public visé. Pour nous, le critère vaut pour toute pratique documentaire : le temps passé à relire du markdown généré se compare à la valeur produite avant d'adopter une méthode.

Une technique abandonnée par son créateur

L'histoire du sharding de BMAD vaut au-delà de BMAD. Cette technique découpait les gros documents (spécification produit, architecture) en fichiers par titre de niveau 2, avec un index en table des matières ; la méthode s'en servait déjà en version 4. Début 2026, la documentation l'a marquée « Deprecated » : plus recommandée, et bientôt inutile, puisque la plupart des modèles et des outils savent lancer des sous-processus.

L'outil a été retiré du projet à l'été 2026, avec la version 6.11 publiée en août, sans remplacement. Un utilisateur avait signalé dès novembre 2025 que le découpage n'économisait aucun contexte tant que le document entier restait en place ; l'équipe a corrigé. Pour nous, la leçon vaut pour toute équipe tentée par un standard documentaire maison : ne pas bâtir sur une technique que son créateur abandonne en quelques mois.

Ce qui se transpose

Ce qui reste utile dans ces méthodes, ce sont les spécifications en markdown versionnées avec le code : elles remplacent un contexte de conversation volatil et donnent à l'agent un point d'appui stable d'une session à l'autre. Ippon le montre en français, sur Kiro : la spécification devient la source de vérité du projet, versionnée avec le code et consultée chaque jour.

Deux contreparties sont à connaître :

• L'empilement consomme la fenêtre. Des utilisateurs de BMAD ont signalé en janvier 2026, sur des versions de test, 80 000 à 100 000 tokens par étape de création de story, et un agent de test qui occupait 67 % ou plus d'une fenêtre de 200 000 tokens dès son activation.
• La spécification ne vaut que ce que l'humain y apporte. Daniel Westheide, consultant chez INNOQ, soutient que la couche de spécification de BMAD dépend entièrement de la connaissance métier que l'humain apporte à l'entretien : l'agent ne peut pas fournir ce qui n'est pas dans la pièce.

L'outil rend les manques de connaissance visibles tôt, ajoute-t-il, sans pouvoir les combler : le changement d'organisation vient d'abord, les outils ensuite.

Deux pannes reviennent. La surcharge : trop de contenus mélangés, dont des versions qui se contredisent, et l'agent donne des conseils contradictoires. La dérive : le code change, la documentation reste figée, et des agents qui modifient vite le code l'aggravent. Les parades passent par des contraintes plus que par des outils.

Trop de contenus, et qui se contredisent

HubSpot a raconté en octobre 2025 ce qu'il a appris en migrant sa documentation pour développeurs vers Mintlify. Selon HubSpot, le problème venait de la surcharge plus que de contenus périmés : les modèles mélangeaient la documentation de l'ancienne API V1, celle de la V3, des exemples et des tutoriels, et en tiraient des conseils contradictoires. Sa parade : un serveur MCP qui repère l'ancienne version et ne sert que l'actuelle.

Cette étude de Deakin University et de RMIT annonce une baisse moyenne de 18,2 %, un chiffre que son propre tableau ne retrouve pas (environ 12 %). Elle mesure seulement la proximité des réponses avec une réponse de référence, et porte sur des documents médicaux. Pour nous, le scénario est pourtant le plus banal en entreprise : une politique périmée à côté de la version en vigueur, un système en fin de vie documenté au même niveau que son remplaçant.

Pour nous, la parade commence par des documents de référence datés (des golden sources) : prioriser la version en vigueur et purger l'obsolète avant d'indexer quoi que ce soit.

La documentation qui dérive

La seconde panne est la dérive de la documentation (doc drift). Fiberplane a publié en mars 2026 un outil, Drift, qui ancre les spécifications en markdown au code source et signale en intégration continue quand le code ancré a changé. L'auteur part d'un constat : les agents changent beaucoup de code et voient mal ce que leurs changements affectent ailleurs. Sa conclusion : « la vraie valeur n'est pas l'outil, c'est la contrainte ».

Deux autres garde-fous vont dans le même sens. Swimm rattache chaque partie de la documentation qu'il génère à des endroits précis du code pour éviter les hallucinations, selon l'éditeur. Et un guide de Daniel Vaughan sur Codex CLI prévient qu'un agent qui rédige les décisions d'architecture à partir du code peut en inventer le pourquoi : il propose des tests d'architecture en intégration continue plutôt que la confiance.

L'outillage autour

Sur l'outillage périphérique, trois constats :

• Les serveurs de documentation de bibliothèques ne se départagent pas. Le comparatif de MCP.Directory d'avril 2026 observe Ref meilleur sur les longues sessions d'agent, grâce à son plafond d'environ 5 000 tokens par page lue, Context7 sur les demandes courtes et DeepWiki pour comprendre une architecture, sans publier de mesure.
• Le fichier llms.txt n'aide pas un site à être cité. SE Ranking, sur près de 300 000 domaines, ne trouve aucun effet de ce fichier sur la fréquence à laquelle les LLM citent un site ; retirer cette variable a même amélioré la précision de son modèle. L'étude ne dit rien de son usage par un agent qui lit une documentation.
• Repomix compresse le code source. Cet outil rassemble un dépôt en un seul fichier pour le donner à un agent ; son option de compression, que l'éditeur annonce à environ 70 % de tokens en moins, garde les signatures des fonctions et reste expérimentale.

Non, selon nous. Un RAG sans cas d'usage précis ni évaluation échoue sans bruit, et la qualité du contenu pèse autant que le choix technique. Nous recommandons de dérouler d'abord l'inventaire, le nettoyage et le classement, puis de réévaluer le RAG quand les documents de référence existent et qu'un cas d'usage réel tourne.

Préparer le contenu d'abord

Enterprise Knowledge propose sept étapes pour rendre un contenu exploitable par l'IA, que nous résumons ici :

1. définir ce qu'on entend par contenu, cas d'usage par cas d'usage ;
2. nettoyer : doublons, quasi-doublons, contenus périmés ou faux ;
3. combler les manques, en recueillant aussi le savoir tacite ;
4. ajouter de la structure : taxonomies, métadonnées, glossaires ;
5. étiqueter le contenu selon ce modèle, avec une validation humaine quand l'étiquetage est automatique ;
6. unifier les droits d'accès ;
7. gouverner dans la durée, en améliorant par itérations.

La classification paie, selon la méthode

Une étude acceptée à la conférence IEEE CAI 2026 teste l'ajout de métadonnées générées par un LLM aux passages indexés. L'effet dépend de la méthode : sur la documentation d'AWS S3, avec un découpage simple, des métadonnées ajoutées en préfixe font passer la précision des dix premiers résultats de 0,640 à 0,798.

C'est à peine mieux qu'un découpage récursif sans métadonnées (0,783). Avec les autres découpages, le gain est minime, et une pondération TF-IDF fait moins bien que le texte seul, contrairement à ce qu'annonce le résumé de l'article. Les auteurs concluent qu'aucune configuration ne l'emporte sur tous les critères.

Leur référence de pertinence est elle-même produite par un modèle, sans annotation humaine. Pour nous, la classification s'instrumente sur vos documents : elle ne s'applique pas en aveugle.

Ce que disent les retours de terrain

SFEIR décrit en avril 2026 l'écart entre une preuve de concept, qui vise le spectaculaire, et la production, qui exige la robustesse : PDF scannés mal reconnus, tableaux coupés par le découpage, contrats de 200 pages pleins de renvois internes. Pour SFEIR, le context engineering est « une discipline à part entière ».

Sabrine Bendimerad tire six leçons de ses projets en décembre 2025, dont deux à afficher au mur : « répondre aux questions internes » n'est pas un cas d'usage, et c'est à cette étape que la plupart des projets RAG échouent sans bruit. Sans évaluation, les erreurs n'apparaissent que quand les utilisateurs se plaignent.

Notre conclusion : dérouler d'abord le tri (inventaire, nettoyage, classement, documents de référence), puis réévaluer le RAG. Et mesurer localement, avant et après, sur quelques tâches représentatives, ce que la littérature ne tranche pas.

Si un fichier de contexte rend un agent plus juste sur du travail réel, ce que vaut vraiment la recherche sémantique face à la recherche par mots, et comment se comporte un agent face à la documentation métier d'une entreprise plutôt qu'à un dépôt de code.

• L'effet des fichiers de contexte sur la réussite reste mal connu. Une seule étude académique mesure la réussite des tâches, sur des bancs d'essai publics ; Vercel l'a mesurée sur ses propres tests, dans un cas favorable ; les autres mesures portent sur le temps et les tokens.
• Aucune mesure indépendante ne départage la recherche par mots et la recherche sémantique. Les chiffres viennent de Cursor, sur son propre banc d'essai, ou d'une impression interne chez Anthropic.
• Le context rot est mesuré sur des tâches simples. Chroma et « Lost in the Middle » isolent l'effet de la longueur ; personne n'a mesuré ce que change une documentation réduite sur le travail d'un agent en entreprise.
• La documentation métier est peu étudiée. Presque toutes les mesures portent sur des dépôts de code ; les politiques, procédures et bases de connaissances d'une entreprise beaucoup moins.

Distinguer l'étude de l'avis, repérer les cas uniques et les éditeurs qui vendent l'outil dont ils parlent, et dater chaque source : ce domaine change de mois en mois.

• Plusieurs sources vendent l'outil ou le service dont elles parlent : Chroma (base de données vectorielle), Cursor (recherche sémantique), Anthropic (Claude Code), Vercel (éditeur de Next.js), Swimm et Fiberplane (leurs outils), Repomix. HubSpot est client de Mintlify, et son fonds d'investissement est entré au capital de Mintlify en avril 2026.
• Beaucoup de retours portent sur un seul cas : LogRocket (une tâche, un essai), Scott Logic (une application personnelle), le comparatif de Ran the Builder (des notes de son auteur), le projet de modernisation présenté par OCTO.
• Plusieurs études sont des préprints, et certaines ont changé de chiffres d'une version à l'autre (ETH Zurich, « Agent READMEs ») : nous citons leur dernière version.
• Les signalements sur BMAD viennent d'utilisateurs, sur des versions de test de début 2026, et les outils spec-driven évalués en février 2026 ont beaucoup changé depuis.
• « Lost in the Middle » porte sur un modèle de 2023 ; l'étude sur les documents contradictoires porte sur des questions médicales et de petits modèles.
• Les 60 000 projets d'AGENTS.md comptent des dépôts qui contiennent le fichier, y compris de tout petits : ils mesurent une présence.