Context engineering : la sobriété comme condition de fiabilité

Le context engineering, c'est l'arbitrage permanent sur ce qu'on met dans la fenêtre de contexte d'un agent à chaque tour, par opposition au prompt engineering qui se joue une fois. Le constat fondateur est contre-intuitif : plus on charge, moins ça marche. Anthropic le formule sans détour dans son guide Effective context engineering for AI agents : quand le nombre de tokens dans la fenêtre augmente, la capacité du modèle à rappeler précisément l'information décroît. Chroma le corrobore indépendamment sur 18 modèles frontier, avec des scores qui tombent de plus de 95 % à environ 60 à 70 % en contexte long dès qu'on introduit des distracteurs. Les travaux académiques « Lost in the Middle » (Liu et al.) mesurent plus de 30 % de perte de précision quand l'information utile se trouve au milieu du contexte plutôt qu'aux extrémités.

La conséquence est directe pour qui outille des agents : un parcours documentaire à plusieurs centaines de milliers de tokens n'est pas riche, il est bruité. Le viser à quelques dizaines de milliers n'est pas une mesure d'économie, c'est ce qui permet à l'agent de retrouver la bonne information. Le gain de facture arrive par-dessus le marché, et il n'est pas négligeable : dans la structure de coût d'un système documentaire augmenté, l'appel au modèle domine largement le reste, OCTO allant jusqu'à parler d'un ordre de 99 % du coût de fonctionnement d'un RAG. Assertion de conférence, à prendre comme ordre de grandeur : les sources indépendantes situent plutôt le curseur entre 80 et 90 %, mais la direction est unanime.

Trois niveaux se confondent souvent dans les discussions et gagnent à être séparés : les fichiers de contexte d'un dépôt (AGENTS.md et consorts), les frameworks spec-driven qui produisent des artefacts markdown durables, et la gouvernance documentaire d'entreprise (golden sources, classification, RAG). Ce dossier les traite dans cet ordre, du plus outillé au moins mûr. C'est le pendant contexte de notre dossier sur le loop engineering : là on parlait de la boucle, ici de ce qu'on met dedans.

Le modèle qui émerge pour alimenter un agent en documentation tient en deux mouvements. Des fichiers de contexte légers injectés d'office en début de session (conventions, commandes, architecture de haut niveau), et la récupération du reste à la demande via des outils de navigation. La formulation d'Anthropic est explicite : les fichiers CLAUDE.md sont déposés naïvement dans le contexte en amont, pendant que des primitives comme glob et grep permettent d'aller chercher les fichiers just-in-time. Nuance importante, souvent perdue dans les résumés : Anthropic ne prescrit pas le just-in-time pur mais une stratégie hybride assumée, récupérer une partie des données en amont pour la vitesse et poursuivre par de l'exploration autonome.

La position n'est pas unanime, et il faut la présenter comme telle. Cursor défend la recherche sémantique par embeddings pour les agents de coding, et c'est un argument de poids dans l'arbitrage. Dans l'autre sens, plusieurs praticiens rapportent en production avoir reporté ou abandonné leur pipeline vectoriel au profit de grep et de recherche itérative agentique. Zenika documente la limite de front : le RAG fonctionne en mono-document et échoue en consolidation multi-documents, le chunking cassant les liens entre passages. Notre lecture : l'arbitrage se tranche sur un pilote mesuré, pas sur principe, et surtout pas sur la foi d'un billet de fournisseur.

Côté francophone, OCTO a théorisé exactement ce pont à la Duck Conf 2026 en posant la documentation comme dénominateur commun du contexte IA et l'architecte comme Context Engineer du système d'information, avec une stratification chat vers skills markdown vers MCP et un monorepo de contexte partagé. Leur retour d'expérience sur la modernisation d'un legacy par agents donne l'ordre de grandeur du basculement : environ 70 % du temps passe désormais dans la planification et les specs. Un argument connexe monte en parallèle, celui du monorepo contre le multi-repo, au motif que la bande passante de contexte est devenue la contrainte limitante de l'ingénierie.

AGENTS.md est un format ouvert adopté par plus de 60 000 projets open source et supporté nativement par plus de 20 outils (OpenAI Codex, Cursor, GitHub Copilot, Devin, Windsurf, Zed, VS Code, JetBrains Junie), donné à la Linux Foundation fin 2025. Sa prise de position la plus utile est la séparation assumée entre la doc pour humains (README) et la doc pour agents (AGENTS.md), cette dernière portant build, tests et conventions. Réserve de méthode à garder en tête : l'adoption est mesurée par présence de fichier, un proxy qui inclut beaucoup de dépôts triviaux.

Ce que ces fichiers contiennent réellement a été mesuré. L'étude Agent READMEs porte sur 2 303 fichiers de contexte dans 1 925 dépôts GitHub : tests dans 75 % des fichiers, implémentation 69,9 %, architecture 67,7 %, commandes de build 62,3 %, mais sécurité et performance à 14,5 % chacune. Autrement dit, presque personne n'écrit de garde-fous pour du code agent sécurisé ou performant. Second enseignement, plus opérationnel : ce sont des artefacts vivants, 59 à 67 % des fichiers étant modifiés sur plusieurs commits (67,4 % pour les CLAUDE.md), avec un intervalle médian de mise à jour d'environ un jour. Les traiter comme une doc statique, c'est passer à côté de leur mode d'emploi.

Le point le plus inconfortable est l'effet réel de ces fichiers, et il faut le regarder en face. L'étude ETH Zurich est la mesure la plus dure du domaine : les fichiers de contexte n'améliorent pas le taux de succès en général et augmentent le coût d'inférence de plus de 20 % en moyenne, les vues d'ensemble de dépôt recommandées par les fournisseurs de modèles étant qualifiées d'inutiles. Détail décisif : les fichiers écrits par des humains apportent environ 4 % de gain, ceux générés par un LLM dégradent. Une seconde étude portant sur 10 dépôts et 124 pull requests trouve l'inverse sur le coût : 28,64 % de runtime médian en moins et 16,58 % de tokens de sortie en moins en présence d'un AGENTS.md, à taux de complétion inchangé. Un retour d'expérience chiffré de LogRocket va dans ce sens sur un cas unique : 2 480 627 tokens et 81 appels d'API sans contexte ajouté, contre 1 175 645 tokens et 42 appels avec un AGENTS.md, soit 53 % de tokens en moins, l'ajout de skills faisant au contraire remonter la note au-delà de 6 millions de tokens.

On observe, sans s'emballer : le désaccord porte sur le coût, pas sur la qualité. Les trois mesures s'accordent sur le fait que le taux de réussite ne bouge pas. Ce que fait un AGENTS.md, c'est supprimer la phase de découverte large, la plus chère de la session, et encoder les conventions maison. C'est un mécanisme de conformité, pas un accélérateur d'intelligence. D'où des recommandations de format qui convergent partout : Red Hat conseille moins de 150 lignes, 30 à 50 pour un petit dépôt, et le guide du Journal du Net insiste sur le même point : éviter le générique, écrire les commandes du projet, le nommage interne, les exigences de sécurité et les choix d'architecture atypiques. Court, écrit à la main, spécifique.

Le seul benchmark contrôlé du corpus vient d'Itzhak Eretz Kdosha, ingénieur senior chez Palo Alto Networks : même feature backend brownfield en Python serverless, même IDE, quatre configurations testées. OpenSpec sort en tête à 4,00 sur 5 pour environ 1,1 jour et 95 dollars, BMAD Quick à 3,74, BMAD Full à 3,65 pour environ 6 jours et 200 dollars, Spec-Kit ferme la marche à 2,77 pour environ 1,2 jour et 75 dollars. Le verdict de l'auteur est net : aucun des frameworks testés n'est prêt pour une adoption en grande entreprise sans modification. À traiter comme un point de repère daté, avec un n égal à 1 sur une seule feature, pas comme un classement généralisable.

Le retour d'expérience le plus parlant sur le coût caché vient de Scott Logic : pour une feature de 689 lignes de code, la phase de plan a généré 2 067 lignes de markdown, soit 3,5 heures de relecture plus 33 minutes d'exécution, contre 8 minutes d'exécution et 15 minutes de revue en prompting itératif simple. Environ dix fois plus rapide sans framework, sans bénéfice qualitatif constaté sur ce cas. Le critère de gouvernance à retenir tient en une phrase, et il est transposable à toute pratique documentaire : le ratio entre relecture de markdown généré et valeur produite doit gouverner l'adoption, pas l'élégance de la méthode.

L'histoire du sharding BMAD mérite d'être connue au-delà de BMAD. Le découpage des gros documents en fichiers par titre de niveau 2, avec un index en table des matières, était la technique emblématique de la méthode en version 4. La documentation officielle du projet la marque aujourd'hui Deprecated, en indiquant qu'elle n'est plus recommandée et qu'avec le support des sous-processus par les principaux modèles et outils elle deviendra inutile. Elle n'est plus conseillée qu'en dernier recours. L'issue 892 du dépôt est encore plus directe : le sharding n'économise aucun contexte. La leçon générale est simple, et elle vaut avertissement pour toute équipe tentée par un standard documentaire maison : ne pas bâtir sur une technique que son propre créateur abandonne en quelques mois.

Ce qui reste transposable dans ces frameworks, ce sont les specs markdown persistantes versionnées dans le dépôt, qui remplacent le contexte conversationnel volatil et donnent à l'agent un ancrage stable entre sessions. Ippon décrit la même mécanique côté francophone : la spec devient une source de vérité versionnée et consultée au quotidien. Deux contreparties à connaître avant de s'engager. La première est mécanique : l'empilement specs plus architecture plus stories consomme vite la fenêtre, les issues officielles BMAD documentant 80 000 à 100 000 tokens par étape de création de story et des agents à plus de 67 % d'une fenêtre de 200 000 tokens dès l'activation. La seconde est structurelle, et c'est la critique la plus fine du corpus : INNOQ montre que la couche de spécification dépend entièrement de l'expertise domaine apportée par l'humain à l'entretien, l'agent analyste ne pouvant pas fournir une connaissance métier qui n'est pas dans la pièce. La conclusion de l'analyse est sans appel : une organisation incapable de faire du DDD correctement ne tirera rien d'une couche spec.

Le retour d'expérience le plus utile du corpus est celui de HubSpot sur sa migration de documentation développeur, parce qu'il est contre-intuitif. Leur problème n'était pas la fraîcheur de la doc mais la surcharge : trop de contexte, avec des versions V1 et V3 mélangées produisant des conseils contradictoires. La littérature mesure jusqu'à 18,2 % de performance en moins en présence de documents en conflit. C'est le scénario le plus banal en entreprise : une politique périmée qui vit à côté de la version en vigueur, un système en fin de vie documenté au même niveau que son remplaçant. D'où la logique de golden source : dater, prioriser la version en vigueur, purger l'obsolète avant d'indexer quoi que ce soit.

La seconde panne est le doc drift, aggravé par des agents qui changent le code sans voir l'impact documentaire. Fiberplane a publié un linter dédié qui détecte la dérive de façon déterministe via tree-sitter et des empreintes AST en intégration continue, avec une conclusion honnête sur son propre outil : la vraie valeur est la contrainte, pas l'outil. Swimm applique la même idée par l'ancrage statique, chaque sortie générée étant rattachée au code réel pour limiter l'hallucination. Sur les décisions d'architecture, un retour d'expérience outillé Codex CLI pose le garde-fou qui manque souvent : un agent qui génère des ADR peut fabriquer le pourquoi, d'où les fitness functions en CI et les hooks plutôt que la confiance.

Sur l'outillage périphérique, deux constats à froid. Les serveurs de documentation de bibliothèques ne se départagent pas : le comparatif Context7 contre DeepWiki contre Ref contre Docfork ne désigne aucun gagnant unique, Ref tenant mieux sur les longs runs avec un plafond d'environ 5 000 tokens, Context7 sur les demandes courtes, DeepWiki sur l'orientation architecturale. Et llms.txt est à déprioriser : l'étude SE Ranking sur environ 300 000 domaines ne trouve aucun effet mesurable sur les citations par les LLM, retirer la variable améliorant même les prédictions du modèle. Pour la rétro-documentation d'un legacy, Repomix reste le candidat naturel pour donner une vue d'ensemble ponctuelle à un agent, avec une option de compression qui revendique environ 70 % de réduction de tokens : revendication de l'éditeur, sur une fonctionnalité que son propre README qualifie d'expérimentale, et qui compresse le code, pas la documentation.

Le niveau gouvernance documentaire d'entreprise est le moins mûr des trois, et c'est aussi celui où l'on voit le plus de projets s'engager trop tôt. Le cadre le plus opérationnel vient d'Enterprise Knowledge, qui déroule sept étapes : périmètre par cas d'usage, contrôle qualité et dédoublonnage, identification des manques, enrichissement sémantique par taxonomies, étiquetage avec un humain dans la boucle, gestion des accès, gouvernance continue. La méthodologie ROT (Redundant, Outdated, Trivial) fournit les règles de purge actionnables avant toute indexation.

L'étape de classification n'est pas cosmétique, et c'est maintenant établi par une étude à comité de lecture. Les travaux publiés à IEEE CAI 2026 montrent que les métadonnées générées par LLM surpassent systématiquement le contenu seul en récupération, avec une précision passant de 73,3 % à 82,5 % et un NDCG de 0,813. Nuance à conserver : ce systématiquement vaut pour les configurations testées, certaines stratégies de métadonnées sous-performant. À instrumenter, pas à appliquer en aveugle.

Les retours de production convergent tous vers le même diagnostic : le RAG échoue sur les prérequis de gouvernance de la donnée, pas sur la technique. SFEIR documente l'écart entre POC et production, PDF scannés, tableaux, renvois internes, et pose le context engineering comme une discipline à part entière. Towards Data Science tire six leçons dont deux à afficher au mur : répondre aux questions internes n'est pas un cas d'usage, et la plupart des projets RAG échouent silencieusement. La conclusion pratique, qu'on assume : dérouler d'abord le funnel (audit, classification, golden sources), réévaluer le RAG quand les golden sources existent et qu'un cas d'usage réel tourne en production. Et mesurer localement, avec un avant et un après tracés sur quelques tâches représentatives, ce que la littérature ne tranche pas.