der Moment
Ein Plan mit 400 Zeilen ist gerade gelandet. Und jetzt?
Du kennst das: Der Agent stellt einen Plan fertig, und der nächste Zug ist deiner. Rohes Markdown im Editor zu lesen versteckt, was ein Leser sehen würde — Tabellen, Struktur, die Form des Arguments. Häppchen zurück in den Chat zu kopieren reißt jeden Kommentar von der Stelle, um die es geht, und der Agent muss raten, worauf dein „das hier stimmt nicht" zeigt. Und das eine Werkzeug, das fürs Kommentieren von Dokumenten gebaut ist — ein Pull Request — will den Entwurf erst committet, gepusht und im Browser reviewt sehen.
Nicht jedes Dokument gehört committet, und nicht jeder Arbeitsstand eines Docs gehört gepusht.
Ein Arbeitsentwurf braucht die Feedback-Schleife, die du einem Kollegen am Whiteboard geben würdest: auf den Absatz zeigen, sagen, was nicht stimmt, zurückgeben. Genau das sind Randnotizen.
der Loop
Gerendert lesen. Vor Ort notieren. Zurückgeben.
Öffne den Entwurf in PullMark — oder einfach pullmark plan.md
aus dem Terminal, in dem dein Agent läuft. Tabellen sind Tabellen, Diagramme
sind Diagramme, und die Seite rendert neu, sooft sich die Datei ändert.
Fahr über den Block, der nicht stimmt, klick die Notiz-Sprechblase und schreib, was du einem Kollegen sagen würdest. Notizen sind mit deinem @Namen signiert und an genau der Passage verankert — eine Notiz über dem Titel gilt dem ganzen Dokument.
Sag deinem Agenten: „geh meine Notizen in plan.md durch." Die Notizen leben als gewöhnliche HTML-Kommentare in der Datei — der Agent liest also jede genau dort, wo du sie hinterlassen hast: setzt sie um, beantwortet sie, löscht sie.
Kein Lock-in, per Konstruktion. Eine Randnotiz ist
<!-- note @you: … --> im Markdown — ein Kommentar, der aus
der gerenderten Seite herausbleibt. Deine Dateien bleiben reiner Text, deine
Notizen reisen mit dem Dokument, und alles, was die Datei lesen kann, kann
auch das Feedback lesen. Die Randnotizen-Doku
erklärt die Mechanik; das Feature ist in der Beta und standardmäßig an.
Agents befolgen die Konvention besser mit einem Absatz Kontext. Das hier
ist derselbe Text wie hinter dem Copy-Button in
Einstellungen → Experimentell — füg ihn in die Instruktionsdatei deines
Agenten ein (CLAUDE.md, AGENTS.md) oder in die
Unterhaltung:
## 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 Dokumente
Notizen, die auf dich warten.
Ein gründliches Review eines langen Dokuments — eine Recherche-Zusammenfassung, ein komplexes Design-Doc — kann eine Stunde dauern. Randnotizen sind für diese Stunde gebaut. Das Dokument hält still, während du arbeitest: Schreib den Gedanken dort auf, wo er dich trifft, und lies weiter. Wenn Seite dreißig deine Meinung über die Notiz von Seite drei ändert, geh zurück und schärfe sie — oder lösch sie. Nichts erreicht deinen Agenten, bevor der Durchgang fertig ist und deine Notizen zueinander passen — das Feedback landet als ein stimmiges Ganzes statt als laufender Strom von Korrekturen.
Das lohnt sich selbst für Dokumente, die am Ende committet werden. Mach den groben ersten Durchgang in Randnotizen, bevor der erste Commit passiert, und der Pull Request startet sauber — Reviewer sehen die Unterhaltung, die zählt, nicht das Gerüst, das nötig war, um dorthin zu kommen.
die Überarbeitung
Sieh zu, wie die Änderungen landen.
Während der Agent deine Notizen abarbeitet, bleibt PullMark dran. Die
Seite rendert bei jedem Speichern neu, und Vergleichen
zeigt die Überarbeitung als gerendertes Diff — die Änderungen
des Agenten Wort für Wort hervorgehoben, live, während sie landen. Ein Klick
vergleicht die Arbeitsdatei mit jedem letzten Commit oder Branch;
pullmark --diff plan.md macht es vom Terminal aus. Es ist die
schnellste Antwort auf „Was hat der Agent gerade an meinem Doc
geändert?" — und sind die Notizen abgearbeitet, sind sie einfach weg
aus der Datei.
wenn es doch ein PR ist
Und wenn das Doc doch ins Review geht …
Manche Dokumente gehören committet — und agentenlastige Repos füllen Pull Requests mit Markdown: Pläne, ADRs, Agent-Definitionen, Runbooks. PullMark zeigt diese PRs als gerenderte Diffs, in denen nur die geänderten Wörter hervorgehoben sind, lässt dich an genau den Blöcken kommentieren und Vorschläge machen und reicht dein Review bei GitHub ein. Die Übersicht weiß, wo der PR steht: Entscheidung, Reviewer-Urteile, Checks und die Unterhaltung als lesbare Timeline.
Schließ den Loop mit deinem Agenten.
Kostenlos, Open Source, signiert und notarisiert. macOS 13+.
$ brew tap jedijashwa/tap
$ brew trust jedijashwa/tap
$ brew install --cask pullmarkDas aktuelle DMG — öffnen, nach „Programme" ziehen (PullMark räumt hinterher auf). Alle Releases →
So oder so: PullMark prüft auf Updates und installiert sie mit einem Klick.