Changelogs, rückverfolgbar bis zum echten Commit

Ein Changelog ist eine Tatsachenbehauptung darüber, was ein Release seinen Nutzern antut. Lies ein gutes, und du kannst nicht erkennen, ob es stimmt – jeder Generator macht die Einträge hübsch, kaum einer macht sie überprüfbar. Von Claude geschriebene Changelogs haben dokumentierte Fehlermuster: erfundene Einträge, halluzinierte Versionsnummern und Daten, vergrabene oder fehlende Breaking Changes, freundliche Umformulierungen, die von dem abdriften, was der Code tatsächlich getan hat. Wir betreiben ein Verzeichnis, das Claude-Skills beruflich benchmarkt, also haben wir die Disziplinschicht gebaut, die jedes davon blockiert – und sie dann gegen vier echte Open-Source-Releases gemessen.

Das Ergebnis heißt changelog-discipline, und dieser Beitrag veröffentlicht seine Zahlen vollständig, auch die, bei denen es verloren hat. Kostenlos und MIT-lizenziert: github.com/Skillproofdev/changelog-discipline.

Die Lücke: Ehrlichkeit und Lesbarkeit stecken in verschiedenen Produkten

Bevor wir eine Zeile geschrieben haben, haben wir 101 Changelog- und Release-Notes-Skills in unserem 16k-Skills-Datensatz gesichtet, plus die eigenständigen Tools – git-cliff, release-please, conventional-changelog. Die zwei Hälften eines guten Changelogs leben in verschiedenen Produkten und überschneiden sich nie.

Mechanische Generatoren (git-cliff und Verwandte) sind konstruktionsbedingt rückverfolgbar: Jede Zeile kommt aus einem Commit. Aber sie sehen nur Conventional Commits, also fällt alles, was nicht zu feat:/fix: passt, still unter den Tisch, und sie lesen sich wie ein geparster Git-Log, weil sie genau das sind. KI-Generatoren schreiben wunderschön – Sprache mit Nutzerwirkung, saubere Gruppierung – aber sie verifizieren nichts, also erfinden sie Einträge, prägen Versionsnummern und vergraben Breaking Changes, wenn der Release ohne sie sauberer aussieht. Niemand setzt Ehrlichkeit und Lesbarkeit gleichzeitig durch, und niemand setzt zusätzlich Breaking-Change-Trefferquote durch. Genau diese dritte Eigenschaft tut am meisten weh, wenn sie fehlt: ein fallengelassener Breaking Change ist der eine nicht wiedergutzumachende Changelog-Fehler.

Acht Regeln, drei davon durchsetzt sonst niemand

Das Skill ist ein Satz harter Regeln (vollständige SKILL.md). Die bekannten Teile: Keep-a-Changelog-Gruppierung, Sprache mit Nutzerwirkung, die eine Behauptung nie über den Diff hinaus ausweitet, Versionen und Daten aus echten Tags statt aus dem Gedächtnis geschrieben, und ein verpflichtender Selbstaudit vor der Auslieferung. Die Teile, die sonst niemand durchsetzt:

1. Aus Git abgeleitet, nie aus dem Gedächtnis. Der Bereich wird aufgelöst und gelesen – git log, plus Diffs, wo Betreffzeilen vage sind – bevor ein einziger Eintrag geschrieben wird. Kein Repo-Zugriff heißt kein Changelog, keine Vermutung aus „was wir wohl gemacht haben“.
2. Jede Zeile lässt sich auf einen echten Commit oder PR zurückführen. Eine Rückverfolgungskarte wird zuerst erstellt; ein Eintrag, der sich nicht auf einen Commit zurückführen lässt, wird nicht ausgeliefert, und jedes zitierte (#123) oder (abc1234) muss in der echten Historie existieren.
3. Breaking Changes werden gejagt, nicht abgewartet. Nicht nur BREAKING CHANGE:-Fußzeilen – entfernte APIs, umbenannte Flags, geänderte Defaults, gefunden durch Lesen des Diffs. Sie stehen zuerst, markiert BREAKING, mit einer einzeiligen Migrationsnotiz.

Der Benchmark: vier echte Releases, bewertet gegen von Menschen kuratierte Changelogs

Wir haben vier Open-Source-Repos mit von Hand kuratierten Changelogs als Ground Truth genommen und je einen veröffentlichten Tag-Bereich ausgewählt, abgerufen bei den fixierten Tags: Django 5.2→6.0 (der größte, 404 Commits im bewerteten Satz), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (eine Null-Breaking-Falle – seine kuratierten Notizen haben keinen Breaking-Abschnitt, also ist jeder als Breaking dargestellte Eintrag eine Fabrikation) und curl 8.14.1→8.15.0. Zwei Agenten bekamen den identischen Prompt und dasselbe Repo; einziger Unterschied war, ob der Agent vorher diese SKILL.md gelesen hatte. Wir haben Commit-Abdeckung, erfundene Einträge (mechanisch gegen echte Hashes und Daten verifiziert), Breaking-Change-Trefferquote, Formatkonformität und blinde Lesbarkeit bewertet.

Bereich	Arm	Rückverfolgbare Commit-Abdeckung	Erfunden	Breaking zuerst?	Format (0–6)
Tailwind	Base	0/164 (0%)	0	nein	3
	Skill	143/164 (87%)	0	ja	5
Django	Base	23/404 (6%)	0	nein	3
	Skill	234/404 (58%)	0	ja	6
curl	Base	22/278 (8%)	0	ja	3
	Skill	59/278 (21%)	0	ja	6
FastAPI	Base	12/18 (67%)	0	n/a	4
	Skill	9/18 (50%)	0	n/a	6

Wo Disziplin sich zeigt, gewinnt das Skill klar. Rückverfolgbarkeit ist seine Kernthese, und sie dominiert: 87% vs. 0% bei Tailwind, 58% vs. 6% bei Django. Der Base-Agent schreibt flüssige Prosa, die viele echte Änderungen beschreibt – er kann sie nur nicht auf Commits zurückführen, und genau diese Lücke soll das Skill schließen. Formatkonformität lag über die vier Skill-Läufe bei 30/36, gegen 13/36 bei Base; jeder Base-Output nutzte Nicht-Keep-a-Changelog-Überschriften („Features“, „Notable bug fixes“), ließ das ISO-Datum weg und hängte einen Notizen-Epilog an. Und bei der Platzierung von Breaking Changes setzte das Skill sie über die drei Bereiche mit echten Breaking Changes hinweg immer zuerst und markierte sie BREAKING; Base tat das nur bei einem (curl).

Ehrlich bleiben: die Schlagzeilenmetrik war ein Unentschieden

Die eine Zahl, die wir am meisten bewegen wollten – erfundene Einträge – hat sich nicht bewegt. Sie lag bei 0 für alle acht Outputs. Unentschieden. Jedes #-Zitat löste sich zu einer echten Referenz auf (bis zu 195 davon in einem einzigen Skill-Lauf), keine erfundenen Versionen oder Daten, und jede stichprobenartig geprüfte Prosa-Behauptung war commit-belegt, inklusive Djangos 11 CVEs. Der Grund ist simpel, und wir dressieren ihn nicht auf: In diesem Korpus war der Base-Agent bereits diszipliniert genug, keine Einträge zu erfinden, also hielt die Fabrikationsgarantie des Skills, wurde aber nie wirklich auf die Probe gestellt. Wir berichten das Unentschieden, statt es zu verstecken.

Wo das Skill verloren hat – trotzdem veröffentlicht

Unsere Methodik verlangt, die Verluste neben die Gewinne zu stellen, und es gab echte.

Base gewann die reine Lesbarkeit bei den zwei großen Repos. Bei curl und Django bevorzugte der einzelne blinde Bewerter den Base-Output – sein kuratierter Erzählstil, mit einem eigenen CVE-Abschnitt bei Django, liest sich besser als der erschöpfende 230-Zeilen-Keep-a-Changelog-Block des Skills. Der Bewerter konnte nicht sehen, dass die Base-Version nicht rückverfolgbar war und ihre Breaking Changes verstreute; rein nach Lesbarkeit gewann die Base-Prosa. Das Skill tauscht auf riesigen Releases etwas Lesbarkeit gegen Struktur und Ehrlichkeit, und dieser Tausch ist sichtbar.

Base schlug das Skill sogar bei der rückverfolgbaren FastAPI-Abdeckung – 67% vs. 50%. Das ist unser Lieblingsergebnis, denn das Skill hatte recht damit, hier zu verlieren: Base zitierte drei zusätzliche interne Commits (ein mypy-Bump, eine Dependency-Cache-Änderung, ein pydantic.mypy-Fix), die das Skill korrekt als für Nutzer irrelevant ausließ. Die Metrik belohnte Base dafür, Churn zu listen, den ein Nutzer nicht sehen sollte. Und bei der Tailwind-Breaking-Trefferquote lag Base mit 4/7 gegen 3/7 vor dem Skill, weil eine Deprecation in Prosa formuliert war, die das Skill unter „Added“ ablegte – Formulierungsglück in einem Korpus, in dem keine Commit-Betreffzeile „deprecate“ sagt.

Zwei ehrliche Vorbehalte zum Benchmark selbst: Der blinde Präferenzscore nutzte 1 Bewerter, nicht die vorgesehenen 3, ist also unterbesetzt. Und der Token-Kostenaufwand pro Lauf wurde diesmal nicht erfasst – der Skill-Arm zahlt zusätzlich fürs Lesen der SKILL.md, und wir können dir noch nicht sagen, wie viel.

Installation

git clone https://github.com/Skillproofdev/changelog-discipline ~/.claude/skills/changelog-discipline

Claude Code neu starten. Es greift bei „write a changelog“, „release notes for v2.3“, „update CHANGELOG.md“ und „what changed between 1.4 and 2.0“ – und hält sich raus bei Blogposts, Marketingtexten und dem Verfassen von Commit-Messages. Es reiht sich neben research-discipline, das senkt, was eine recherchierte Antwort falsch macht, und token-discipline, das senkt, was dein Kontext kostet, in unsere benchmarked Discipline-Serie ein.

FAQ

Wie unterscheidet sich das von git-cliff oder conventional-changelog? Die sind konstruktionsbedingt rückverfolgbar, sehen aber nur Conventional Commits, sodass nicht konformer Code still unter den Tisch fällt, und sie lesen sich wie ein geparster Log. Dieses Skill liest den ganzen Bereich – Diffs inklusive, nicht nur Commit-Betreffzeilen – und schreibt Sprache mit Nutzerwirkung, während trotzdem jede Zeile auf einen echten Commit zurückführen muss. Rückverfolgbarkeit und Lesbarkeit, was kein einzelnes Tool in unserer Erhebung gemeinsam durchsetzte.

Kippt es einfach den Git-Log mit schönerer Wortwahl aus? Nein – das Gegenteil. Es ordnet jeden Commit entweder einem Eintrag oder einem bewussten Ausschluss zu, jagt Breaking Changes im Diff, gruppiert nach Keep-a-Changelog-Überschriften und stellt Breaking-Einträge mit Migrationsnotiz nach vorn. Bei FastAPI hat es korrekt drei interne Commits ausgelassen, die der Base-Agent listete – das hat es einen Abdeckungspunkt gekostet und war die richtige Entscheidung.

Erfindet es Versionsnummern oder Daten? Es ist so gebaut, dass es das nicht tut: Die Versionsüberschrift ist der echte Tag-Name, und das Datum ist das tatsächliche Tag-Datum, per Git in ISO-8601 gelesen. Unveröffentlichte Bereiche landen unter ## [Unreleased], statt eine geprägte Nummer zu bekommen. Über acht Benchmark-Outputs: null erfundene Versionen, Daten oder PR-Nummern.

Kann ich dem Benchmark trauen? So weit, wie er reicht – und das sagen wir offen: Die Fabrikationsmetrik war ein 0:0-Unentschieden, weil der Base-Agent auf diesem Korpus schon ehrlich war, der Lesbarkeitsscore nutzte einen Bewerter statt drei, und der Token-Kostenaufwand wurde nicht erfasst. Die Gewinne, die solide sind – Rückverfolgbarkeit, Format, Breaking-Change-Platzierung – sind mechanisch gegen die von Menschen erstellten Changelogs bewertet und reproduzierbar. Das vollständige Verdict veröffentlicht jede Zelle, Verluste inklusive.