Divulgation progressive : donner à l'IA le bon contexte sans tout lui faire lire

L’ancre de cette série a posé un constat : un agent ne dispose que de ce qui est dans son contexte, et une large part de ce qui rend une application métier correcte n’est écrite nulle part. La réaction la plus fréquente à ce constat est d’écrire, beaucoup, puis de tout charger. Un fichier d’instructions qui grossit à chaque incident, une documentation projet versée d’un bloc en début de session. Le résultat déçoit presque toujours : l’agent qui sait tout se comporte comme celui qui ne sait rien. Il ignore la règle qui comptait, contredit une convention posée trois pages plus haut, réécrit ce qui existait déjà.

Le problème n’est pas la quantité de documentation, c’est son mode de livraison. Une base de connaissances utile à un agent ne se charge pas, elle s’aiguille. Chaque module porte une description courte, toujours visible, qui dit ce qu’il contient et quand le lire ; le détail n’entre dans le contexte que pour le module que la tâche justifie. Ce principe a un nom, la divulgation progressive, et il vient de l’ergonomie des interfaces bien avant de servir aux modèles de langage.

Cet article décrit les deux façons dont un agent perd pied faute d’un contexte bien servi, montre d’où vient le principe et comment les mécanismes récents de skills le rendent concret et mesurable, puis le transpose à la documentation d’un projet métier en cinq gestes. Il termine sur ce que l’aiguillage ne garantit pas, et sur ce qu’un DSI (directeur des systèmes d’information) peut exiger de sa documentation avant d’y brancher un agent.

Deux façons de perdre un agent : la famine et l’indigestion de contexte

La première façon est connue. Rien n’est écrit, ou presque, et l’agent infère depuis le code ce que le code ne dit pas. Il produit alors quelque chose de plausible et de faux : il autorise la modification d’un devis validé parce qu’aucune règle ne l’interdisait dans son contexte, il contourne une contrainte réglementaire qu’il n’a jamais vue, il redéfinit le contrat d’échange avec un système voisin parce que ce contrat vivait dans la tête d’un développeur et n’avait jamais été explicité. Le code obtenu est cohérent avec lui-même et incohérent avec le système. C’est le mode d’échec que l’ancre de cette série a détaillé.

La seconde façon est le réflexe inverse, et elle est moins reconnue parce qu’elle ressemble à de la diligence. L’équipe documente tout, puis charge tout. Le fichier d’instructions à la racine du dépôt reçoit une ligne par incident et atteint 40 pages. La documentation projet est collée intégralement dans chaque session. Trois effets s’ensuivent. Le coût, d’abord : chaque tâche paie la lecture de l’ensemble, y compris des neuf dixièmes qui ne la concernent pas. L’attention, ensuite : les travaux de Liu et al. ont montré que la performance d’un modèle chute nettement quand l’information utile se trouve au milieu d’un contexte long, et Anthropic décrit dans son billet d’ingénierie sur le context engineering un « budget d’attention » qui s’épuise à mesure que le contexte grossit. La contradiction, enfin : une documentation de 40 pages contient au moins une règle périmée, et l’agent la lit avec la même confiance que la règle courante. Il n’a aucun moyen de savoir laquelle des deux conventions contradictoires est celle d’aujourd’hui.

Les deux modes d’échec ont une racine commune. Dans les deux cas, la connaissance n’est pas là où l’agent en a besoin, au moment où il en a besoin. Le contexte est un budget, pas un sac dans lequel verser tout ce qui pourrait servir. Chaque token dépensé à lire une convention sans rapport avec la tâche est un token qui ne sera pas dépensé à lire le code en cours de modification. La question utile n’est donc pas « avons-nous assez documenté ? » mais « la bonne page arrive-t-elle au bon moment, et seulement elle ? ».

Un principe d’interface qui a 20 ans, et le mécanisme qui le rend mesurable

La réponse à cette question existe depuis longtemps dans une autre discipline. En 2006, Jakob Nielsen formalise la divulgation progressive comme réponse à une tension classique de l’ergonomie : les utilisateurs veulent à la fois des fonctions puissantes et une interface simple. Le principe tient en deux temps. Montrer d’abord peu d’options, les plus importantes ; proposer le reste sur demande. L’interface reste lisible, la puissance reste accessible, et l’utilisateur décide lui-même quand descendre d’un niveau.

La transposition demande peu d’efforts. Le lecteur est désormais un agent. L’écran est la fenêtre de contexte. Les options avancées sont les modules de documentation. Ce qui doit rester visible en permanence est petit et décisif : assez pour choisir quoi ouvrir, pas assez pour faire le travail. Ce qui est lourd n’apparaît qu’après une décision d’ouverture. Un principe conçu pour ménager l’attention humaine s’applique presque mot pour mot à un système dont l’attention est, elle aussi, une ressource comptée.

Ce qui a changé récemment, c’est qu’un mécanisme d’outillage rend ce principe concret et chiffré. Les skills documentés par Anthropic fonctionnent sur trois niveaux. Au premier niveau, seules les métadonnées de chaque module (un nom et une description) sont chargées au démarrage, pour une centaine de tokens par module. Au deuxième niveau, le corps du module n’entre dans le contexte que lorsque la demande correspond à sa description, pour moins de 5 000 tokens. Au troisième niveau, les ressources annexes (scripts, gabarits, références) ne coûtent rien tant qu’elles ne sont pas explicitement appelées. La documentation précise que la description doit dire à la fois ce que fait le module et quand l’utiliser, parce que c’est elle que le modèle compare à la demande pour décider de l’ouvrir.

Lu avec des yeux d’ingénieur, ce mécanisme est un index à trois étages. Le point qui compte est le suivant : c’est la métadonnée d’entrée qui fait l’aiguillage, jamais le corps du document. Une description mal écrite envoie l’agent au mauvais endroit ; un corps chargé sans nécessité dilapide le budget. La même logique se retrouve, sous d’autres noms, dans les fichiers de règles à déclencheur de la plupart des assistants de code, dans les conventions de fichiers d’instructions partagés entre outils, et dans ce qu’Anthropic appelle la récupération « juste à temps » : l’agent garde des identifiants légers (un chemin de fichier, une référence) et ne charge le contenu qu’au moment de s’en servir. Le principe n’appartient à aucun éditeur. Ce qui varie, c’est si l’outillage l’impose ou si l’équipe doit l’inscrire elle-même dans sa documentation.

Transposer à la documentation d’un projet : la base de connaissances modulaire et auto-aiguillée

Une documentation de projet métier n’est pas un ensemble de skills, mais elle peut emprunter la même architecture. Cinq gestes suffisent à transformer un corpus monolithique en base de connaissances que l’agent aiguille lui-même.

Le premier geste consiste à découper par domaine de décision plutôt que par type de fichier. Un agent en cours de tâche se pose des questions d’une classe précise : quelle règle métier s’applique ici, quelle frontière d’architecture ne pas franchir, quelle convention de code est en vigueur, quel contrat me lie au système voisin, quelle donnée est sensible, comment ce composant se déploie. Chaque classe de questions devient un module. Règles métier et invariants, architecture et frontières, conventions, intégrations et contrats externes, sécurité et données, exploitation. Le découpage suit les décisions que l’agent aura à prendre, pas l’arborescence du dépôt.

Le deuxième geste normalise l’en-tête de chaque module, parce que c’est l’en-tête qui aiguille. Un nom. Une description d’une phrase construite sur le modèle « lire quand », par exemple « règles de facturation : lire avant toute modification touchant devis, avoirs ou remises ». Un périmètre, un état et une date de dernière revue, un propriétaire. Tout le reste du module peut être long, technique, dense. L’en-tête, lui, doit pouvoir être lu en trois secondes et déclencher la bonne décision d’ouverture. Un en-tête complet tient en cinq lignes :

Module : règles de facturation
Lire quand : toute modification touchant devis, avoirs ou remises
Périmètre : calcul des montants, exports comptables ; hors gestion des paiements
État : à jour, revu le AAAA-MM-JJ
Propriétaire : équipe back-office

Le troisième geste tient l’index racine court. Le fichier d’instructions à la racine du dépôt, quel que soit son nom selon l’outil, ne contient plus que deux choses : les invariants transverses qui s’appliquent à toute tâche, et la liste des descriptions de modules. Un ordre de grandeur utile est celui d’un écran, lisible par un humain en une minute. Tout le reste est à un lien de distance. Si l’index déborde, un module manque ou une description est trop longue.

Le quatrième geste référence les annexes lourdes sans jamais les inliner. Schémas de données, contrats d’API (interfaces de programmation), décisions d’architecture consignées (ADR, architecture decision records), journaux d’incidents : tout cela existe, est pointé depuis le module concerné, et n’entre dans le contexte que si le module l’appelle. C’est le troisième étage de l’index, celui qui ne coûte rien tant qu’il n’est pas ouvert.

Le cinquième geste teste l’aiguillage. Donner à l’agent une tâche représentative et observer ce qu’il ouvre. S’il ouvre le mauvais module, ou aucun, la description est en cause, pas l’agent. Répéter l’exercice sur une dizaine de tâches typiques du projet. C’est l’équivalent exact d’un test d’utilisabilité, avec un utilisateur qui laisse des traces complètes de son parcours.

Un exemple récent illustre l’ensemble. Un logiciel professionnel en mode SaaS (Software as a Service, logiciel proposé en service hébergé), en phase de lancement, avait accumulé au fil de sa construction une documentation projet de plusieurs dizaines de pages, complète et peu utilisée. L’équipe l’a refondue selon ces cinq gestes : un index racine, des modules par domaine, une description d’une ligne par module. L’effet s’est vu sans instrument de mesure. L’agent a cessé de relire l’ensemble à chaque session et s’est mis à ouvrir le module que la tâche appelait ; les conventions ont cessé d’être redécouvertes, puis contredites ; et la documentation s’est remise à vivre, parce que chaque module avait désormais une raison précise d’être ouvert, donc corrigé.

Ce que l’équipe y gagne, au-delà de l’agent

L’agent n’est pas le premier bénéficiaire. Une base de connaissances aiguillable est d’abord une documentation que les humains lisent. Le développeur qui rejoint le projet parcourt l’index, ouvre le module qui correspond à son ticket, et découvre en même temps la règle et la raison de la règle. Il entre par la même porte que l’agent, et cette porte a été testée.

La description devient un contrat. Écrire « lire quand » oblige l’auteur à dire à quoi sert le module. Un module dont personne ne parvient à formuler le « quand » est un module qui n’a pas de raison d’exister seul : il fusionne avec un autre ou disparaît. Cette contrainte élague la documentation bien plus sûrement qu’une revue annuelle.

La fraîcheur suit le même mouvement. Un module qui est ouvert est un module qui est corrigé, parce que l’erreur est vue au moment où elle coûte. L’état et la date de revue portés dans l’en-tête rendent l’obsolescence visible avant qu’elle ne soit lue. La documentation monolithique, elle, n’est corrigée par personne parce qu’elle n’est lue par personne : son volume la protège de la lecture, et donc de la correction.

Beaucoup d’équipes pratiquent déjà ce pattern pour les humains sans l’avoir nommé. Une note de cadrage qui renvoie vers les bons corpus au lieu de les reproduire, des fiches de synthèse qui résument et orientent, un registre de décisions d’architecture consulté avant chaque évolution : c’est de la divulgation progressive, appliquée à des lecteurs humains. Les agents n’ont rien inventé. Ils ont rendu l’absence de ce pattern coûteuse, et sa présence mesurable, en tokens consommés et en tâches réussies. Le nommer permet de le reproduire d’un projet à l’autre et de l’auditer.

Ce que l’aiguillage ne garantit pas

Une description mal écrite envoie l’agent au mauvais endroit, et rien ne le signale. L’agent ne sait pas ce qu’il n’a pas ouvert. Ce mode d’échec est plus insidieux qu’une erreur franche, parce que le travail produit paraît complet. La qualité des descriptions est donc un objet de revue à part entière, au même titre que le code.

Un module périmé induit en erreur avec assurance. La divulgation progressive réduit le volume lu ; elle ne valide pas ce qui est lu. Elle appelle une gouvernance minimale : un propriétaire par module, une cadence de revue, une description versionnée avec le code qu’elle décrit, et une revue des modifications de modules aussi exigeante que celle du code lui-même.

L’agent peut décider de ne pas ouvrir un module. L’aiguillage repose sur le jugement du modèle face à une description ; c’est un contrôle que l’agent choisit d’appliquer, pas un contrôle que le système impose. Une précédente publication de ce blog a posé la différence entre ces deux natures de contrôle, et elle vaut ici sans réserve. Pour tout ce qui doit tenir quoi qu’il arrive, une règle de sécurité, une opération irréversible, une contrainte réglementaire, la base de connaissances n’est pas le mécanisme. Les tests, les points de contrôle de la chaîne d’intégration continue et les permissions le sont.

Enfin, organiser le savoir ne crée pas le savoir. Un module ne peut encoder que ce que quelqu’un a rendu explicite, et l’explicitation reste la compétence la plus sous-estimée du métier. La divulgation progressive est une discipline de livraison pour une connaissance qui existe. Elle ne remplace ni l’atelier où les règles métier sont formulées, ni la revue du code que l’agent produit. Sa place est ailleurs : elle rend les autres contrôles moins coûteux, parce qu’un agent bien aiguillé commet moins d’erreurs évitables, et que les tests et la revue n’ont plus à rattraper que ce qui reste.

Ce qu’un DSI peut exiger de sa documentation avant d’y brancher un agent

Quatre exigences résument l’ensemble, et chacune se vérifie en une séance.

Un index racine qui tient sur un écran, dont chaque ligne dit quand ouvrir le module qu’elle décrit. Des modules découpés par domaine de décision, chacun avec un propriétaire et une date de revue lisibles en en-tête. Une séparation nette entre ce qui est toujours chargé, ce qui se charge à la demande et ce qui n’est que référencé. Et une preuve d’aiguillage : sur les tâches courantes du projet, l’agent ouvre le bon module, et cette preuve se rejoue à chaque refonte de la documentation.

Cette feuille prolonge l’analyse de l’ancre de la série : un prototype IA tient en démonstration et coince en production parce que la couche d’ingénierie qui fait tenir un système reste à construire. La documentation qui sait dire quand il faut la lire est l’une des pièces de cette couche, la moins coûteuse à poser et souvent la première absente.

Une documentation qu’un agent peut aiguiller est une documentation qu’une équipe peut reprendre. C’est le même test, et il se passe avant la première ligne de code générée.