het moment
Er is net een plan van 400 regels geland. En nu?
Je kent het ritueel: de agent rondt een plan af, en de volgende zet is aan jou. Ruwe Markdown lezen in een editor verbergt wat een lezer zou zien — tabellen, structuur, de vorm van het betoog. Stukken terugplakken in de chat rukt elk commentaar los van de plek waar het over gaat, en de agent moet raden waar jouw "dit klopt niet" naar wijst. En het ene gereedschap dat gebouwd is om op documenten te reageren — een pull request — wil eerst dat het concept gecommit, gepusht en in een browser gereviewd wordt.
Niet elk document hoort in een commit, en niet elke werkversie van een doc hoeft gepusht te worden.
Een werkversie verdient de feedbackloop die je een collega bij een whiteboard zou geven: wijs de alinea aan, zeg wat er mis is, geef het terug. Dat zijn margin notes.
de loop
Lees gerenderd. Noteer ter plekke. Geef het terug.
Open het concept in PullMark — of gewoon pullmark plan.md
vanuit de terminal waarin je agent draait. Tabellen zijn tabellen,
diagrammen zijn diagrammen, en de pagina rendert opnieuw telkens
wanneer het bestand verandert.
Beweeg over het blok dat niet klopt, klik op het notitieballonnetje en schrijf wat je een collega zou zeggen. Notities worden ondertekend met je @naam en verankerd aan de exacte passage — een notitie boven de titel gaat over het hele document.
Zeg tegen je agent: "verwerk mijn notities in plan.md." De notities staan in het bestand als gewone HTML-comments, dus de agent leest elke notitie precies waar jij die achterliet — past haar toe, beantwoordt haar, verwijdert haar.
Geen lock-in, per constructie. Een margin note is
<!-- note @you: … --> in de Markdown — een comment
die buiten de gerenderde pagina blijft. Je bestanden blijven platte
tekst, je notities reizen met het document mee, en alles wat het
bestand kan lezen kan de feedback lezen. De margin
notes-docs behandelen de details; de functie is in beta en staat
standaard aan.
Agents volgen de conventie beter met één alinea context. Dit is
dezelfde tekst als achter de Kopieer-knop in
Instellingen → Experimenteel — plak hem in het instructiebestand
van je agent (CLAUDE.md, AGENTS.md) of in het
gesprek:
## 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.
lange documenten
Notities die op je wachten.
Een grondige review van een lang document — een onderzoeksverslag, een complex ontwerpdocument — kan zo een uur duren. Margin notes zijn voor dat uur gebouwd. Het document houdt zich stil terwijl jij werkt: schrijf de gedachte op waar ze je invalt en lees verder. Doet pagina dertig je van gedachten veranderen over de notitie die je op pagina drie achterliet, dan ga je terug om die aan te scherpen — of te schrappen. Er bereikt je agent niets totdat de ronde af is en je notities het onderling eens zijn, zodat de feedback landt als één samenhangend geheel in plaats van een doorlopende stroom correcties.
Het loont zelfs voor documenten die uiteindelijk gecommit worden. Doe de ruwe eerste ronde in margin notes vóór de eerste commit, en de pull request opent schoon — reviewers zien het gesprek dat ertoe doet, niet de steigers die nodig waren om er te komen.
de revisie
Zie de wijzigingen landen.
Terwijl de agent je notities afwerkt, blijft PullMark bij. De pagina
rendert opnieuw bij elke save, en Vergelijk toont de
revisie als gerenderde diff — de wijzigingen van de agent woord voor
woord gemarkeerd, live terwijl ze landen. Eén klik vergelijkt het
werkbestand met elke recente commit of branch;
pullmark --diff plan.md doet het vanuit de terminal. Het is
het snelste antwoord op "wat heeft de agent net aan mijn doc
veranderd?" — en zijn de notities verwerkt, dan zijn ze gewoon uit
het bestand verdwenen.
als het wél een PR is
En als het document wél ter review gaat…
Sommige documenten horen wél gecommit te worden — en repo's vol agents vullen pull requests met Markdown: plannen, ADR's, agentdefinities, runbooks. PullMark toont die PR's als gerenderde diffs met alleen de gewijzigde woorden gemarkeerd, laat je op precies de juiste blokken reageren en suggesties doen, en dient je review in bij GitHub. Het overzicht weet waar de PR staat: beslissing, oordelen van reviewers, checks, en de conversatie als leesbare tijdlijn.
Maak de cirkel rond met je agent.
Gratis, open source, ondertekend en genotariseerd. macOS 13+.
$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmarkDe nieuwste DMG — open hem en sleep PullMark naar Applications (het opruimen doet PullMark zelf). Alle releases →
Hoe dan ook: PullMark controleert op updates en installeert ze met één klik.