Gouverner un Agent IA avec du AsciiDoc : Ma Stratégie Eager/Lazy pour des Sessions Opencode sans Fuite de Contexte

Mon premier projet avec Opencode, plantuml-plugin, a démarré sans aucune gouvernance. Je pose une question, l’agent répond, on itère, la session se termine, et le lendemain on repart de zéro. C’était la session 1, puis la 2, puis la 3…​ jusqu’à la session 62 où je réalise que j’ai perdu des heures cumulées à réexpliquer la même architecture.

À la session 62, les chiffres sont là : 198 tests unitaires passent, 42 tests fonctionnels validés, le plugin fonctionne. Mais le coût cognitif est insupportable. Chaque nouvelle session commence par un monologue de vingt minutes sur la structure du projet.

La méthode naît aussi d’une catastrophe. Sur le projet bakery-gradle, à la session 2, je demande à l’agent de modifier le fichier site.yml. L’agent, sans vérifier si le fichier est versionné, fait un Write complet qui écrase le contenu. Résultat : les tokens réels (clés API Firebase, secrets de déploiement) sont remplacés par des placeholders factices. Le fichier n’était pas dans git — il était dans .gitignore pour protéger les secrets.

Sans sauvegarde. Sans git restore possible. Je suis bloqué. Il me faut reconstruire manuellement le fichier de configuration, retrouver les tokens dans mes gestionnaires de mots de passe, tout recoller.

C’est de cette frustration que naît la Règle Absolue 1b :

Cette règle, aujourd’hui gravée dans le marbre de tous mes fichiers AGENT.adoc et INDEX.adoc sur quatre projets, est née d’une erreur réelle qui m’a coûté une heure de travail manuel.

Le 25 avril 2026, sur cheroliv.com, je prends une décision radicale : convertir l’intégralité de la gouvernance de Markdown vers AsciiDoc. Ce n’est pas esthétique. C’est fonctionnel. AsciiDoc offre une structure sémantique que les LLM lisent mieux : sections hiérarchiques, tableaux typés, admonitions (NOTE, WARNING, CAUTION), attributs de document lisibles par la machine.

La session 1 de cheroliv.com formalise la structure :

Un seul commit : 90975e9 refactor: migrate agent governance from Markdown to AsciiDoc. Et le site continue de fonctionner.

La timeline ci-dessus illustre la progression réelle. Le point de bascule est la session 87 : c’est là que la frustration du recontextualisation répétée dépasse le seuil de tolérance, et que la méthode Eager/Lazy cesse d’être une idée pour devenir une obligation.

Mon approche s’inspire directement de la gestion de cache informatique. Tout ce qui est critique et fréquemment utilisé doit être immédiatement accessible (Eager). Tout ce qui est contextuel ou volumineux doit être chargé sur demande (Lazy).

Ces fichiers vivent à la racine de chaque projet et sont chargés automatiquement par l’agent au début de chaque session. Ils forment le tableau de bord — information critique, immédiatement accessible.

AGENT.adoc — Le fichier maître. Sur cheroliv.com, il fait 200 lignes et contient :

Sur bakery-plugin, la Règle 0 est différente : ./gradlew -q publishToMavenLocal obligatoire après chaque modification du code source. Parce que tester le plugin sans republier le JAR local m’a fait perdre une heure à débugger un code qui n’était pas encore empaqueté.

PROMPT_REPRISE.adoc — La mission de la session en cours. Mis à jour à chaque fin de session, il contient :

.agents/INDEX.adoc — Le point d’entrée. Il résume les règles absolues, les sessions récentes, et surtout le portefeuille de projets gérés avec la même méthodologie. À ce jour, cinq projets y figurent :

*_ESSENTIALS.adoc — Un ajout récent (Session 109, plantuml-plugin) pour optimiser encore le contexte Eager. Au lieu de charger 200 lignes de contexte métier sur le pool de clés API, je charge 50 lignes de l’essentiel, et les 150 autres lignes restent en LAZY dans *_REFERENCE.adoc.

Résultat mesuré : passage de ~25k tokens EAGER à ~10k tokens (gain de 60%). L’agent n’a plus besoin de rappels énergivores.

Ces fichiers vivent dans .agents/ et ne sont lus que quand l’agent en a besoin. Ils constituent la véritable richesse de la méthode, car ils accumulent la connaissance du projet sans polluer le contexte courant.

L’arborescence ci-dessus montre la structure réelle du dossier .agents/ sur plantuml-plugin, le projet le plus mature. Notez la profondeur en trois couches : fichiers racine (métadonnées), dossier sessions/ (archives chronologiques), et dossier archives/ (agrégations et résumés). C’est cette profondeur qui transforme la gouvernance d’un simple fichier TODO en une mémoire organisationnelle complète.

.agents/sessions/{N}-{titre}.adoc — Les archives détaillées de chaque session. Actuellement :

Chaque archive contient le contexte complet de la session, les décisions prises, les problèmes rencontrés et leur résolution, les commandes exécutées et leur output.

.agents/SESSIONS_HISTORY.adoc — Un tableau récapitulatif de toutes les sessions avec un score. Exemple sur cheroliv.com :

.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc — Les tâches terminées archivées par mois, pour ne pas surcharger le backlog actif. Quand une user story est terminée, elle migre ici. Le backlog reste lisible : maximum 10 items actifs.

.agents/PROCEDURES.adoc — Templates détaillés de la procédure de fin de session. Long, mais lu une seule fois par l’agent quand il apprend la méthode. Ensuite, la procédure devient mécanique.

.agents/AGENT_MODUS_OPERANDI.adoc — La documentation stratégique complète. Sur plantuml-plugin, ce fichier fait 900+ lignes et se nomme en réalité AGENT_METHODOLOGIES.adoc — j’ai changé le nom entre l’écriture de cet article et la mise en place effective. Ce genre de divergence de naming est inévitable dans un système artisanal qui évolue. L’important est la convention de nommage : si le fichier documente la méthode, il commence par AGENT_ ou un préfixe explicite. Il documente la méthodologie Eager/Lazy, les patterns à suivre, les anti-patterns à éviter. Il est LAZY parce qu’un agent n’a pas besoin de relire toute la stratégie à chaque session, seulement quand il y a ambiguïté.

*_REFERENCE.adoc — Les références techniques spécifiques au projet. Sur magic-stick, deux fichiers LAZY denses :

Sur plantuml-plugin :

La création des agents spécialisés suit une courbe naturelle. Au début d’un projet, vous n’en avez pas besoin — AGENT.adoc suffit largement. Mais quand le projet grandit (disons, au-delà de 20 sessions), deux signaux doivent vous alerter :

Sur cheroliv.com, c’est arrivé à la session…​ 1. Oui, dès le départ. Parce que ce projet est un site web avec trois langages (FTL, CSS, JS), du contenu AsciiDoc, et des diagrammes PlantUML — trois domaines qui n’ont rien à voir. L’agent CODER a besoin de connaître les tailles de police et les media queries ; l’agent PLANTUML_DESIGNER a besoin de connaître la syntaxe @startuml. Sans séparation, l’agent CODER me proposait des diagrammes, et vice versa. Le chaos.

Sur jhipster-gradle-plugins, j’ai créé deux agents spécialisés adaptés au développement de plugins Gradle : PLUGIN_DEVELOPER.adoc et BACKLOG_MANAGER.adoc. Le premier encode toutes les conventions Kotlin/Gradle (pas de !!, data classes pour les modèles, @TaskAction pour les tâches). Le second sait que persistence doit être stable avant que assistant ne démarre son développement — une dépendance critique dans un mono-repo.

L’erreur à ne pas commettre : créer trop d’agents trop tôt. plantuml-plugin a attendu la session 108 avant de formaliser un agent spécialisé pour le pool de clés API. Avant ça, le contexte métier tenait dans AGENT.adoc. La règle empirique : un agent spécialisé se justifie quand son domaine métier dépasse 100 lignes de documentation.

Un détail qui paraît futile mais qui devient critique quand on atteint 100 sessions. Comment nommer les fichiers d’archive ?

J’ai appris à mes dépens qu’une convention est nécessaire — quatre projets, quatre formats différents au début, et je ne m’y retrouvais plus. Aujourd’hui, la convention que j’ai stabilisée est :

Exemples concrets : * 1-chore-migration-gouvernance-agent.adoc — session 1, type chore * 10-solidification-tests.adoc — session 10, sans type explicite (le sujet suffit) * 036-debug-graphify-symlink-epic9.adoc — session 36 avec numéro sur 3 chiffres pour le tri

Le numéro de session est le critère de tri principal. Les projets utilisant des numéros sur 3 chiffres (001, 036, 133) évitent les problèmes de tri lexicographique quand on dépasse 99. C’est ce que j’utilise désormais sur magic-stick : 001-init-projet.adoc, 036-debug-graphify-symlink-epic9.adoc.

Le type est facultatif et dérivé des mots-clés de la session (debug, feature, refactor, docs, chore, test). Le sujet en kebab-case est la partie la plus importante : il doit permettre de retrouver une session sans ouvrir le fichier. Si vous vous demandez « c’était quelle session où on a corrigé le timeout des tests d’intégration ? », la réponse est 124-fix-timeout-integration-test.adoc.

Pour les sessions historiques reconstituées (projets nés avant la gouvernance), j’utilise des numéros négatifs. Sur cheroliv.com, les sessions -6 à 0 couvrent toute l’histoire pré-gouvernance du projet. Et pour les sessions « non documentées » ou perdues, je crée une entrée dans SESSIONS_HISTORY.adoc sans archive correspondante, avec un score ?. C’est plus honnête que faire semblant.

L’étape 5 de la procédure de fin de session est la plus mystérieuse. Elle dit « Mettre à jour TEST_COVERAGE_ANALYSIS.adoc si des tests ont été ajoutés ou modifiés. » Mais à quoi ressemble ce fichier ?

Sur plantuml-plugin, il a évolué de quelques lignes à une structure complète. Voici sa forme stabilisée :

L’intérêt n’est pas le fichier lui-même — c’est l’obligation de noter ce qui a changé. Sans cette étape, après 50 sessions, vous ne savez plus quels tests couvrent quoi. L’agent non plus. Le fichier devient le référentiel unique de vérité sur la couverture de tests du projet.

Pour les projets sans tests traditionnels (comme magic-stick qui teste des scripts bash), l’étape 5 est remplacée par SCRIPT_VERIFICATION.adoc. Le mécanisme est le même : un fichier qui suit l’état de validation des scripts. Adaptez l’étape 5 à votre projet, mais ne la sautez jamais. Elle est le filet de sécurité qui empêche la régression silencieuse.

Si votre projet n’a aucun test — ni unitaire, ni fonctionnel, ni script — créez quand même le fichier vide avec une section « À faire : définir une stratégie de test. » C’est un marque-page qui rappellera à votre futur vous que ce sujet n’est pas traité.

Le diagramme ci-dessus montre le cycle de vie complet d’une session. Le point clé est la bifurcation après le chargement EAGER : soit la mission est assez claire pour exécuter directement (80% des cas), soit l’agent charge du LAZY pour résoudre une ambiguïté (20% des cas). C’est cette discrimination qui économise les tokens.

Sans cette procédure, la stratégie Eager/Lazy ne sert à rien. C’est elle qui transforme le travail de la session en information persistante. Elle s’exécute à la demande explicite de l’utilisateur (mots-clés : "fin de session", "je quitte", etc.), et elle est obligatoire — aucune exception, aucune omission.

Le fichier SESSION_CHECKLIST.adoc définit des métriques de session idéale :

Et des signes qu’il faut changer de session : Le LLM répète des erreurs déjà corrigées, Plus de 3 fichiers modifiés en parallèle, Conversation > 50 messages. La règle d’or : Mieux vaut 5 sessions de 20 minutes qu’une session de 2 heures avec debugging chaos.

Voici ce que donne cette procédure appliquée systématiquement sur mes quatre projets :

plantuml-plugin :

bakery-plugin :

magic-stick :

cheroliv.com :

Après exécution silencieuse des 6 étapes, l’agent doit afficher une checklist de confirmation :

Règle absolue : aucune étape ne peut être marquée [✅] si le fichier n’a pas été effectivement modifié et vérifié.

C’est le premier fichier. Pas AGENT.adoc, pas INDEX.adoc. opencode.json d’abord, pour une raison simple : si vous créez AGENT.adoc en premier, vous allez oublier de créer le pont qui le charge automatiquement. Je l’ai fait sur bakery-plugin, je sais de quoi je parle.

Deux dossiers vides. sessions/ recevra les archives de chaque session. archives/ recevra les COMPLETED_TASKS_ARCHIVE mensuels. Ces dossiers doivent exister avant que l’agent n’ait besoin d’écrire dedans. Un agent qui doit créer le dossier ET le fichier en même temps, c’est un agent qui peut échouer silencieusement.

Structure minimale pour la première version (elle grandira) :

Ce template minimal permet à l’agent de démarrer. La version riche — avec la structure du projet, les composants clés, les EPICs, le backlog — viendra à la session 1, quand l’agent aura déjà les règles de base en main et pourra vous aider à enrichir le document.

Un fichier qui dit explicitement : « Ceci est la session 1, mission à définir. » Maximum 70 lignes, avec une section Session 0 (résumé du bootstrap) et une section Session 1 (priorités à définir avec l’utilisateur).

Le fichier qui contiendra les règles absolues (version exécutive) et le tableau des sessions. Pour le bootstrap, il liste les règles 0 à 3 dans leur format concis, le portefeuille de projets (en incluant le nouveau projet avec un emoji 🆕), et la roadmap vide prête à être remplie.

Dans l’ordre :

Si votre projet a un domaine métier complexe (comme jhipster-gradle-plugins avec son mono-repo persistence/assistant), créez les agents spécialisés dès maintenant :

Ne créez pas d’agents que vous n’utiliserez pas. Un agent sans conventions concrètes à encoder est un fichier mort qui pollue .agents/.

C’est l’étape qu’on oublie systématiquement. Chaque INDEX.adoc de chaque projet contient un tableau « Portefeuille de Projets » qui liste TOUS les projets avec la même méthodologie. Quand vous créez un nouveau projet, vous devez :

Sur mes quatre (maintenant cinq) projets, cela veut dire ouvrir les INDEX.adoc de magic-stick, bakery-gradle, cheroliv.com, plantuml-gradle et y ajouter la ligne jhipster-gradle-plugins | Session 1 | …​ | 2026-04-28 🆕.

C’est fastidieux. C’est manuel. C’est aussi la seule façon de garantir que, quel que soit le projet sur lequel vous travaillez, l’agent sait quels autres projets existent et quel est leur état. À la session 012 de magic-stick, l’agent a détecté deux incohérences dans le portefeuille — bakery-gradle avait son COMPLETED_TASKS_ARCHIVE en retard, et plantuml-gradle avait un décalage entre sa documentation de procédure (5 étapes) et son INDEX (6 étapes). Sans ce tableau transverse, ces incohérences seraient restées invisibles.

Je vous entends d’ici : « Mais c’est de la duplication ! » Oui. C’est de la duplication volontaire. Chaque INDEX.adoc est autonome. Si vous ouvrez une session sur magic-stick, l’agent doit savoir que plantuml-gradle en est à la session 133 sans avoir à ouvrir un fichier dans un autre répertoire. C’est le prix de l’indépendance entre projets — et il est de 5 lignes par portefeuille.

Tout ça prend 20 minutes. Vingt minutes une fois, pour ne plus jamais en perdre vingt au début de chaque session. Le ROI est immédiat : dès la session 2, l’agent reprend là où vous avez laissé la session 1.

Sur jhipster-gradle-plugins, ce bootstrap m’a pris exactement 18 minutes — de mkdir .agents/ au dernier INDEX.adoc mis à jour dans le portefeuille de magic-stick. La session 1, qui suivra, démarrera avec un agent qui connaît déjà la structure du mono-repo, les commandes Gradle, et le boundary critique entre persistence/ (lightweight) et assistant/ (lourd). Vingt minutes bien investies.

Spécificité : Contenu éditorial, accessibilité WCAG 2.1 AA, JBake statique. Adaptation : Six épopées priorisées (P0-P4), agents spécialisés (CODER, SCRUM_MASTER, PLANTUML_DESIGNER), critères d’acceptation transverses sur l’accessibilité. Règle emblématique : ./gradlew serve obligatoire, interdiction formelle du script jbake.sh externe.

Spécificité : Plugin Gradle avec tâches de publication, génération de code Firebase, parsing YAML. Adaptation : Règle 0 (publishToMavenLocal), règle de sûreté sur les fichiers de config renforcée par l’incident du site.yml, EPIC 9 et 10 sur la configuration multi-fichiers. Règle emblématique : publishToMavenLocal après chaque modification du code source du plugin.

Spécificité : Intégration LangChain4j, génération de diagrammes PlantUML via LLM, tests avec clés API cloud. Adaptation : Documentation LAZY dense (ARCHITECTURE, API_KEY_POOL_REFERENCE, DATASET_FINETUNING), EPICs numérotés (1-11 terminés, 107+ en cours), séparation EAGER/LAZY optimisée (gain de 60% de tokens). Règle emblématique : Fichiers *_ESSENTIALS.adoc (50 lignes) vs *_REFERENCE.adoc (illimité) pour le pool de clés API.

Spécificité : Build d’ISO Linux live (Xubuntu), partitionnement GPT A/B, CI/CD avec SourceForge. Adaptation : Références techniques LAZY complexes (AB_PARTITION, BOOT_TEST), SCRIPT_VERIFICATION.adoc comme étape 5 spécifique (pas de tests traditionnels, mais vérification de scripts bash). Règle emblématique : isoTestAB skipé en CI (runners non privilégiés), tests réservés aux environnements locaux avec Docker --privileged.

C’est l’erreur numéro un. Vous avez écrit un magnifique AGENT.adoc de 200 lignes, mais il n’est jamais chargé automatiquement. L’agent démarre nu. Vous passez 20 minutes à le recontextualiser — exactement ce que la méthode est censée éviter.

Symptôme : L’agent pose des questions basiques sur la structure du projet alors que tout est dans AGENT.adoc. Correction : Créer opencode.json avec le bloc instructions: ["AGENT.adoc"]. Vérifier que le fichier existe dans le working directory d’Opencode.

À la session 2 de votre projet, vous créez 5 agents spécialisés. Aucun n’a de contenu réel, ce sont tous des stubs. Résultat : .agents/ est pollué de fichiers vides, et l’agent hésite sur lequel charger.

Symptôme : Des fichiers d’agent contenant uniquement « À définir » ou une structure vide de 10 lignes. Correction : Un agent spécialisé se justifie quand son domaine métier dépasse 100 lignes ou qu’il encode au moins 5 règles concrètes. En dessous, le contenu tient dans AGENT.adoc.

PROMPT_REPRISE.adoc est mis à jour…​ mais uniquement à la fin de la session, quand l’agent exécute la procédure. Entre-temps, la mission réelle de la session a dérivé — on a corrigé un bug imprévu au lieu d’implémenter la feature planifiée. Le PROMPT_REPRISE.adoc de fin de session ne reflète pas ce qui s’est vraiment passé.

Symptôme : La section « Priorités » de PROMPT_REPRISE.adoc mentionne une feature qui n’a pas été touchée, alors que vous avez passé la session sur un bug critique. Correction : Mettre à jour PROMPT_REPRISE.adoc en temps réel quand la session dérive de sa mission initiale. Ne pas attendre la procédure de fin de session pour documenter le changement de cap. 30 secondes d’édition pendant la session valent mieux qu’un PROMPT_REPRISE mensonger.

La procédure de fin de session crée l’archive…​ mais l’agent, pressé d’afficher sa checklist, remplit le template avec des placeholders. {detail} devient « Détail à compléter plus tard ». Ce « plus tard » n’arrive jamais.

Symptôme : Des archives de session contenant les mots « TODO », « à compléter », ou des sections vides. Correction : La règle absolue dit qu’aucune étape ne peut être marquée [✅] si le fichier n’a pas été effectivement modifié. Appliquez-la à vous-même : relisez l’archive avant d’afficher la checklist. Si une section est vide, remplissez-la maintenant.

Vous créez un nouveau projet avec une gouvernance parfaite. Mais vous oubliez de l’ajouter au portefeuille des autres projets. Trois semaines plus tard, vous ouvrez une session sur magic-stick et l’agent vous dit que vous avez 4 projets. Vous en avez 5. L’agent ne le sait pas.

Symptôme : Le comptage des projets dans les portefeuilles ne correspond pas à la réalité. Correction : Scriptez la mise à jour du portefeuille, ou au minimum maintenez une checklist post-bootstrap qui inclut « Mettre à jour le portefeuille de tous les projets existants ». C’est l’étape la plus fastidieuse de la méthode, et donc la plus souvent omise.

Vous copiez-collez le même backlog de 50 lignes dans AGENT.adoc et INDEX.adoc. À la session suivante, vous mettez à jour l’un mais pas l’autre. Vos deux fichiers EAGER se contredisent.

Symptôme : Des divergences entre les EPICs listées dans AGENT.adoc et celles dans INDEX.adoc. Correction : La redondance doit être assumée et bornée. AGENT.adoc contient le backlog détaillé avec user stories. INDEX.adoc contient UNIQUEMENT le tableau récapitulatif des EPICs (nom, progression, priorité). Si les deux divergent, c’est INDEX.adoc qui fait foi — parce que c’est lui qui est mis à jour à chaque fin de session. Documentez cette règle dans votre AGENT.adoc : « En cas de divergence entre AGENT.adoc et INDEX.adoc, INDEX.adoc est la source de vérité. »

Vous ignorez les signaux du SESSION_CHECKLIST.adoc. 2 heures, 85 messages, 12 fichiers modifiés. L’agent tourne en boucle, vous aussi. Vous auriez dû changer de session il y a 45 minutes.

Symptôme : Le LLM répète des erreurs déjà corrigées, le contexte tokens dépasse 80k, vous avez modifié à la fois persistence/ et assistant/ dans la même session. Correction : Le SESSION_CHECKLIST.adoc existe pour une raison. Respectez-le. La règle d’or n’est pas une suggestion. 5 sessions de 20 minutes > 1 session de 2 heures.