docs / beta

Randnotizenbeta

Kommentiere jedes lokale Markdown-Dokument so, wie du einen Pull Request kommentierst — nur dass die Kommentare in der Datei selbst wohnen, als schlichte HTML-Kommentare, die im gerenderten Markdown nicht auftauchen. Gebaut für eine Schleife im Besonderen: Ein Agent schreibt dir ein Dokument, du liest es in PullMark und hinterlässt im Vorbeigehen Notizen, dann gibst du die Datei zurück mit „arbeite die Notizen ab und lösch sie dabei". Die Agenten-Seite geht die ganze Schleife durch, mit Screenshots und allem.

In PullMark benutzen

Liest du das auf dem Mac, auf dem PullMark (ab 0.28.1) installiert ist? Direkt zum Randnotizen-Schalter springen.

• Sie sind standardmäßig an — Randnotizen sind ein experimentelles Beta-Feature, das eingeschaltet ausgeliefert wird (seit 0.35). Beim ersten Griff danach — die Hover-Blase, ⌥⌘M oder Bearbeiten / Löschen an einer Notiz, die dir jemand hinterlassen hat — stellt PullMark das Feature vor: was Notizen sind, ein Copy-Knopf, um deinen Agenten anzulernen, und ein „Ausschalten“-Knopf, falls es nichts für dich ist. Der Schalter wohnt in Einstellungen → Experimentell und regelt nur die Werkzeuge zum Schreiben; ein Dokument, das schon Notizen enthält, zeigt seine Blasen so oder so (nur lesbar) — eine Datei, die ein Kollege oder ein Agent annotiert hat, rendert also nie stillschweigend leer.
• Eine Notiz anlegen — fahr über einen beliebigen Block in einem lokalen Dokument und klick die Blase am Rand (dieselbe Geste wie beim Kommentieren eines PRs). In einer Liste zielt die Blase auf den Punkt, auf den du zeigst, in einer Tabelle auf die Zeile — eine dezente Tönung zeigt genau, woran die Notiz hängen wird. Markier vorher Text und die Notiz öffnet mit der Auswahl als Zitat — so zeigst du auf einen Satz statt auf einen Absatz. ⌥⌘M notiert am Block, den du gerade liest; Bearbeiten → Randnotiz zur Datei… hinterlässt oben eine Notiz zum ganzen Dokument.
• Schreib Markdown — fett, Code-Spans, Code-Blöcke, Links, Listen; ⌘↩ speichert. Jedes Speichern ist eine Änderung in der Datei (rückgängig mit Ablage → Letzte Änderung zurücknehmen).
• Bearbeiten / Löschen — fahr über eine Notizblase für ihre Aktionen. Eine Notiz zu löschen ist, wie sie aufgelöst wird: kein Status, kein Archiv — eine abgearbeitete Notiz ist eine abwesende Notiz.
• Der Chip — Zeilen unter „Geöffnete Dateien“ zeigen einen Chip mit der Kommentarzahl, solange ein Dokument noch Notizen trägt. Er ist live: Während ein Agent die Datei durcharbeitet und Notizen löscht, fällt die Zahl und die Blasen verschwinden vor deinen Augen.
• Überall sonst — in durchstöberten GitHub-Dateien rendern Notizen nur lesbar, im Druck, im PDF-/HTML-Export und in Quick Look tauchen sie nie auf, und Darstellung → Randnotizen ausblenden räumt die Seite frei, wenn du sauber lesen willst.
• Deine Signatur — Notizen sind standardmäßig mit @dein-github-login signiert; ändern kannst du das beim eigenen Schalter des Features in Einstellungen → Experimentell.

Das Format

Eine Randnotiz ist ein HTML-Kommentar mit dem Schlüsselwort note und einem Autor-Tag, in einer eigenen Zeile nach dem Block, um den es geht:

Anfragen werden dreimal mit exponentiellem Backoff wiederholt.

<!-- note @josh: In Abschnitt 2 steht fünfmal. Was gilt? -->

Eine Notiz zu einem einzelnen Listenpunkt wohnt im Punkt selbst — eingerückt auf dessen Inhalt, dicht gepackt, damit die Liste ganz bleibt:

- Erster Punkt
  <!-- note @josh: zu vage — nenn die Kennzahl -->
- Zweiter Punkt

Längere Notizen setzen die schließende Marke in eine eigene Zeile; der Rumpf ist volles Markdown, Leerzeilen und Code-Blöcke eingeschlossen:

<!-- note @josh:
Das widerspricht dem Design-Dokument. Entweder in Einklang bringen
oder den Abschnitt streichen.

```suggestion
Anfragen werden fünfmal mit exponentiellem Backoff wiederholt.
```
-->

Die komplette Grammatik:

Weil Markdown-Renderer HTML-Kommentare überspringen, rendert eine Datei mit Notizen darin sauber auf GitHub, in Editoren und in jedem anderen Tool — die Notizen fahren im Quelltext mit, ohne die Seite vollzustellen. PullMark ist der hübsche Client für ein Format, das überall funktioniert.

Für Agenten

Die Übergabe braucht kein Protokoll: Agenten lesen Dateien, und die Notizen stehen in der Datei, physisch direkt neben dem Text, um den es geht. Füg das hier in dein CLAUDE.md / AGENTS.md ein — Einstellungen → Experimentell hat einen Copy-Knopf mit genau diesem (englischen) Text, oder sag es deinem Agenten einfach:

## 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.

Die Konvergenz-Schleife folgt aus dem Format: Übrige Blasen sind übrige Arbeit, und eine leere Datei ist ein fertiges Review. Sollen Notizen es nie bis in einen Pull Request schaffen, ist ein CI-Check eine Zeile — grep -rn '<!-- note @' docs/ && exit 1.

Warum beta

Die Mechanik hat sich bewährt — das Format brauchte seit dem Ausliefern keine inkompatible Änderung, und genau darum ist es aus alpha herausgewachsen. Nach dem Beta-Vertrag geben wir uns jetzt echte Mühe, Grammatik und Verhalten zwischen Versionen kompatibel zu halten, und das Feature wird wahrscheinlich ganz graduieren. Was sich noch setzt, ist die Oberfläche drumherum: Namen, Bedienelemente und wie weit der Workflow über die Agenten-Review-Schleife hinaus trägt, in der er entworfen wurde. Ändert sich doch etwas, sagen die Release Notes genau, was. Rückmeldungen willkommen.