Changelogs die je kunt herleiden naar echte commits

Een changelog is een feitelijke claim over wat een release met zijn gebruikers doet. Lees een goede en je kunt niet zien of hij klopt — elke generator maakt de regels mooi, en bijna geen enkele maakt ze verifieerbaar. Door LLM's geschreven changelogs hebben gedocumenteerde faalpatronen: verzonnen regels, gehallucineerde versienummers en data, breaking changes verstopt of weggevallen, vriendelijke herschrijvingen die afdrijven van wat de code echt deed. Wij runnen een directory die Claude-skills benchmarkt voor de kost, dus bouwden we de disciplinelaag die elk daarvan blokkeert — en maten hem toen tegen vier echte open-sourcereleases.

Het resultaat is changelog-discipline, en deze post publiceert zijn cijfers volledig, inclusief de keren dat hij verloor. Gratis en MIT-licensed: github.com/Skillproofdev/changelog-discipline.

Het gat: eerlijkheid en leesbaarheid worden in verschillende producten geleverd

Voordat we een regel schreven, bekeken we 101 changelog- en release-notes-skills in onze dataset van 16k skills, plus de losstaande tooling — git-cliff, release-please, conventional-changelog. De twee helften van een goede changelog zitten in verschillende producten en overlappen nooit.

Mechanische generators (git-cliff en soortgenoten) zijn traceerbaar door constructie: elke regel komt van een commit. Maar ze zien alleen conventionele commits, dus alles wat niet op feat:/fix: past valt stilletjes weg, en ze lezen als een geparste git-log, want dat zijn ze ook. LLM-generators schrijven prachtig — taal over gebruikersimpact, nette groepering — maar ze verifiëren niets, dus ze verzinnen regels, muntenversienummers, en verstoppen breaking changes als de release er zonder schoner uitziet. Niemand dwingt beide af — eerlijkheid én leesbaarheid — en niemand dwingt daar bovenop breaking-change-recall af. Die derde eigenschap is degene die echt pijn doet als hij ontbreekt: een weggevallen breaking change is het enige onherstelbare changelog-falen.

Acht regels, drie die niemand anders afdwingt

De skill is een set harde regels (volledige SKILL.md). De bekende onderdelen: Keep-a-Changelog-groepering, taal over gebruikersimpact die een claim nooit breder maakt dan de diff, versies en data gelezen uit echte tags in plaats van uit het geheugen geschreven, en een verplichte zelfcontrole-pass voor oplevering. De onderdelen die niemand anders afdwingt:

1. Afgeleid van git, nooit uit het geheugen. De range wordt eerst opgelost en gelezen — git log, plus diffs waar subjectregels vaag zijn — voordat er ook maar één regel geschreven wordt. Geen repo-toegang betekent geen changelog, geen gok op basis van "wat we deden".
2. Elke regel herleidt naar een echte commit of PR. Er wordt eerst een traceerkaart gebouwd; een regel die niet naar een commit kan wijzen wordt niet opgenomen, en elke geciteerde (#123) of (abc1234) moet echt in de geschiedenis bestaan.
3. Breaking changes worden opgespoord, niet afgewacht. Niet alleen BREAKING CHANGE:-footers — verwijderde API's, hernoemde flags, gewijzigde standaardwaarden gevonden door de diff te lezen. Ze komen eerst, gemarkeerd als BREAKING, met een migratienotitie van één regel.

De benchmark: vier echte releases, gescoord tegen menselijke changelogs

We namen vier open-sourcerepo's met handmatig samengestelde changelogs als ground truth en kozen per stuk één uitgebrachte tag-range, opgehaald bij de vastgepinde tags: Django 5.2→6.0 (de grootste, 404 commits in de gescoorde set), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (een nul-breaking-val — de samengestelde notities hebben geen breaking-sectie, dus elke regel die als breaking wordt gepresenteerd is een fabricatie), en curl 8.14.1→8.15.0. Twee agents kregen dezelfde prompt en dezelfde repo; het enige verschil was of de agent eerst deze SKILL.md las. We scoorden op commit-dekking, verzonnen regels (mechanisch geverifieerd tegen echte hashes en data), breaking-change-recall, formatnaleving en blinde leesbaarheid.

Range	Arm	Traceerbare commit-dekking	Verzonnen	Breaking eerst?	Format (0–6)
Tailwind	base	0/164 (0%)	0	nee	3
	skill	143/164 (87%)	0	ja	5
Django	base	23/404 (6%)	0	nee	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.v.t.	4
	skill	9/18 (50%)	0	n.v.t.	6

Waar discipline zich toont, wint de skill duidelijk. Traceerbaarheid is zijn kernthese en hij domineert: 87% tegen 0% op Tailwind, 58% tegen 6% op Django. De baseline-agent schrijft vlot proza over legio echte wijzigingen — hij kan ze alleen niet herleiden naar commits, wat precies het gat is dat de skill moet dichten. Formatnaleving stond op 30/36 over de vier runs van de skill tegenover 13/36 voor base; elke base-output gebruikte niet-Keep-a-Changelog-koppen ("Features", "Notable bug fixes"), liet de ISO-datum vallen en plakte er een notities-epiloog achteraan. En bij breaking-change-plaatsing, over de drie ranges die echt breaking changes hebben, zette de skill ze eerst en markeerde ze BREAKING in alle drie; de base deed dat bij één (curl).

Eerlijk zijn: de hoofdmetriek was een gelijkspel

Het ene cijfer dat we het liefst zagen bewegen — verzonnen regels — bewoog niet. Het was 0 voor alle acht outputs. Een gelijkspel. Elke #-citatie herleidde naar een echte referentie (tot 195 ervan in één skill-run), geen verzonnen versies of data, en elke steekproefsgewijs gecontroleerde proza-claim was commit-onderbouwd, inclusief Django's 11 CVE's. De reden is simpel en we verbloemen die niet: op dit corpus was de base-agent al gedisciplineerd genoeg om geen regels te verzinnen, dus de fabricatiegarantie van de skill hield stand, maar werd nooit echt getest. We rapporteren het gelijkspel in plaats van het te verbergen.

Waar de skill verloor — toch gepubliceerd

Onze methodologie eist dat de verliezen naast de winsten staan, en die waren er echt.

Base won op pure leesbaarheid bij de twee grote repo's. Op curl en Django verkoos de enige blinde beoordelaar de base-output — de curatorstijl, met een aparte CVE-sectie op Django, leest beter dan het uitputtende blok van 230 regels in Keep-a-Changelog-stijl van de skill. De beoordelaar kon niet zien dat de base-versie niet-traceerbaar was en zijn breaking changes verspreidde; puur op leesbaarheid won base's proza. De skill ruilt op grote releases wat leesbaarheid in voor structuur en eerlijkheid, en die ruil is zichtbaar.

Base versloeg de skill zelfs op traceerbare dekking bij FastAPI — 67% tegen 50%. Dit is ons favoriete resultaat, want de skill had gelijk dat hij dit verloor: base citeerde drie extra interne commits (een mypy-bump, een dependency-cache-wijziging, een pydantic.mypy-aanpassing) die de skill terecht liet vallen als niet-gebruikersgericht. De metriek beloonde base voor het opsommen van ruis die een gebruiker niet zou moeten zien. En op Tailwind-breaking-recall versloeg base de skill nipt met 4/7 tegen 3/7, door een deprecatie in proza te formuleren die de skill onder Added indeelde — geluk met formulering op een corpus waar geen enkele commit-subject "deprecate" zegt.

Twee eerlijke kanttekeningen bij de benchmark zelf: het blinde-voorkeurscijfer gebruikte 1 beoordelaar, niet de 3 die we voorschrijven, dus het is onderbemand. En tokenkosten per run zijn deze keer niet vastgelegd — de skill-arm betaalt extra om SKILL.md te lezen, en we kunnen je nog niet vertellen hoeveel.

Installatie

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

Herstart Claude Code. Hij triggert op "schrijf een changelog", "release notes voor v2.3", "update CHANGELOG.md", en "wat is er veranderd tussen 1.4 en 2.0" — en blijft weg bij blogposts, marketingteksten en het schrijven van commit-messages. Hij hoort bij research-discipline, dat verlaagt wat een onderzocht antwoord fout heeft, en token-discipline, dat verlaagt wat je context kost, in onze benchmarked disciplinereeks.

FAQ

Hoe verschilt dit van git-cliff of conventional-changelog? Die zijn traceerbaar door constructie maar zien alleen conventionele commits, dus niet-conform werk valt stilletjes weg, en ze lezen als een geparste log. Deze skill leest de volledige range — diffs inbegrepen, niet alleen commit-subjectregels — en schrijft taal over gebruikersimpact terwijl elke regel nog steeds naar een echte commit moet herleiden. Traceerbaarheid en leesbaarheid, wat geen enkele tool in onze inventarisatie samen afdwong.

Dumpt hij gewoon de git-log met mooiere woorden? Nee — het tegenovergestelde. Hij koppelt elke commit aan óf een regel óf een bewuste uitsluiting, spoort breaking changes op in de diff, groepeert volgens Keep-a-Changelog-koppen, en zet breaking-items eerst met een migratienotitie. Op FastAPI liet hij terecht drie interne commits vallen die de base-agent wel opsomde, wat hem een dekkingspunt kostte en de juiste keuze was.

Verzint hij versienummers of data? Hij is zo gebouwd dat hij dat niet doet: de versiekop is de echte tagnaam en de datum is de echte tagdatum, gelezen via git in ISO-8601. Niet-uitgebrachte ranges gaan onder ## [Unreleased] in plaats van een gemunt nummer te krijgen. Over acht benchmark-outputs: nul verzonnen versies, data of PR-nummers.

Moet ik de benchmark vertrouwen? Vertrouw hem zo ver als hij reikt, en dat zeggen we ronduit: de fabricatiemetriek was een 0-0-gelijkspel omdat de base-agent al eerlijk was op dit corpus, de leesbaarheidsscore gebruikte één beoordelaar in plaats van drie, en tokenkosten zijn niet vastgelegd. De winsten die wél stevig zijn — traceerbaarheid, format, breaking-change-plaatsing — zijn mechanisch gescoord tegen de menselijke changelogs en reproduceerbaar. Het volledige verdict publiceert elke cel, inclusief de verliezen.