CommunityCodierung & Entwicklunggithub.com

Merge-Request-Annotationen

Kommentiere einen Merge-Request / Pull-Request mit erklärenden Hinweisen für Reviewer zu KI-erstellten Änderungen – mit Absicht, Vorher/Nachher-Verhalten und einem verifizierten Einstiegspunktgraphen – als einen Übersichtskommentar, einen Dateikommentar pro geänderter Datei und Inline-Kommentare nur an wirklich unklaren Stellen – alles nach jedem Push aktuell gehalten.

Was ist Merge-Request-Annotationen?

Diese Fähigkeit (Skill) erstellt automatisch mehrschichtige Annotationen für Merge-Requests (MRs) / Pull-Requests (PRs), die von KI generierte Codeänderungen für menschliche Reviewer verständlich machen. Sie generiert drei Ebenen: einen Übersichtskommentar auf MR-Ebene, einen Dateikommentar pro geänderter Datei (außer bei automatisch generierten Dateien) und sparsame Inline-Kommentare nur an wirklich nicht offensichtlichen Stellen. Die Annotationen umfassen die Absicht der Änderung, das Vorher-/Nachher-Verhalten und einen verifizierten Einstiegspunktgraphen, der mithilfe von `rg`-Suchen im Repository erstellt wird, um Kontrollflussbehauptungen zu bestätigen. Der Skill unterstützt GitLab, GitHub und Bitbucket, führt einen Trockenlauf (Preview) durch und postet erst nach Benutzerfreigabe. Ein Synchronisationsmodus (`sync`) aktualisiert Annotationen nach jedem Push, ohne Duplikate zu erzeugen, indem er vorherige Kommentare anhand von HTML-Markern identifiziert. Der Skill enthält zwei Python-Skripte (`diff_inventory.py` und `sync_state.py`), die die Änderungsbestandsaufnahme und den Abgleich der Annotationen übernehmen. Die Annotationen sind mit Budgets versehen (maximal 3 Inline-Kommentare pro Datei, maximal 12 pro MR), um eine Überfrachtung zu vermeiden. Der Skill setzt Cross-Referenzen zwischen Kommentaren in zwei Phasen um: Erstellen mit Platzhaltern, dann Ersetzen durch echte URLs nach dem Posten.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kirill-kolomin/self-descriptive-merge-requests/tree/main/skills/annotate-merge-request

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Einen Merge-Request für Reviewer annotieren

Ein Reviewer, der einen KI-generierten Diff liest, verbringt die meiste Zeit damit, drei Dinge zu rekonstruieren, die der Autor bereits wusste: warum diese Änderung existiert, welches Verhalten sich geändert hat und wer diesen Code aufruft. Dieser Skill schreibt diese drei Dinge in einfacher Sprache auf der Ebene des Merge-Requests auf – nicht als Source-Code-Kommentare.

Die Annotationen bestehen aus drei Ebenen mit unterschiedlichen Regeln:

EbeneAbdeckungEnthält
Übersicht – ein MR-weiter Kommentarimmerdie Karte der gesamten Änderung
Datei – ein Kommentar pro geänderter Dateiimmer, außer bei automatisch generierten Dateienwas die Änderung in dieser Datei bedeutet
Inline – an eine Diff-Zeile angeheftetnur an wirklich nicht offensichtlichen Stellen, begrenztwarum dieser bestimmte Code so ist, wie er ist

Die Dateiabdeckung ist bedingungslos: Ein Reviewer, der eine beliebige Datei im Diff öffnet, muss eine Erklärung dafür finden. Die Ermessensentscheidung – was erklärenswert ist und was offensichtlich – gilt innerhalb einer Datei für Methoden und einzelne Hunk-Abschnitte, niemals dafür, ob die Datei überhaupt abgedeckt wird.

Betriebsmodi

ModusWannWas er tut
annotateErster Durchlauf auf einem MRErstellt das vollständige Annotationsset, zeigt eine Vorschau an und veröffentlicht es nach Freigabe
syncNach jedem Push auf den MR-BranchÜberprüft vorhandene Annotationen auf den neuen Diff; aktualisiert, entfernt oder fügt nur hinzu, was sich geändert hat

Wenn bereits Annotationen dieses Skills auf dem MR vorhanden sind (erkennbar am Marker, siehe §7), führe sync aus, nicht annotate – ein erneutes Ausführen von annotate würde Kommentare duplizieren.

1. Vorbereitung

Stelle vor dem Schreiben Folgendes fest:

  1. Plattform und MR-Identität. git remote -v → gitlab.com/self-hosted GitLab, github.com oder Bitbucket. Finde dann den offenen MR für den aktuellen Branch (glab mr view, gh pr view). Wenn es noch keinen MR gibt, stoppe und teile dies mit – dieser Skill annotiert einen bestehenden MR, er erstellt keinen.
  2. Diff-Bereich. Immer git merge-base HEAD origin/<target-branch> → <base>..HEAD. Vergleiche niemals mit der nackten Spitze des Zielbranches: Nicht zusammenhängende Commits, die auf dem Ziel gelandet sind, würden als Änderungen dieses MRs erscheinen.
  3. Sprache. Schreibe Annotationen in der Sprache, die die MRs des Projekts bereits verwenden (überprüfe vorhandene MR/PR-Beschreibungen und -Kommentare). Standardmäßig verwende die Sprache, in der der Benutzer mit dir spricht.
  4. Berechtigung zum Posten. Das Posten auf einem MR ist für das gesamte Team sichtbar und benachrichtigt Reviewer. Standardmäßig zeige eine Trockenlauf-Vorschau im Gespräch an und veröffentliche erst nach Freigabe durch den Benutzer. Überspringe die Vorschau nur, wenn der Benutzer bereits gesagt hat, ohne Nachfrage zu posten.

Lies references/platform-gitlab.md, references/platform-github.md oder references/platform-bitbucket.md für die genauen Befehle – die Kommentar-APIs unterscheiden sich in wesentlichen Punkten (dateiebene Verankerung, Auflösbarkeit, Aktualisierungssemantik).

2. Erstelle das Änderungsinventar

Die beiden Skripte befinden sich neben dieser Datei im Verzeichnis scripts/. Rufe sie mit absolutem Pfad auf, der aus dem eigenen Verzeichnis dieses Skills ermittelt wird – das Arbeitsverzeichnis während eines Durchlaufs ist das Repository des Benutzers, nicht der Skill, daher würde ein bloßer Pfad scripts/... fehlschlagen. Unten steht $SKILL für das Verzeichnis, das diese SKILL.md enthält (z.B. ~/.claude/skills/annotate-merge-request für eine Installation auf Benutzerebene oder skills/annotate-merge-request des Plugins, wenn aus einem Plugin geladen).

python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json

Pro geänderter Datei liefert dies: Änderungsart (hinzugefügt/geändert/gelöscht/umbenannt), requires_file_comment (nur bei automatisch generierten/ausgelagerten Dateien false), einen file_fingerprint und die Hunks der Datei mit neuen Zeilennummern (an die Inline-Kommentare verankern müssen), dem nächstgelegenen umschließenden Symbol und Trivialitätssignalen. Bei Spezifikations- und Testdateien gibt es außerdem test_cases aus – jeder Fall in der Datei mit seinem Status (unchanged / adapted / added / removed), berechnet durch Vergleich der Fallkörper zwischen den beiden Revisionen, nicht direkt aus dem Diff ausgelesen. Es handelt sich um eine heuristische Karte für deine Lektüre, nicht um einen Ersatz dafür – lies den tatsächlichen Diff für alles, was du beschreiben wirst.

Der anchor jedes Hunks ist ein Vorschlag (seine erste hinzugefügte Zeile); added_lines listet jede Zeile in diesem Hunk auf, an die du stattdessen verankern könntest. Wähle die Zeile aus, um die es in der Erklärung tatsächlich geht.

Harte Einschränkung: Ein Inline-Kommentar kann nur an einer Zeile verankert werden, die im Diff erscheint. Weder GitLab noch GitHub erlauben Kommentare zu unberührtem Code weit entfernt von einem Hunk. Alles, was du zu Code sagen möchtest, den der MR nicht berührt hat, gehört in den Datei- oder Übersichtskommentar, niemals inline.

3. Ebene 1 – decke jede geänderte Datei ab

Jede Datei, die das Inventar mit requires_file_comment: true markiert, erhält genau einen Kommentar auf Dateiebene. Keine Ausnahmen, kein Budget, keine Ermessensentscheidung, ob sie „interessant genug“ ist.

Die einzige Ausnahme sind automatisch generierte und ausgelagerte Ausgaben – Lockfiles, dist/, Snapshots, Codegenerierung, minifizierte Bundles, vendor/. Das Inventar kennzeichnet diese; wenn es eine übersieht, die dein Projekt generiert, nimm sie ebenfalls aus und teile dem Benutzer mit, welches Muster hinzugefügt werden soll.

Variabel sind Form und Länge, nicht die Existenz:

  • Eine Datei mit echten Logikänderungen erhält die vollständige Vorlage (references/annotation-format.md): Rolle, warum sie geändert wurde, vorher → nachher, von wo aus sie erreicht wird.
  • Eine Spezifikations- oder Testdatei erhält stattdessen eine Testfall-Liste – jeder Fall, den sie jetzt enthält, jeweils mit einem Status (unchanged / adapted / added / removed) und, für die geänderten, einer kurzen Beschreibung. Die Standardvorlage ist für Spezifikationen falsch: Nichts ruft sie auf, daher ist der Abschnitt zum Einstiegspunkt von Natur aus leer. Das Inventar berechnet die Status für dich (test_cases pro Datei); adapted-Fälle sind diejenigen, die ein Reviewer am meisten braucht, also kommen sie zuerst und müssen angeben, ob sich die Aufrufform oder die Erwartung geändert hat. Vollständige Regeln in references/annotation-format.md.
  • Eine mechanische Datei erhält eine Zeile, die es dem Reviewer ermöglicht, sie getrost zu überspringen: Nur Importpfade - folgt der Umbenennung von PricingService; keine Verhaltensänderung.
  • Eine gelöschte Datei erhält eine Zeile, warum sie entfernt wurde und was sie ersetzt hat – oft die nützlichste Annotation in einem MR.

Verankere diese als Kommentare auf Dateiebene (subject_type=file auf GitHub, position_type=file auf GitLab), nicht auf einer Zeile. Sie werden am Dateikopf angehängt, sodass sie sich nicht mit Code vermischen und der Reviewer sie beim Öffnen jeder Datei vorfindet. Wenn eine Instanz keine Verankerung auf Dateiebene unterstützt, falle auf die erste geänderte Zeile der Datei zurück – die Plattformreferenzen geben das genaue Fallback an.

Das Schreiben von Einzeilern ist hier die ganze Kunst. Der Umfang skaliert jetzt mit der Dateianzahl, daher ist eine mechanische Datei, die in drei Absätzen beschrieben wird, ein Fehler, nicht Gründlichkeit.

4. Ebene 2 – der Übersichtskommentar

Ein Kommentar auf MR-Ebene, der Einstiegspunkt für die gesamte Überprüfung, genau wie in references/annotation-format.md spezifiziert:

  • Absicht – welches Problem dieser MR löst, in zwei oder drei Sätzen, in einfacher Sprache. Kein Wiederholen des Diffs.
  • Vorher → Nachher-Verhalten – was ein Beobachter des laufenden Systems bemerken würde. Für eine neue Komponente sage „neu“, anstatt ein „vorher“ zu erfinden.
  • Einstiegspunktgraph – wie ein Leser den geänderten Code von einem echten Einstiegspunkt aus erreicht (HTTP-Route, CLI-Befehl, Event-Handler, Cron, exportierte API). Begrenzt auf 3 Ebenen; eine Zeile pro geändertem Bereich, nicht pro Datei.
  • Lesereihenfolge – welche Datei zuerst geöffnet werden sollte, welche mechanisch sind.
  • Index der Inline-Kommentare – Links zu jeder Inline-Annotation.

Die Übersicht hat ihre eigenen Volumenbegrenzungen (maximal 7 Einträge in der Lesereihenfolge, maximal 5 Verhaltenszeilen, keine Auflistung pro Datei – das erledigen die Dateikommentare). Sie stehen in references/annotation-format.md; respektiere sie, sonst wird die Übersicht zu einer Textwand, die die Dateikommentare verhindern sollten.

Den Einstiegspunktgraph überprüfen

Rate niemals einen Aufrufgraphen. Eine erfundene Aufruferliste ist schlimmer als keine Annotation: Sie ist mit Überzeugung falsch, und der Reviewer wird ihr vertrauen. Suche für jede behauptete Kante den Aufrufer mit einer tatsächlichen Suche (rg -n 'symbolName' im gesamten Repository, einschließlich Tests und Konfiguration) und folge ihm nach oben, bis du einen Einstiegspunkt oder 3 Ebenen erreichst, je nachdem, was zuerst eintritt. Wenn die Aufrufer eines Symbols nicht aufgelöst werden können – dynamischer Dispatch, DI-Container, Reflection, ein string-keyed Registry – schreibe Einstiegspunkt nicht aufgelöst (<Grund>) anstatt einer plausibel klingenden Kette.

5. Ebene 3 – Inline-Kommentare, nur wo der Code nicht offensichtlich ist

Dies ist die einzige Ebene mit einer Ermessensentscheidung. Führe den Signifikanztest aus references/significance-test.md für jede Methode und jeden Hunk durch. Die Kurzversion:

Annotiere, wenn der Leser vernünftigerweise fragen könnte: „Warum ist das so?“ – nicht offensichtliche Absicht, eine Verhaltensänderung, die im Diff nicht sichtbar ist, eine nicht-lokale Konsequenz, ein bewusster Kompromiss, ein ungewöhnlicher Algorithmus, eine Problemumgehung, eine Einschränkung von außerhalb der Datei oder eine Interaktion mit einer anderen Änderung in diesem selben MR.

Überspringe, wenn der Code sich für einen kompetenten Leser dieser Codebasis selbst erklärt: ein 5-10-zeiliger Helfer, der einen String in Titelform bringt, eine DEBOUNCE_MS = 300-Konstante, eine offensichtliche Null-Prüfung, eine mechanische Testaktualisierung. Der Dateikommentar deckt die Datei bereits ab; ein Inline-Kommentar würde ihn hier mit geringerem Wert wiederholen.

Die Größe des Codes ist nicht der Test – seine inferentielle Distanz ist es. Ein 6-zeiliger Helfer innerhalb eines benutzerdefinierten Kodierungsschemas benötigt einen Kommentar; eine 200-zeilige generierte Snapshot-Datei nicht.

Budgets (Standardeinstellungen; der Benutzer kann sie explizit erhöhen):

  • Maximal 3 Inline-Kommentare pro Datei, maximal 12 pro MR.
  • Dies sind Obergrenzen, keine Quoten. Eine Datei, deren Geschichte vollständig durch ihren Dateikommentar erzählt wird, erhält null Inline-Kommentare, und das ist der Normalfall.
  • Das Überschreiten eines Budgets ist ein Signal, keine Lizenz: Wenn mehr als 12 Stellen in einem MR wirklich nicht offensichtlich sind, ist der MR zu groß oder die Erklärung gehört in die Übersicht, wo sie als eine Geschichte erzählt werden kann. Sage das dem Benutzer.

Jede Inline-Annotation verwendet dieselben Abschnitte wie der Dateikommentar, eingegrenzt auf diesen Hunk, und bleibt kurz – 3 bis 6 Zeilen, gelesen in einer engen Diff-Ansicht.

6. Querverweise innerhalb des MRs

Wenn eine Änderung nur zusammen mit einer anderen Änderung im selben MR Sinn ergibt, verlinke sie. Querverweise gehören normalerweise in den Einstiegspunktgraphen, erscheinen aber auch in der Absicht („notwendig, weil jetzt X übergibt“) und im Vorher/Nachher („der alte Pfad existiert noch, siehe “). Dateikommentare sind der natürlichste Ort dafür: Der neue Vertrag dieser Datei wird von [[ref:order-controller]] konsumiert.

Eine Kommentar-URL existiert nicht, bis der Kommentar veröffentlicht ist, daher erfolgt die Querverlinkung in zwei Phasen:

  1. Veröffentliche jeden Kommentar mit einem Platzhalter-Token ([[ref:<slug>]]), wo ein Link zu einer anderen Annotation hingehört.
  2. Sammle die IDs/URLs der erstellten Kommentare, bearbeite dann jeden Text und ersetze die Token durch echte Links.

Plane die Slugs vor dem Veröffentlichen – jedes [[ref:...]]-Token muss in Phase 2 aufgelöst werden, und ein übrig gebliebenes Token in einem veröffentlichten Kommentar ist ein sichtbarer Fehler. Phase 2 ist nicht optional.

7. Veröffentlichen mit einem Identitätsmarker

Jeder Kommentar, den dieser Skill erstellt, endet mit einer Markerzeile, die im gerenderten Markdown unsichtbar ist:

<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<datei> ffp=<datei-fingerprint> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<datei>@<neue-zeile> fp=<hunk-fingerprint> -->

Verwende den file_fingerprint aus dem Inventar für ffp= und den fingerprint des Hunks für fp=. Der Marker ist das, was sync möglich macht: Er identifiziert die eigenen Kommentare des Skills, woran jeder angehängt war und den Fingerprint des Codes, den er beschrieben hat. Veröffentliche niemals eine Annotation ohne einen; bearbeite niemals den Kommentar eines Menschen.

Hinterlasse Annotationen unaufgelöst. Ein aufgelöster Thread wird zusammengeklappt dargestellt, sodass der Reviewer jede Annotation einzeln erweitern müsste – was genau das verbirgt, was die Annotation zeigen soll. Veröffentliche sie offen und lasse den Reviewer jede einzelne auflösen, während er sie liest; dieser Klick ist sein eigener „gelesen“-Marker.

Die Kosten dieser Wahl: Wo das Projekt erfordert, dass alle Threads vor dem Mergen aufgelöst sind (GitLabs Alle Threads müssen aufgelöst sein, GitHub's Unterhaltungsauflösung erforderlich), müssen die Annotationen aufgelöst sein, bevor der Merge-Button freigegeben wird. Bei einem Dateikommentar pro Datei ist das eine echte Anzahl von Klicks, also sag es dem Benutzer, wenn du eine solche Einstellung erkennst, und biete an, am Ende alle aufzulösen. Befehle für beides findest du in den Plattformreferenzdateien.

8. Synchronisieren nach jedem Push

Neue Commits machen Annotationen stillschweigend ungültig: Der Code, den ein Kommentar beschreibt, könnte verschoben worden sein, seine Bedeutung geändert haben oder verschwunden sein – und neue Dateien kommen ohne jede Abdeckung. Führe diesen Skill nach jedem Push auf den MR-Branch im sync-Modus erneut aus.

python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json

--comments ist wiederholbar und nimmt das rohe JSON der Plattform unverändert – auf GitHub sind das zwei Aufrufe (Review-Kommentare und Issue-Kommentare), also übergib beide Dateien.

Es klassifiziert jede vorhandene Annotation als ok (Anker und Fingerprint unverändert – in Ruhe lassen), moved (gleicher Code, neue Zeile – neu verankern), stale (der Code, den es beschrieb, hat sich geändert – erneut lesen und umschreiben) oder orphaned (Datei oder Hunk ist weg – löschen). Es meldet auch file coverage – welche geänderten Dateien immer noch keinen Dateikommentar haben, welche ausgenommen sind – und uncovered-Hunks, die jetzt Kandidaten für einen Inline-Kommentar sind.

Dann: Korrigiere nur das, was es markiert hat. Schreibe den Übersichtskommentar immer direkt um (er fasst den gesamten MR zusammen, daher kann jeder Push ihn ungültig machen). Führe Phase 2 von §6 erneut aus, damit Querverweis-Links immer noch auf aktive Kommentare zeigen. Eine Zeile MISSING in der Dateiabdeckung ist keine optionale Arbeit – eine neue Datei ohne Kommentar ist die eine Lücke, die dieser Skill verhindern soll. Befolge references/sync-after-push.md für den Fall des Force-Pushes, die Handhabung gelöschter Kommentare pro Plattform und wie vermieden wird, Kommentare umzurühren, die sich nicht tatsächlich geändert haben.

Erwähne dem Benutzer einmal, dass dies nach jedem Push ausgeführt werden muss und dass references/sync-after-push.md einen optionalen pre-push-Hook enthält.

Verwandte Skills