Voilà à quoi ressemblait ma relecture de spec il y a six mois :
« Dans la section 3, le paragraphe qui commence par "L'utilisateur doit être connecté", précise ce qui se passe si la session expire pendant que le formulaire est rempli. Et dans la partie sécurité, la contrainte sur les tokens doit être formulée comme un impératif. Attention aussi au paragraphe juste après, il reprend l'ancienne formulation… »
Voilà ce qu'on doit écrire quand on veut faire des retours à l'IA sur un document. Des dizaines de lignes de ce genre qui ne servent qu'à dire où regarder, indiquer un contexte.
Aujourd'hui, la même remarque me prend cinq mots : « et si la session expire ? », posés directement sur la phrase concernée.
C'est ce que fait notabene. L'IA s'adapte, et non l'inverse.
On sait déjà travailler ensemble
Quand plusieurs personnes travaillent sur un même document, personne n'a attendu l'IA pour savoir comment faire. On surligne un passage, on laisse un mot dans la marge, quelqu'un répond, on résout le fil. Ces gestes sont vieux de trente ans, tout le monde les connaît, et il n'y a jamais besoin de les expliquer à qui que ce soit.
Avec un les llm, tout ça a disparu. Il ne reste qu'une zone de texte.
Et comme l'outil ne sait faire que ça, c'est nous qui nous sommes adaptés. On décrit des emplacements avec des phrases, on recopie des passages pour lever le doute, on empile dix demandes dans un seul message en espérant qu'elles arrivent entières. On a rajouté de la complexité, pour compenser une interface.
Comme beaucoup d'outils et de machines au début, c'est le monde à l'envers. Une IA censée nous simplifier la vie devrait s'adapter à nos façons de faire, pas nous obliger à en apprendre une nouvelle, surtout si ce n'est pas pertinent.
Dans mon cas, c'est la spec
Quand je construis une fonctionnalité, je n'écris plus le code, j'écris la spécification détaillée. En somme, j'ai juste changé de langage.
C'est devenu l'étape qui compte le plus. L'agent code à partir de mes indications. Si c'est assez clair, le résultat sort juste du premier coup. Si c'est flou, il comble le vide tout seul.
Et il le comble bien. C'est ça, le piège. Une spec floue ne produit pas une erreur visible, elle produit une décision que personne n'a prise.
Reprenons l'exemple. J'écris « l'utilisateur doit être connecté pour accéder à cette page », et je ne dis rien de la session qui expire en plein formulaire. L'agent ne me pose pas la question. Il choisit un comportement, l'implémente proprement, et je découvre son choix à la review, ou pire, en testant.
Donc je relis. Sérieusement, ligne par ligne. Et ce qui suit vaut pour n'importe quel document produit à quatre mains avec une IA, que ce soit une spec, une note de cadrage ou un contrat.
Là où ça coince
Je repère un problème page 2, un autre page 5, un troisième dans un schéma page 8. Et pour gagner du temps, je veux faire traiter tout ça par mon agent.
J'ouvre le terminal, et il faut tout lui préciser.
Je ne peux pas simplement écrire « ce paragraphe est flou ». Il ne sait pas lequel. Je dois le situer : la page, la section, la phrase qui commence par tel mot. La plupart du temps je finis par recopier le passage, pour être sûr.
C'est long, et c'est fragile. Plus j'empile de remarques, moins l'ensemble est lisible. L'agent en traite une partie, en oublie une, en interprète une autre de travers. Je passe ensuite un quart d'heure à vérifier ce qu'il a compris.
Le problème ne vient pas de lui. Il vient du fait que je perds toute l'information en changeant de fenêtre. Quand je lisais, je savais exactement de quel paragraphe je parlais. Dans le terminal, je dois le reconstruire avec des mots. Le prompt est une bonne interface pour demander. C'en est une médiocre pour désigner.
L'idée
Reprendre les gestes qu'on connaît déjà. Commenter directement sur le texte, comme dans un Word ou un Google Docs.
Je sélectionne le passage, j'écris trois mots, je continue ma lecture. Rien à situer, rien à recopier. Le commentaire est accroché à l'endroit exact.
À la fin, une seule phrase à l'agent : « traite les commentaires. »
Il récupère chaque remarque avec sa position. Ce que je gagne, ce n'est pas du temps de frappe. C'est de ne plus avoir à reconstruire ce que j'avais déjà sous les yeux. Et je n'ai rien eu à apprendre pour ça.
Comment ça marche
L'outil génère un site de documentation à partir des fichiers Markdown. Vos specs, votre doc, tout ce qui vit en markdown. Le .md classique et le .mdx cohabitent, vous pouvez mélanger les deux selon les pages.
Vous ouvrez le site en local et vous lisez. Quand quelque chose cloche, vous sélectionnez le texte et vous commentez. Ça marche aussi sur une page entière, une image, ou un diagramme Mermaid. Chaque commentaire ouvre un fil : on répond, on met en attente, on collabore, on résout. Une page récapitule ce qui reste ouvert.
Ensuite vous passez la main à l'agent. Il lit les commentaires, modifie les fichiers source, et marque les fils comme résolus.
Certaines corrections sont plus rapides à faire soi-même qu'à expliquer. Un crayon dans la marge ouvre alors le bloc concerné directement dans la page. On édite au choix en visuel, comme dans un traitement de texte, ou en markdown brut quand on préfère voir la syntaxe. Vous enregistrez, et ça ferme au passage les commentaires auxquels la modification répond.
Le tout est stocké en JSON dans votre repo, avec le reste du code. Vos collègues annotent la même page que vous, et leurs remarques arrivent via git.
La boucle complète tient en trente secondes de démo sur le repo : un commentaire posé, l'agent qui applique, le diff que je valide.
Vérifier ce que l'agent a fait
On a tous changé notre façon d'écrire du code. Presque personne n'a changé sa façon de le relire. C'est pourtant là que se joue la qualité maintenant.
Un agent traite trente commentaires en trois minutes. Sur une spec, ça fait potentiellement trente décisions de conception que personne n'a validées.
D'où deux garde-fous.
Un journal. Chaque passage de l'agent laisse une entrée sur une page dédiée : ce qui a changé, pourquoi, et en réponse à quels commentaires. Le pourquoi sert surtout dans trois semaines, quand vous vous demanderez d'où sort cette contrainte bizarre.
Un mode « approve ». L'agent prépare ses modifications au lieu de les appliquer. Vous les validez une par une, avec le vrai diff git sous les yeux. Pas un résumé de ce qu'il pense avoir fait : le diff.
Ce qu'il n'y a pas dedans
Pas de service en ligne, pas de compte, pas de base de données. Tout vit dans le repository. Le jour où vous arrêtez d'utiliser notabene, vous supprimez un dossier.
Pas de serveur ni de MCP dans la boucle avec l'agent non plus. Il lit des fichiers et il en écrit, c'est tout. J'ai ajouté des skills pour qu'il sache directement comment utiliser l'outil, et n'importe quel agent capable de lire un fichier sait alors faire le travail.
Le serveur d'écriture ne tourne qu'en local. L'éditeur refuse aussi de modifier un fichier que git ne suit pas, parce qu'une modification non versionnée ne se rattrape pas.
En local, puis en public
C'est par ailleurs un vrai générateur de doc. Espaces, sommaire piloté par le frontmatter, recherche textuelle, multilingue avec des commentaires par langue, thème clair et sombre, diagrammes Mermaid zoomables, export PDF avec signets. On peut le mettre à son image : page d'accueil, logo, liens de navigation, polices, et un jeu de variables CSS pour reprendre votre charte.
Mais tout ce qui précède se passe chez vous. Vous lancez le site sur votre machine, vous annotez, l'agent travaille. Personne ne voit rien tant que vous ne poussez pas.
Quand la doc est prête, la même commande produit un site statique à publier. Ce build est en lecture seule et ne contient ni éditeur, ni serveur d'écriture, ni commentaires. Vos annotations de travail restent de votre côté. Vous pouvez aussi marquer des pages comme privées : elles ne partent pas dans le build public, et le lint vous prévient si un lien publié pointe vers l'une d'elles.
Le site publié inclut un llms.txt et une version Markdown de chaque page, pour que les agents le lisent correctement.
Fait avec l'IA, et amélioré par lui-même
notabene a lui aussi été développé en grande partie avec l'IA. Sans l'usage intensif d'agents, je n'aurais jamais rencontré le problème que l'outil résout.
Il y a une deuxième boucle, à laquelle je tiens plus. La doc de notabene est écrite, relue et publiée avec notabene. J'écris la spec d'une fonctionnalité, je la relis dans le navigateur, je commente, l'agent applique, je valide les diffs. On code après.
C'est mon meilleur test. Chaque friction que je rencontre en annotant devient une issue. Le journal du projet est l'historique de ses propres corrections.
Pour qui ?
Si vos specs sont dans Confluence ou Notion, ça ne vous servira à rien. notabene ne lit que des fichiers Markdown versionnés.
Si elles sont déjà dans le repo, à côté du code, l'installation prend deux minutes. C'est un projet qui se veut simple dans sa mise en place et son fonctionnement, le but n'est pas d'alourdir le projet dans lequel il intervient.
Le code : github.com/z29k/notabene
La doc : z29k.github.io/notabene