le moment
Un plan de 400 lignes vient d'atterrir. Et maintenant ?
Vous connaissez la chanson : l'agent termine un plan, et le coup suivant vous revient. Lire le Markdown brut dans un éditeur cache ce qu'un lecteur verrait — les tableaux, la structure, la forme de l'argument. Recoller des extraits dans la conversation coupe chaque commentaire de l'endroit qu'il vise, et l'agent doit deviner où pointe votre « cette partie est fausse ». Quant au seul outil conçu pour commenter des documents — la pull request — il exige d'abord un brouillon commité, poussé et révisé dans un navigateur.
Tout document n'a pas vocation à être commité, et toute version de travail d'une doc n'a pas à être poussée.
Un brouillon de travail réclame la boucle de retour que vous offririez à un collègue devant un tableau blanc : montrer le paragraphe, dire ce qui cloche, rendre la copie. C'est exactement ça, les notes de marge.
la boucle
Lisez rendu. Notez sur place. Rendez la main.
Ouvrez le brouillon dans PullMark — ou simplement pullmark plan.md
depuis le terminal où tourne votre agent. Les tableaux sont des tableaux, les
diagrammes des diagrammes, et la page se réaffiche à chaque changement du
fichier.
Survolez le bloc fautif, cliquez la bulle de note, écrivez ce que vous diriez à un collègue. Les notes sont signées de votre @nom et ancrées au passage exact — une note au-dessus du titre porte sur tout le document.
Dites à votre agent : « traite mes notes dans plan.md ». Les notes vivent dans le fichier comme de simples commentaires HTML : l'agent lit chacune exactement là où vous l'avez laissée — l'applique, y répond, la supprime.
Aucun verrouillage, par construction. Une note de marge, c'est
<!-- note @you: … --> dans le Markdown — un commentaire qui
reste hors de la page rendue. Vos fichiers restent du texte brut, vos notes
voyagent avec le document, et tout ce qui sait lire le fichier sait lire le
retour. La doc des notes de
marge en couvre la mécanique ; la fonctionnalité est en bêta, activée
par défaut.
Les agents suivent mieux la convention avec un paragraphe de contexte. C'est le
texte même du bouton Copier de
Réglages → Expérimental — collez-le dans le fichier d'instructions de
votre agent (CLAUDE.md, AGENTS.md) ou dans la
conversation :
## Margin notes Markdown files may contain review notes as HTML comments: `<!-- note @name: comment -->` (possibly multi-line, closing with `-->` on its own line). Each note sits directly after the passage it's about; a note above the first heading is about the whole document. `--\>` inside a note means a literal `-->`. When asked to address notes: work through each one, apply or answer it, and DELETE the note (with its surrounding blank line) once addressed. To reply or ask instead, leave your own note in the same format below the original, signed with your own @name. Don't add notes to code examples inside fenced blocks. A note about one list item sits inside that item — directly after the item's last line, indented to the item's content, with no blank lines around it. Keep (or delete) the whole indented comment; its indentation is what ties it to the item.
documents longs
Des notes qui vous attendent.
La relecture sérieuse d'un long document — une synthèse de recherche, une doc de conception complexe — peut prendre une heure. Les notes de marge sont faites pour cette heure-là. Le document ne bouge pas pendant que vous travaillez : écrivez l'idée là où elle surgit et continuez de lire. Quand la page trente vous fait changer d'avis sur la note laissée en page trois, revenez l'affûter — ou la supprimer. Rien n'atteint votre agent avant que la passe soit finie et que vos notes s'accordent entre elles : le retour arrive comme un ensemble cohérent, pas comme un flot continu de corrections.
Le procédé se rend utile même pour les documents qui finiront commités. Faites la première passe, la plus rugueuse, en notes de marge avant le premier commit : la pull request s'ouvre propre — les réviseurs voient la conversation qui compte, pas l'échafaudage qu'il a fallu pour y arriver.
la nouvelle version
Regardez les modifications atterrir.
Pendant que l'agent traite vos notes, PullMark suit le rythme. La page se
réaffiche à chaque enregistrement, et Comparer montre
la nouvelle version en diff rendu — les modifications de l'agent surlignées mot à
mot, en direct au fur et à mesure. Un clic compare le fichier de travail à
n'importe quel commit ou branche récents ;
pullmark --diff plan.md le fait depuis le terminal. C'est la réponse
la plus rapide à « qu'est-ce que l'agent vient de changer dans ma
doc ? » — et une fois les notes traitées, elles ont simplement disparu
du fichier.
quand c'est une PR
Et quand la doc part bel et bien en révision…
Certains documents ont bel et bien vocation à être commités — et les dépôts où les agents abondent remplissent les pull requests de Markdown : plans, ADR, définitions d'agents, runbooks. PullMark montre ces PR en diffs rendus où seuls les mots modifiés sont surlignés, vous laisse commenter et suggérer sur les blocs exacts, et envoie votre révision à GitHub. La vue d'ensemble sait où en est la PR : décision, verdicts des réviseurs, checks, et la conversation en chronologie lisible.
Bouclez la boucle avec votre agent.
Gratuite, open source, signée et notarisée. macOS 13+.
$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmarkLe dernier DMG — ouvrez-le, glissez vers Applications (PullMark se charge du nettoyage). Toutes les versions →
Dans les deux cas, PullMark vérifie les mises à jour et les installe en un clic.