Rainbow Journey a un peu plus de 36 heures. Le code a avancé vite : un premier jalon jouable, le Lot 1, une session collaborative au piano, un pack de hotfix, le Lot 2.F, puis trois des quatre chantiers du Lot 2.G intégrés en parallèle. La documentation a suivi le même rythme… et c'est devenu un problème.
Dans un projet mené avec des agents, la documentation n'est pas un à-côté : c'est le contexte. Chaque ligne qu'un modèle lit pour « reprendre » est une ligne qu'il ne consacre pas au code. Chaque statut périmé est une fausse piste. Ce billet raconte l'audit mené cet après-midi et le plan qui en sort, volontairement pas encore exécuté.
Le constat de départ
La demande tenait en deux exigences qui semblent se contredire :
- Tout garder, dans l'ordre : choix, audits, reviews, handoffs, plans, prompts, articles. On veut pouvoir valider le fil du projet sur la durée et en tirer des dossiers d'articles complets.
- Ne lire que l'utile : une doc fraîche, courte et fiable pour le développement agentique, et même logique pour le code, afin qu'un modèle n'ouvre pas quinze fichiers hors sujet.
Au bout de 36 heures, docs/ compte 56 fichiers, environ 6 000 lignes, rédigés par GPT/Astra, Copilot, Kimi, Claude, Cursor et opencode. Chacun avait ses habitudes.
Ce que l'audit a lu
L'audit a été mené par Claude Code, en lecture seule :
- les 21 documents à la racine de
docs/; - les 35 fichiers datés (devblog, handoffs, plans, prompts), confrontés un par un à leur date de nom, leur date de contenu et leur commit d'ajout ;
- la cartographie des imports des 81 fichiers de
src/, les tests, la CI et les branches.
En cours de route, FG a tranché quatre questions structurantes. On y revient plus bas.
Ce qu'il a trouvé
| Constat | Exemple concret |
|---|---|
| Rien ne sépare le vivant de l'historique | STATUS, HANDOFF et TODO mélangent état courant et récit. 634 lignes à lire avant la première ligne de code, 850 si l'on suit la consigne « Lire d'abord » |
| Les statuts vieillissent sans prévenir | TODO marque G.10, G.13 et G.16 « pas encore » alors qu'ils sont intégrés ; HANDOFF annonce 110 tests, main en compte 130 |
| Deux « plans actifs » | Cinq documents pointent vers un plan, STATUS vers un autre |
| Les codes se télescopent | « Lot 1 » désigne deux pistes différentes ; A1, H1, D1 ou P0 ont chacun trois ou quatre sens |
| Métadonnées au cas par cas | Front-matter YAML dans le devblog seulement ; ailleurs, quatre façons d'écrire une date, ou aucune |
| Pas de consignes agents versionnées | Ni AGENTS.md, ni CLAUDE.md, ni règles Cursor ; les règles d'orchestration sont recopiées dans cinq fichiers |
| Doublons | La rétro agents existe deux fois ; le Lot 1 est raconté dans quatre documents |
| Code à plat | 50 fichiers à la racine de src/ ; settings.ts importé par ~27 modules ; des tests nommés d'après les lots plutôt que d'après ce qu'ils testent |
Il y a aussi quelques erreurs factuelles figées dans l'archive (un piano « Roland FP-1 » à la place du Bird DP1, des prompts qui annoncent 89 tests au lieu de 110) et un point de sécurité, signalé à FG et traité hors de ce billet.
Rien de tout cela n'est grave isolément. Mis bout à bout, cela fait un contexte bruyant, et un agent qui démarre sur de mauvaises prémisses.
L'idée : deux régimes de documentation
La contradiction apparente disparaît quand on accepte que tous les documents n'ont pas le même cycle de vie.
L'archive est chronologique et immuable. Un plan, un contrat, un prompt ou un handoff décrit ce qui était vrai à un moment donné. On ne le corrige pas, on le date. Seuls deux ajouts sont permis : un front-matter commun et la réparation des liens.
La doc vivante est courte et reflète l'état courant, avec une date de mise à jour. Si elle ment, c'est un bug.
Le plan propose de ranger l'archive par lot : un dossier par jalon, trié par date (2026-09-13_lot-2g/ contient plan, découpage, contrat, prompts et handoffs). Un lot devient un chapitre complet. C'est pratique pour écrire un article, et un agent qui travaille sur le lot suivant sait qu'il n'a pas à l'ouvrir.
docs/
README.md index maître : quoi lire selon la tâche
etat/ STATUS, BACKLOG, QUESTIONS-FG, ROADMAP, CHANGELOG
produit/ canon gameplay, recherche émotions
technique/ architecture, invariants, données, tests, protocole DP1, perf
agents/ orchestration, registre des modèles, vocabulaire, zones, templates
decisions/ décisions datées, courtes, append-only
journal/ archive par lot + TIMELINE générée
devblog/ publicationUn front-matter pour tout le monde
Chaque document porte le même en-tête : type, date, time, lot, chantiers, agents, status, sources, superseded_by, et même errata pour signaler une erreur sans réécrire l'archive. Les codes sont qualifiés par lot (2G-A1, 2F-P1, HF-H1) : fini les collisions.
Ce front-matter sert aussi de base de données. Un script sans dépendance pourra :
- générer une TIMELINE globale ;
- lister les redirections entre anciens et nouveaux chemins ;
- assembler un dossier de lot complet, dans l'ordre chronologique, pour servir de matière première à un article.
Un point d'entrée unique pour les agents
Un seul fichier source, AGENTS.md (150 lignes au plus), décliné pour chaque outil utilisé sur le projet : Claude Code, Cursor, Kimi, Codex, Copilot, opencode avec Ollama, Minimax ou GLM. Il dit :
- quoi lire, et surtout quoi ne pas lire (l'archive, le devblog, le lockfile, les rapports HTML) ;
- les commandes ;
- les invariants non négociables ;
- où écrire quoi (une décision, un handoff, une question pour FG).
Des zones plutôt qu'un grand déménagement
Côté code, la tentation était de tout ranger dans des dossiers. FG a préféré plus prudent : des zones d'ownership, sans déplacer un seul fichier. Il y a trois raisons à cela : un chantier (A4) est encore ouvert, dix worktrees tournent, et le plan de fork technique prévoit déjà une architecture cible qu'il ne faut pas anticiper à moitié.
| Zone | Ce qu'elle possède |
|---|---|
| musique | théorie, fantômes, glyphes, styles, émotions (logique pure) |
| runtime | temps, MIDI, vélocité, sessions, presets |
| monde-3d | scène Three.js, perf |
| interface | HUD joueur, panneaux, clavier affiché |
| éditeur | onglets de réglages, règles |
| outillage | build, CI, e2e, debug |
| pivots | settings.ts, labels.ts, ui.tsx : orchestrateur seul |
Chaque zone a une fiche d'une soixantaine de lignes. Les règles Cursor et Claude en sont générées, et un contrôle vérifie que chaque fichier appartient à exactement une zone. C'est la généralisation d'une règle déjà éprouvée au Lot 2.G : runtime.ts n'est modifié que par l'orchestrateur.
Les quatre choix de FG
- Archive par lot, plutôt que par type ou par date.
- Zones sans déplacement dans
src/. - Tous les outils reçoivent leurs consignes depuis la même source.
- Docs vivantes en français accentué. La règle « ASCII sans accents » reste réservée aux libellés de l'interface, d'où elle s'était étendue aux documents par habitude.
Ce qui n'est pas fait
Le plan est déposé, pas exécuté. L'audit complet et le plan détaillé sont versionnés à côté de ce billet ; ils attendent un GO. L'ordre prévu :
- Préalables : le point de sécurité, la fusion de l'article du matin, la coordination avec le chantier A4.
- Squelette non destructif :
AGENTS.md, vocabulaire, templates, scripts de contrôle. - Déplacement de l'archive par lot, en commits « déplacement seul » pour ne pas perdre l'historique git.
- Réécriture des documents vivants.
- Génération et contrôle en CI.
Le critère de succès est mesurable : pour une tâche courante, passer de 634 lignes de documentation lues à 300 ou moins, sans perdre une seule trace du chemin parcouru. On vérifiera en donnant la même petite tâche à trois agents différents et en comptant ce qu'ils ouvrent.
Audit et plan : docs/audits/2026-09-13-audit-documentation-code-contexte-agents.md et docs/plans/2026-09-13-plan-architecture-docs-agents.md (dépôt privé).