Je n'écris pas la documentation

Avant le second brain, dont je parlais dans l'article précédent, il y avait un problème plus bête, et plus ancien : chaque session repartait de zéro sur le projet lui-même.

Un README de 2 400 lignes

Début 2026, je suis encore sur Cursor. L'app avance, le serveur de la radio tourne, et j'ai déjà des instructions écrites. Un README de 2 400 lignes dans le repo du backend : le modèle d'origine de Payload, des règles de sécurité ajoutées au fil de l'eau, et à côté un dossier plein d'audits et d'enquêtes. Un document pour l'agent, et pour moi à l'époque où je ne le laissais pas encore toucher au serveur.

Parfois l'agent trouvait la bonne info. Il lisait la structure du repo, retrouvait la procédure, faisait ce qu'il fallait. Parfois non. Et je ne savais jamais à l'avance.

Donc je précisais tout. « Redémarre le serveur. Attention, on a une procédure pour ne pas couper le stream. Cherche-la, confirme-moi que tu l'as, et applique. » Et je le redisais à chaque fois qu'on touchait au serveur.

En mars, on arrête. Le 11, premier manuel dans le repo du backend, un dossier .ai/ : l'architecture, le domaine, les flux, les règles, les automatisations. Le 16 dans l'app, le 19 sur le site. Les CLAUDE.md ne sont arrivés que quelques semaines plus tard, avec Claude Code. Ces manuels, je les ai faits pour Cursor, pour ne plus avoir à tout réexpliquer.

Aujourd'hui, je dis « redémarre le serveur », et l'agent sait comment on fait. « Va voir combien d'auditeurs on a en ce moment » : l'alias SSH de la machine, ce qui tourne dessus, quelle URL expose quoi, c'est écrit. Et sur le site de l'agence, « ajoute une page avec ce contenu » veut dire Astro, du contenu qui vient de Sanity et jamais du code, le design system avec ses échelles, et les règles d'écriture qui vont avec.

La ligne qui évite la catastrophe

Dans le manuel d'infrastructure de DIA, il y a une ligne qui m'a sans doute évité quelques catastrophes. Elle est écrite en anglais, comme tout le reste : le dossier des fichiers audio sur le serveur n'est pas la source de vérité. C'est un cache, dimensionné pour les prochaines vingt-quatre heures de programmation. Ce qui n'y est pas se trouve sur le stockage d'archive. Un fichier absent ne veut pas dire un fichier perdu.

Sans cette ligne, un agent qui cherche un épisode de la semaine dernière et ne le trouve pas conclut à une perte de données. Au mieux il enquête sur un problème qui n'existe pas. Au pire il « répare ».

Même chose pour ce qui est interdit, nommément. Sur le backend, les routes qui déplacent les fichiers avant et après diffusion sont marquées dangereuses : elles ne tournent qu'avec un interrupteur explicite en plus de l'authentification. C'est écrit dans le manuel, avec la raison.

C'est ce que je cherche dans un manuel : ce qu'il faut savoir avant d'agir, ce qu'on ne fait pas seul, et ce qui n'est pas ce qu'il paraît. Le reste, l'agent le trouve dans le code.

La doc, c'est mon métier

Cahiers des charges, spécifications fonctionnelles, PRD : c'est mon métier, et je le fais toujours. La documentation est essentielle sur un projet, elle l'a toujours été. Avec des agents, encore plus.

Seul sur un projet, on a tout dans la tête. On documente bien au début, et puis on part dans le flux de production, on enchaîne, et la doc passe à côté. Le projet grossit, et un jour ça devient un vrai problème.

Aujourd'hui, les agents documentent en même temps que moi, sur ce qu'on est en train de construire ou ce qu'on vient de finir. Pendant qu'on développe, qu'on produit, qu'on teste, ils écrivent la doc, les specs, les changelogs, les items de backlog. J'ai mon chef de projet, mon scrum master et mon senior dev à côté de moi, qui documentent tout au fil de l'eau. On ne peut pas faire plus agile.

Écrite pour les agents, lisible par les humains

Aujourd'hui, la doc est d'abord écrite pour les agents. Un agent ouvre le projet plusieurs fois par jour, sans aucun souvenir de la veille, et il se réfère à ce qui est écrit, à chaque fois. Mais elle doit rester lisible par un humain, parce que le jour où quelqu'un intervient à la main sur le projet, c'est la même doc qu'il lit.

Et ce n'est pas moi qui l'écris. Les agents écrivent la doc pour les agents, pour que tout le monde travaille correctement, humains compris.

L'agent vient de passer des heures dans le repo. Il a lu le code, pas ma description du code. Il connaît la structure réelle, les dépendances réelles, les endroits où ça devient tordu. Moi je décris le projet de mémoire, lui le décrit à partir du code.

Moi, je vérifie. Est-ce que c'est juste. Est-ce que ça dit bien ce qu'on ne touche pas. Est-ce qu'il n'a pas inventé une règle que je n'ai jamais suivie. Et quand je corrige, la correction va dans la doc. Mes mails clients, c'est Claude qui les rédige et moi qui les relis : chaque brouillon que je refuse devient une règle dans un fichier d'écriture, avec l'exemple refusé et la bonne version. Le mail suivant l'applique sans que je la redise.

À quoi ça ressemble

Un CLAUDE.md court à la racine, que l'agent lit au début de chaque session. Un AGENTS.md à côté, trois lignes qui renvoient au premier, pour Codex et les autres. Et quand le projet grossit, un dossier .ai/ qui porte le détail, pour que CLAUDE.md reste un sommaire.

Le squelette est le même sur tous nos projets, vingt-huit aujourd'hui :

La mise en place pas à pas, avec le prompt qui fait remplir tout ça par l'agent, est dans un guide à part.

Un manuel faux, c'est pire

Un manuel décrit un projet à un moment donné. Le projet bouge, le manuel non. Au bout de quelques mois, une partie est fausse, et un manuel faux est plus dangereux qu'un manuel absent, parce que l'agent le croit.

Ça m'est arrivé en écrivant cet article, justement. J'avais deux plans pour la suite du journal : une note dans le brain, et une feuille de route à côté des articles. Les deux disaient des choses différentes, et la feuille de route traînait une ligne écrite un matin d'août et rendue caduque le soir même. Claude l'a crue, et m'a annoncé le mauvais article comme le prochain. On a remonté l'historique git ensemble pour retrouver ce que j'avais vraiment décidé, on a corrigé la feuille de route, et la note du brain renvoie maintenant vers elle. Il n'y a plus qu'un seul plan.

Tout ça est un chantier permanent. On se trompe, on corrige, et la doc comme les process s'ajustent un peu plus à ma façon de bosser à chaque fois. C'est même ce que j'aime le plus dans ce système : il n'est jamais fini, il se façonne à l'usage.

Pour la doc, je pose simplement la question. « Est-ce que la doc est encore à jour ? Qu'est-ce qui a changé, qu'est-ce qu'il faut corriger ? » L'agent vient de travailler dans le code, il voit l'écart tout de suite. Il rend une liste, je valide, il corrige.

Faites-le une fois, deux fois. La troisième, vous savez ce qu'il faut en faire : une skill. Un processus écrit une fois et rejoué à l'identique, que l'agent écrit lui-même parce qu'il vient de le suivre trois fois avec vous. Les skills méritent un article à elles, avec celles qu'on utilise vraiment. Il viendra.

Deux fois le même geste

Avec les manuels, j'ai arrêté d'expliquer mes projets. Avec les skills, j'arrête d'expliquer comment on travaille. Je ne me demande plus si j'ai le temps d'écrire quelque chose. Je me demande si j'ai envie de le redire la semaine prochaine.

Un manuel rend un projet lisible. Vingt-huit manuels au même endroit, à côté d'un brain et d'une poignée de skills, ça fait autre chose que vingt-huit projets lisibles. C'est l'article du mois prochain, et c'est ce qui a vraiment changé ma façon de travailler.