Ein Agent annotiert meine Screenshots für die Dokumentation
- Die Frage
- Kann ich einem Agenten einen Ordner mit namenlosen Screenshots geben, damit er analysiert, was sie zeigen, und mir die annotierten Abbildungen für eine Dokumentationsseite erstellt?
- Ergebnis
- Ja, das Lesen und Zeichnen funktioniert. Die Platzierung der Bildunterschrift bleibt eine Ermessensentscheidung und hängt davon ab, ob die Benutzeroberfläche genügend Weißraum bietet.
Was ich herausfinden wollte
Wenn ich Dokumentationen schreibe, erstelle ich währenddessen Screenshots, die mit Namen wie Screenshot 2026-09-14 at 18.03.12.png auf meinem Desktop landen. Dann beginnt der mühsame Teil: jedes Bild öffnen, zuordnen, welchem Schritt es angehört, zuschneiden, eine Box um die Schaltfläche zeichnen und die Bildunterschrift so platzieren, dass sie das beschriebene Element nicht verdeckt.
Die Frage war, ob ich das alles überspringen kann. Dem Agenten den Ordner übergeben, die Bilder analysieren lassen, um zu verstehen, worüber er überhaupt schreibt, Unterstützung beim Text erhalten und dann die markierten Abbildungen erstellen lassen. Kein Figma, kein Hin und Her bei der Platzierung einer Box.
Ich hatte erwartet, dass das Zeichnen schwierig wird. Das erwies sich als falsch.
Wie es getestet wurde
Eine Annotation ist ein JavaScript-Modul, keine Zeichnung. Es definiert ein Quellbild und eine Liste von Formen in Prozentwerten des Rahmens. Ein Renderer legt diese in Chrome über den Screenshot und fotografiert die Seite mit Playwright erneut ab.
Chrome ist der entscheidende Trick. Abgerundete Ecken, Schatten, Textrendering und Unschärfe werden vom Browser übernommen, sodass nichts neu implementiert werden muss. Das Ergebnis ist eine PNG-Datei in der exakten Dimension der Quelle.
- 1Capture importierenEgal, wie das Screenshot-Tool es genannt hat
- 2Grid rendernEin Prozent-Overlay über dem Bild
- 3Koordinaten lesenEinmal ansehen, aufschreiben
- 4Spec schreibenEine JS-Datei: Boxen, Pfeile, Notizen, Zuschnitte
- 5RendernChrome setzt zusammen, Playwright fotografiert
In Schritt drei wäre das Experiment fast gescheitert. Wenn man den Agenten bittet, eine Box per Auge um eine Schaltfläche zu platzieren, liegt er etwa 2 % daneben. Auf dem Papier klingt das wenig, im Bild ist es offensichtlich. Die Lösung besteht darin, nicht mehr zu schätzen: Zuerst wird ein Prozent-Grid über das Bild gelegt, der Agent liest die Zahlen dieses Grids einmal ab, und jede nachfolgende Box landet exakt auf dem Pixel.
Sechs Primitiven decken alles ab, was eine Dokumentationsabbildung benötigt.
| Primitiv | Funktion |
|---|---|
box | Der abgerundete Rahmen mit Halo, optional mit Nummer und Bildunterschrift |
arrow | Ein gebogener Pfeil, punktorientiert, für ein einzelnes “Klicken Sie hier” |
note | Eine Textkarte: Titel und eine Zeile Fließtext |
spotlight | Verdunkelt alles außer den ausgeschnittenen Bereichen |
zoom | Eine Lupe: ein vergrößerter Ausschnitt, platziert in einem freien Bereich |
redact | Macht eine Region unscharf |
Das Ergebnis
Das Lesen der Screenshots funktioniert. Trotz fehlender nützlicher Dateinamen identifizierte der Agent, welches Produkt jeder Capture zeigt, welchen Bildschirm es darstellt und welcher Capture welchen Schritt illustriert, gut genug, um den Text darum herum zu entwerfen.
Das Zeichnen funktioniert ebenfalls und ist schnell: Da die Spec aus Code besteht, wird ein nach einer UI-Änderung neu aufgenommener Screenshot durch das Ausführen eines einzigen Befehls neu annotiert, solange sich nichts um mehr als etwa 1 % verschoben hat.
Der Teil, der sich nicht in einen Befehl reduzieren lässt, ist die Platzierung der Bildunterschrift. Diese wird durch den Screenshot und nicht durch das Tool bestimmt.
Die daraus resultierende Regel: Wenn die Oberfläche keinen Weißraum hat, wandert die Bildunterschrift aus dem Bild. Ein nummeriertes Badge im Screenshot und eine nummerierte Liste im Text, oder ein Zuschnitt, der den Raum erst schafft. Das ist keine Präferenz, sondern lässt sich aus dem Screenshot ablesen, bevor überhaupt gezeichnet wird.
Die Lupe ist das einzige Primitiv, das sich als unverzichtbar und nicht bloß dekorativ erwiesen hat.
Die Erkenntnis, die eigentlich nicht das Ziel war
Die Annotation von zwei echten Produkt-Captures brachte Dinge ans Licht, die das Unternehmen nicht verlassen sollten. Ein Screenshot eines Workflow-Editors zeigte einen API-Key im Klartext innerhalb einer Verzweigungsbedingung. Ein anderer zeigte eine Seitenleiste mit Titeln privater Konversationen.
Beides wurde bei der Aufnahme nicht bemerkt. Beides wurde offensichtlich, in dem Moment, als etwas das Bild Element für Element durchging und fragte, was jedes einzelne sei.
Mein Fazit
Das Zeichnen der Box ist mechanisch. Die Platzierung der Bildunterschrift ist die eigentliche Arbeit. Jedes Mal, wenn dies eine schlechte Abbildung ergab, lag eine Bildunterschrift über dem benannten Element, und das lag immer daran, dass die Oberfläche keine Lücke bot. Das ist eine Layout-Entscheidung über den Screenshot und das Teil, das nicht zum Befehl wurde.
Eine Spec-Datei schlägt für diesen Zweck eine Design-Datei. Die Abbildungen sind Code. Ein nächsten Monat neu aufgenommener Screenshot wird mit einem Befehl neu annotiert, statt ihn erneut zu öffnen und neu zu zeichnen. Der Preis dafür ist, dass die erste Version jeder Abbildung schlechter ist als eine handgezeichnete und ein oder zwei Durchgänge braucht, um optimal zu sein.
Ein Annotations-Durchgang ist ein versehentlicher Privacy-Review. Niemand hatte vor, diese Captures zu prüfen. Erst das genaue Betrachten jeder Region, um sie zu beschreiben, brachte den Key und die Konversationstitel zutage. Das ist ein Grund, diesen Durchgang vor der Veröffentlichung zu machen und nicht danach.
Eine Unschärfe ist keine Schwärzung. Der Renderer weichzeichnet mit einem Backdrop-Filter, und eine 14px-Unschärfe über einem 13px-Text ist unlesbar, aber nicht nachweislich unwiederbringlich. Für wirklich geheime Daten ist die Lösung ein solider Block, weshalb die zwei Captures, die einen solchen enthalten, hier beschrieben, aber nicht gezeigt werden.