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

Publié le 27 April 2026

Résumé

Quand on travaille avec un agent IA comme Opencode sur des projets complexes sur plusieurs sessions, on fait face à un problème fondamental : la fuite de contexte. L’agent ne se souvient pas de la session précédente. Tout ce qu’on lui a expliqué — l’architecture, les conventions, l’état du backlog — est perdu. Reconstruire ce contexte à chaque session est coûteux, lent et source d’erreur.

Cet article expose la stratégie artisanale que j’ai construite pour résoudre ce problème : un système de gouvernance persistant basé sur des fichiers AsciiDoc, avec une dichotomie Eager/Lazy pour optimiser la consommation du token de contexte, et une procédure de fin de session incontournable pour assurer la continuité.

1. La Scène : Lundi 21 Avril, 9h00

Je rouvre Opencode pour reprendre mon plugin Gradle plantuml-plugin. Hier soir, j’ai passé trois heures à discuter avec l’agent de l’architecture du pool de clés API — rotation round-robin, gestion des quotas, fallback automatique. Ce matin, l’agent me regarde avec des yeux de poisson rouge.

 — Bonjour, je suis votre assistant Opencode. Comment puis-je vous aider aujourd’hui ?

Pas de — Ah oui, le pool de clés API, on en était à la structure YAML. Pas de — Attention, PlantumlManager est un objet Kotlin singleton, pas une classe. Pas de — Non, on a décidé hier que SyntaxValidationResult restait une sealed class nested dans PlantumlService.

Tout est à refaire. Ou plutôt : tout est à réexpliquer. Je vais passer les vingt premières minutes de ma session à reconstituer un contexte que l’agent a déjà eu entre les mains hier. Vingt minutes de tokens brûlés. Vingt minutes où je pourrais coder, mais où je fais du pédagogique obligatoire.

Ce n’est pas un bug d’Opencode. C’est la nature même des LLM conversationnels : entre deux sessions, la mémoire de travail est entièrement effacée. L’agent ne se souvient pas de la mission précédente, des décisions prises, des pièges identifiés, du code qu’on a écrit ensemble.

J’ai vécu ça des dizaines de fois. Sur quatre projets simultanés. Avec des sessions qui s’enchaînent sur des semaines. J’ai calculé : en moyenne, 30 à 40 % du temps de session était consacré à recontextualiser l’agent. À la session 87 du projet plantuml-plugin, j’ai craqué. Je ne pouvais plus me permettre de réexpliquer pour la dixième fois que AttemptEntry est une data class top-level dans DiagramProcessor.kt.

Il me fallait un système. Pas un hack. Une vraie gouvernance.

2. La Genèse : Du Chaos à la Méthode

2.1. Les Premières Sessions : L’Âge des Ténèbres

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.

2.2. L’Épisode du site.yml Détruit (Session 2, bakery-plugin)

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 :

NE JAMAIS écraser un fichier config avec un Write complet quand un Edit partiel suffit. NE JAMAIS remplacer des valeurs sensibles par des valeurs factices. Vérifier git check-ignore et git ls-files avant toute modification.

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.

2.3. La Migration Markdown → AsciiDoc (Session 1, cheroliv.com)

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 :

  • Conversion de AGENTS.md en AGENT.adoc

  • Création des agents spécialisés : CODER.adoc, SCRUM_MASTER.adoc, PLANTUML_DESIGNER.adoc

  • Création de la structure Eager/Lazy : INDEX.adoc, SESSIONS_HISTORY.adoc, AGENT_SESSION_MANAGER.adoc, SESSION_CHECKLIST.adoc, PROCEDURES.adoc

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

Timeline de croissance des sessions sur les 4 projets

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.

3. La Stratégie : Eager/Lazy en Profondeur

3.1. Philosophie : Cache Informatique Appliqué à la Cognition

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).

Eager (Tableau de Bord) Lazy (Manuel du Propriétaire)

Taille

< 100 lignes, < 10k tokens

Illimité, détaillé

Chargement

Auto, en début de session

Sur demande de l’agent

Contenu

Règles absolues, mission courante, état critique

Archives de sessions, historique complet, procédures détaillées, références techniques

Rôle

Orienter immédiatement l’agent

Répondre aux questions de contexte profond

3.2. Les Fichiers Eager : Le Tableau de Bord

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.

Architecture Eager/Lazy des fichiers de gouvernance

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

  • Les règles absolues du projet (pas de commit sans permission, pas de rm sans confirmation)

  • La structure du projet et les conventions de code

  • Les commandes essentielles (./gradlew serve, ./gradlew test)

  • Les épopées et le backlog produit (user stories priorisées)

  • Les critères de qualité transverses (accessibilité, responsive, compatibilité)

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 :

  • Le numéro de session et la mission prioritaire

  • Le résumé de la session précédente (ce qui a été fait, ce qui reste à faire)

  • Les critères d’acceptation de la session courante

  • Les rappels techniques spécifiques

.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, quatre projets y figurent :

| magic_stick    | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 |
| bakery-gradle  | Session 11 | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| cheroliv.com   | Session 9  | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS   | 2026-04-23 |

*_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.

3.3. Les Fichiers LAZY : Le Manuel du Propriétaire

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.

Arborescence complète du dossier .agents/

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 :

  • plantuml-plugin : 133 sessions archivées (de la session 1 à 133)

  • bakery-plugin : 11 sessions

  • magic_stick : 23 sessions

  • cheroliv.com : 9 sessions formelles + 7 sessions pré-système reconstituées rétroactivement

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 :

| -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10
|  1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10
|  7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10
|  8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10

.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. 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 :

  • AB_PARTITION_REFERENCE.adoc (147 lignes) — Architecture partition A/B GPT, scripts update-system.sh, tailles estimées, mécanisme de rollback

  • BOOT_TEST_REFERENCE.adoc (144 lignes) — Procédure QEMU + VNC pour tester le boot de l’ISO sans matériel physique, checklist BIOS/UEFI, limitations CI/CD

Sur plantuml-plugin :

  • ARCHITECTURE.adoc (134 lignes) — Structure des 11 data classes, points d’attention (pièges à éviter), commandes de test optimisées

  • API_KEY_POOL_REFERENCE.adoc — Détails complets du pool de clés (LAZY pendant que ESSENTIALS est EAGER)

4. Les Agents Spécialisés : Une Équipe Virtuelle

La gouvernance ne se limite pas à des fichiers passifs. J’ai formalisé des rôles d’agents spécialisés dans des fichiers LAZY dédiés, qui définissent le workflow attendu selon le type de tâche.

Agent

Fichier

Rôle

Projet

CODER

CODER.adoc

Implémentation FTL/CSS/JS, balises sémantiques, critères d’accessibilité

cheroliv.com

SCRUM Master

SCRUM_MASTER.adoc

Planification US, découpage en sous-tâches, détection des dépendances

cheroliv.com

PlantUML Designer

PLANTUML_DESIGNER.adoc

Création de diagrammes, syntaxe PUML, intégration JBake

cheroliv.com

Le fichier CODER.adoc sur cheroliv.com contient des règles concrètes : Un seul <h1> par page, Préfixer les chemins avec `${content.rootpath}`, Déclarer la langue `<html lang="${content.lang!"fr"}">`. Ces conventions, écrites une fois, sont respectées automatiquement par l’agent depuis la session 1.

Le fichier SCRUM_MASTER.adoc impose une structure de livrable : Objectif, Tâches (ordonnées avec assignation), Critères d’acceptation, Risques. Quand je demande un plan d’action, l’agent produit cette structure sans que je l’aie demandée. La gouvernance programme l’agent.

Flux d’une session type avec Eager/Lazy et agents

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.

5. La Procédure de Fin de Session : La Règle d’Or

5.1. Pourquoi elle est Incontournable

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 :

  • Durée : 15-30 minutes

  • Fichiers modifiés : 1-3 maximum

  • Échanges LLM : 5-10 messages

  • Contexte tokens : < 50k

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.

5.2. Le Flux des 6 Étapes (Silencieusement)

Flux de la procédure de fin de session

5.3. Les Résultats de 150+ Sessions

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

plantuml-plugin :

  • 133 sessions depuis le début du projet

  • 240/240 tests PASS (100% couverture) — EPICs 1-7 terminées

  • 57 scénarios Cucumber BDD validés

  • Règle de sûreté sur les fichiers de config née d’une erreur réelle (Session 2 bakery-plugin)

bakery-plugin :

  • 11 sessions en deux semaines

  • Migration Supabase → Firebase terminée (9 tests corrigés)

  • EPIC 6 (publishProfile) fonctionnel en production

  • Règle 0 créée : publishToMavenLocal obligatoire après chaque modif

magic_stick :

  • 23 sessions pour construire un système live Xubuntu avec partition A/B

  • Première ISO générée à la session 10

  • Tests de boot QEMU + VNC formalisés (documentation LAZY de 144 lignes)

  • CI/CD SourceForge fonctionnel

cheroliv.com :

  • 9 sessions formelles + reconstitution de 7 sessions pré-système

  • Article 0101 (OpenCode PATH) publié

  • Article 0108 (celui-ci) réécrit après analyse de ses lacunes

  • Gouvernance complète migrée de Markdown vers AsciiDoc

5.4. La Checklist Finale

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

✅ Procédure de fin de session exécutée
📋 Checklist :
[✅] 1. Archive session N créée
[✅] 2. PROMPT_REPRISE.adoc mis à jour pour session N+1
[✅] 3. SESSIONS_HISTORY.adoc mis à jour
[✅] 4. INDEX.adoc mis à jour
[✅] 5. TEST_COVERAGE_ANALYSIS.adoc mis à jour (si applicable)
[✅] 6. COMPLETED_TASKS_ARCHIVE.adoc mis à jour

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

6. Les 4 Projets, 4 Gouvernances, 1 Méthode

Le système Eager/Lazy n’est pas un boilerplate copié-collé. Chaque projet a adapté la méthode à ses spécificités.

6.1. cheroliv.com : Le Site Personnel

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.

6.2. bakery-gradle : Le Plugin Multi-Purpose

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.

6.3. plantuml-gradle : Le Plugin IA

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.

6.4. magic_stick : Le Système Live

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.

7. Règles Absolues Transverses

Quelques règles critiques qui apparaissent dans le fichier AGENT.adoc Eager et s’appliquent à toutes les sessions sur tous les projets :

Environnement de dev

  • ✅ Utiliser la commande propre au projet (./gradlew serve, ./gradlew functionalTest, etc.)

  • ❌ Interdit d’utiliser des scripts externes non versionnés

Git

  • ✅ Lecture seule autorisée (git status, git diff, git log)

  • ❌ git add, git commit, git push interdits sans permission explicite

  • ❌ git commit --amend interdit sauf conditions méticuleusement respectées

Fichiers de Configuration

  • ❌ Ne jamais écraser un fichier config avec un Write complet quand un Edit partiel suffit

  • ❌ Ne jamais remplacer des valeurs sensibles par des valeurs factices

  • ❌ Vérifier git check-ignore et git ls-files avant toute modification

Tests

  • ❌ Ne jamais lancer de tests en procédure de fin de session sans permission explicite

Outils Interdits

  • ❌ TodoWrite et Task — la gouvernance se fait via les fichiers AsciiDoc, pas via des outils externes

8. Pourquoi AsciiDoc ?

J’ai choisi AsciiDoc pour plusieurs raisons pragmatiques qui ont un impact direct sur l’efficacité de la gouvernance :

  1. Structure sémantique riche : sections, tableaux, admonitions, attributs de document. Un agent lit mieux un document structuré qu’un fond de texte.

  2. Attributs de document (:jbake-type:, :jbake-status:) qui permettent de définir des métadonnées lisibles par la machine et l’humain.

  3. Compatibilité avec JBake : mon site statique est généré par JBake, qui traite nativement l’AsciiDoc. Les fichiers de gouvernance et les articles de blog partagent le même format. Mon article de blog sur la gouvernance est écrit dans le même format que la gouvernance elle-même.

  4. Longévité : AsciiDoc est un format de documentation technique éprouvé, avec une spécification stable.

9. Résultat : Une Continuité sans Couture

Depuis que j’ai mis ce système en place, passer d’une session Opencode à l’autre est devenu fluide. L’agent reprend exactement où je l’ai laissé, sans que j’aie à recontextualiser quoi que ce soit.

Les décisions prises à la session 3 sont accessibles à la session 133. Le backlog reste cohérent sur quatre projets simultanés. Les règles de sécurité (notamment sur git et les fichiers de config) sont respectées parce qu’elles sont omniprésentes dans le fichier Eager.

Les chiffres parlent :

  • 150+ sessions archivées au total

  • 60% de tokens EAGER économisés après optimisation (Session 109)

  • Zéro rappel nécessaire sur le contexte métier du pool de clés API

  • 100% des tests PASS sur plantuml-plugin (240/240)

  • Une seule catastrophe (Session 2 bakery-plugin) qui a donné naissance à la règle de sûreté absolue

C’est un système artisanal, construit avec les outils du métier (AsciiDoc, git, Gradle), sans dépendance à une plateforme propriétaire. Il reflète ma conviction fondamentale : un développeur crédible construit et utilise ses propres outils.

10. Liens

Le code qu’on écrit pour soi est le laboratoire du code qu’on enseigne aux autres.