Changelogs du kan spore til ekte commits — benchmarket

En changelog er en faktapåstand om hva en utgivelse gjør med brukerne sine. Les en god en, og du kan ikke se om den er sann — hver generator gjør oppføringene pene, og nesten ingen gjør dem verifiserbare. KI-skrevne changelogs har dokumenterte feilmåter: oppdiktede oppføringer, hallusinerte versjonsnumre og datoer, brytende endringer begravet eller droppet, vennlige omskrivinger som driver bort fra hva koden faktisk gjorde. Vi driver en katalog som benchmarker Claude-skills til daglig, så vi bygde disiplinlaget som blokkerer hver av dem — og målte det så mot fire ekte open source-utgivelser.

Resultatet er changelog-discipline, og dette innlegget publiserer tallene i sin helhet, inkludert de den tapte. Den er gratis og MIT-lisensiert: github.com/Skillproofdev/changelog-discipline.

Gapet: ærlighet og lesbarhet leveres i forskjellige produkter

Før vi skrev en eneste linje kartla vi 101 changelog- og release notes-skills i vårt datasett på 16 000 skills, pluss de frittstående verktøyene — git-cliff, release-please, conventional-changelog. De to halvdelene av en god changelog lever i forskjellige produkter og overlapper aldri.

Mekaniske generatorer (git-cliff og lignende) er sporbare av konstruksjon: hver linje kommer fra en commit. Men de ser bare conventional commits, så alt som ikke matcher feat:/fix: droppes stille, og de leser som en parset git-logg fordi det er akkurat det de er. KI-generatorer skriver vakkert — brukerkonsekvens-språk, ren gruppering — men de verifiserer ingenting, så de dikter opp oppføringer, mynter versjonsnumre og begraver brytende endringer når utgivelsen ser renere ut uten dem. Ingen håndhever både ærlighet og lesbarhet, og ingen håndhever gjenfinning av brytende endringer på toppen av det. Den tredje egenskapen er den som faktisk skader når den mangler: en droppet brytende endring er den ene changelog-feilen du ikke kan rette i ettertid.

Åtte regler, tre ingen andre håndhever

Skillen er et sett med harde regler (hele SKILL.md). De kjente delene: Keep-a-Changelog-gruppering, brukerkonsekvens-fraser som aldri utvider en påstand utover diffen, versjoner og datoer lest fra ekte tagger i stedet for skrevet fra hukommelsen, og en obligatorisk egenrevisjon før levering. Delene ingen andre håndhever:

1. Utledet fra git, aldri fra hukommelsen. Rangen løses opp og leses — git log, pluss differ der emner er vage — før en eneste oppføring skrives. Ingen repo-tilgang betyr ingen changelog, ikke en gjetning fra «hva vi jobbet med».
2. Hver linje spores til en ekte commit eller PR. Et sporingskart bygges først; en oppføring som ikke kan peke på en commit, leveres ikke, og hver siterte (#123) eller (abc1234) må finnes i den faktiske historikken.
3. Brytende endringer jaktes, ikke ventes på. Ikke bare BREAKING CHANGE:-fotnoter — fjernede API-er, omdøpte flagg, endrede standardverdier funnet ved å lese diffen. De kommer først, merket BREAKING, med en migreringsnotis på én linje.

Benchmarken: fire ekte utgivelser, scoret mot menneske-changelogs

Vi tok fire open source-repoer med håndkuraterte changelogs som fasit og valgte én utgitt tag-range hver, hentet ved de fastlåste taggene: Django 5.2→6.0 (den største, 404 commits i det scorede settet), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (en null-brytende-felle — den kuraterte notisen har ingen brytende-seksjon, så enhver oppføring presentert som brytende er en oppdikting), og curl 8.14.1→8.15.0. To agenter fikk den identiske prompten og det samme repoet; den eneste forskjellen var om agenten leste denne SKILL.md-en først. Vi scoret commit-dekning, oppdiktede oppføringer (mekanisk verifisert mot ekte hasher og datoer), gjenfinning av brytende endringer, formatsamsvar og blind lesbarhet.

Range	Arm	Sporbar commit-dekn.	Oppdiktet	Brytende først?	Format (0–6)
Tailwind	base	0/164 (0 %)	0	nei	3
	skill	143/164 (87 %)	0	ja	5
Django	base	23/404 (6 %)	0	nei	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	i/a	4
	skill	9/18 (50 %)	0	i/a	6

Der disiplin viser seg, vinner skillen tydelig. Sporbarhet er hovedtesen dens, og den dominerer: 87 % mot 0 % på Tailwind, 58 % mot 6 % på Django. Base-agenten skriver flytende prosa som beskriver mange ekte endringer — den klarer bare ikke å spore dem tilbake til commits, som er nøyaktig gapet skillen skal lukke. Formatsamsvar var 30/36 på tvers av skillens fire kjøringer mot 13/36 for base; hvert base-resultat brukte overskrifter utenfor Keep-a-Changelog («Features», «Notable bug fixes»), droppet ISO-datoen og hektet på en notis-epilog. Og på plassering av brytende endringer, på tvers av de tre rangene som faktisk har brytende endringer, satte skillen dem først og merket dem BREAKING i alle tre; base gjorde det i én (curl).

Vær ærlig: hovedtallet ble uavgjort

Det ene tallet vi mest ville flytte — oppdiktede oppføringer — flyttet seg ikke. Det var 0 for alle åtte resultater. Uavgjort. Hver #-referanse løste opp til en ekte referanse (opptil 195 av dem i én skill-kjøring), ingen oppfunne versjoner eller datoer, og hver stikkprøvekontrollerte prosapåstand var commit-forankret, inkludert Djangos 11 CVE-er. Grunnen er enkel, og vi later ikke som noe annet: på dette korpuset var base-agenten allerede disiplinert nok til ikke å dikte opp oppføringer, så skillens oppdiktings-garanti holdt, men ble aldri stresstestet. Vi rapporterer uavgjort-resultatet i stedet for å begrave det.

Der skillen tapte — publisert likevel

Vår metodikk krever at tapene vises ved siden av seirene, og det var reelle tap.

Base vant ren lesbarhet på de to store repoene. På curl og Django foretrakk den ene blinde bedømmeren base-resultatet — dens kuraterte fortellerstil, med en dedikert CVE-seksjon på Django, leser bedre enn skillens uttømmende 230-linjers Keep-a-Changelog-blokk. Bedømmeren kunne ikke se at base-versjonen var usporbar og spredte sine brytende endringer; på lesbarhet alene vant base sin prosa. Skillen bytter bort noe lesbarhet på enorme utgivelser mot struktur og ærlighet, og den handelen er synlig.

Base slo til og med skillen på FastAPI-sporbar-dekning — 67 % mot 50 %. Dette er vårt favorittresultat, fordi skillen hadde rett i å tape det: base siterte tre ekstra interne commits (en mypy-oppgradering, en dependency-cache-endring, en pydantic.mypy-justering) som skillen korrekt droppet som ikke-brukersynlige. Metrikken belønnet base for å liste opp støy en bruker ikke skal se. Og på Tailwind-brytende-gjenfinning slo base skillen 4/7 mot 3/7 ved å frase en avvikling i prosa som skillen arkiverte under Added — fraseringsflaks på et korpus der ingen commit-emne sier «deprecate».

To ærlige forbehold om selve benchmarken: den blinde preferansescoren brukte 1 bedømmer, ikke de 3 vi spesifiserer, så den er underdimensjonert. Og kostnad per kjøring i tokens ble ikke fanget denne runden — skill-armen betaler i tillegg for å lese SKILL.md, og vi kan ennå ikke fortelle deg hvor mye.

Installasjon

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

Start Claude Code på nytt. Den trigger på «skriv en changelog», «release notes for v2.3», «oppdater CHANGELOG.md», og «hva endret seg mellom 1.4 og 2.0» — og holder seg unna blogginnlegg, markedsføringstekst og commit-melding-forfatting. Den inngår sammen med research-discipline, som kutter hva et researchet svar bommer på, og token-discipline, som kutter hva konteksten din koster, i vår benchmarkede disiplin-serie.

Ofte stilte spørsmål

Hvordan skiller dette seg fra git-cliff eller conventional-changelog? De er sporbare av konstruksjon, men ser bare conventional commits, så ikke-samsvarende arbeid droppes stille, og de leser som en parset logg. Denne skillen leser hele rangen — differ inkludert, ikke bare commit-emner — og skriver brukerkonsekvens-språk mens den fortsatt krever at hver linje spores til en ekte commit. Sporbarhet og lesbarhet, noe ingen enkeltverktøy i vår kartlegging håndhevet sammen.

Dumper den bare git-loggen med penere ordlyd? Nei — det motsatte. Den kobler hver commit til enten en oppføring eller en bevisst utelatelse, jakter brytende endringer i diffen, grupperer etter Keep-a-Changelog-overskrifter, og setter brytende elementer først med en migreringsnotis. På FastAPI droppet den korrekt tre interne commits base-agenten listet opp, noe som kostet den et dekningspoeng og var riktig avgjørelse.

Dikter den opp versjonsnumre eller datoer? Den er bygget for ikke å gjøre det: versjonsoverskriften er det ekte tag-navnet, og datoen er taggens faktiske dato, lest via git i ISO-8601. Ikke-utgitte ranger går under ## [Unreleased] i stedet for å få et myntet nummer. På tvers av åtte benchmark-resultater: null oppfunne versjoner, datoer eller PR-numre.

Bør jeg stole på benchmarken? Stol på den så langt den rekker, noe vi sier rett ut: oppdiktings-metrikken ble uavgjort 0–0 fordi base-agenten allerede var ærlig på dette korpuset, lesbarhetsscoren brukte én bedømmer i stedet for tre, og token-kostnad ble ikke fanget. Seirene som er solide — sporbarhet, format, plassering av brytende endringer — er mekanisk scoret mot menneske-changelogene og reproduserbare. Hele vurderingen publiserer hver celle, inkludert tapene.