Changelogs du kan spore til rigtige commits — benchmarket

En changelog er en faktuel påstand om, hvad en udgivelse gør ved dens brugere. Læs en god én, og du kan ikke se, om den er sand — hver generator gør indlæggene pæne, og næsten ingen gør dem verificerbare. LLM-skrevne changelogs har dokumenterede fejlmåder: opdigtede indlæg, hallucinerede versionsnumre og datoer, breaking changes begravet eller droppet, venlige omskrivninger, der driver væk fra hvad koden rent faktisk gjorde. Vi driver et katalog, der benchmark-tester Claude-skills til daglig, så vi byggede disciplinlaget, der blokerer hver eneste — og målte den derefter mod fire rigtige open source-udgivelser.

Resultatet er changelog-discipline, og dette indlæg udgiver dens tal fuldt ud, inklusive dem, hvor den tabte. Den er gratis og MIT-licenseret: github.com/Skillproofdev/changelog-discipline.

Hullet: ærlighed og læsbarhed leveres i forskellige produkter

Før vi skrev en linje, gennemgik vi 101 changelog- og release-notes-skills i vores 16k-skill-datasæt, plus de selvstændige værktøjer — git-cliff, release-please, conventional-changelog. De to halvdele af en god changelog lever i forskellige produkter og overlapper aldrig.

Mekaniske generatorer (git-cliff og lignende) er sporbare af konstruktion: hver linje kommer fra en commit. Men de ser kun conventional commits, så alt, der ikke matcher feat:/fix:, droppes stille, og de læser som en parset git-log, fordi det er, hvad de er. LLM-generatorer skriver smukt — brugerpåvirknings-sprog, ren gruppering — men de verificerer intet, så de opdigter indlæg, minter versionsnumre og begraver breaking changes, når udgivelsen ser renere ud uden dem. Ingen håndhæver både ærlighed og læsbarhed, og ingen håndhæver breaking-change-genfinding ovenpå det. Den tredje egenskab er den, der reelt gør ondt, når den mangler: en droppet breaking change er den ene uoprettelige changelog-fejl.

Otte regler, tre som ingen andre håndhæver

Skillen er et sæt hårde regler (fuld SKILL.md). De velkendte dele: Keep-a-Changelog-gruppering, brugerpåvirknings-formulering, der aldrig udvider en påstand ud over diffen, versioner og datoer læst fra rigtige tags i stedet for skrevet fra hukommelsen, og et obligatorisk selv-audit-trin før levering. Delene ingen andre håndhæver:

1. Udledt fra git, aldrig fra hukommelsen. Intervallet er opløst og læst — git log, plus diffs hvor emnelinjer er vage — før et eneste indlæg skrives. Ingen repo-adgang betyder ingen changelog, ikke et gæt fra "hvad vi arbejdede på."
2. Hver linje spores til en rigtig commit eller PR. Et sporingskort bygges først; et indlæg, der ikke kan pege på en commit, leveres ikke, og hver citeret (#123) eller (abc1234) skal findes i den faktiske historik.
3. Breaking changes jages, afventes ikke. Ikke kun BREAKING CHANGE:-fodnoter — fjernede API'er, omdøbte flag, ændrede standardværdier fundet ved at læse diffen. De kommer først, mærket BREAKING, med en énlinjes migrationsnote.

Benchmarken: fire rigtige udgivelser, scoret mod menneskeskrevne changelogs

Vi tog fire open source-repoer med håndkuraterede changelogs som grundsandhed og udvalgte ét udgivet tag-interval hver, hentet ved de fastlåste tags: Django 5.2→6.0 (den største, 404 commits i det scorede sæt), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (en zero-breaking-fælde — dens kuraterede noter har ingen breaking-sektion, så enhver linje præsenteret som breaking er en opdigtelse) og curl 8.14.1→8.15.0. To agenter fik den identiske prompt og det samme repo; den eneste forskel var, om agenten læste denne SKILL.md først. Vi scorede commit-dækning, opdigtede indlæg (mekanisk verificeret mod rigtige hashes og datoer), breaking-change-genfinding, formatoverholdelse og blind læsbarhed.

Interval	Arm	Sporbar commit-dæk.	Opdigtet	Breaking først?	Format (0–6)
Tailwind	base	0/164 (0%)	0	nej	3
	skill	143/164 (87%)	0	ja	5
Django	base	23/404 (6%)	0	nej	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

Hvor disciplinen viser sig, vinder skillen klart. Sporbarhed er dens kernetese, og den dominerer: 87% mod 0% på Tailwind, 58% mod 6% på Django. Base-agenten skriver flydende prosa, der beskriver masser af rigtige ændringer — den kan bare ikke spore dem tilbage til commits, hvilket er præcis det hul, skillen findes for at lukke. Formatoverholdelse var 30/36 på tværs af skillens fire kørsler mod 13/36 for base; hvert base-output brugte ikke-Keep-a-Changelog-overskrifter ("Features", "Notable bug fixes"), droppede ISO-datoen og hæftede en note-epilog på. Og på breaking-change-placering, på tværs af de tre intervaller, der reelt har breaking changes, satte skillen dem først og mærkede dem BREAKING i alle tre; base gjorde det i én (curl).

Vær ærlig: overskriftsmetrikken var uafgjort

Det ene tal, vi allermest ville flytte — opdigtede indlæg — flyttede sig ikke. Det var 0 for alle otte outputs. Uafgjort. Hver #-citering løste op til en rigtig reference (op til 195 af dem i én skill-kørsel), ingen opfundne versioner eller datoer, og hver stikprøvetjekket prosapåstand var commit-understøttet, inklusive Djangos 11 CVE'er. Grunden er enkel, og vi pynter ikke på den: på det her korpus var base-agenten allerede disciplineret nok til ikke at opdigte indlæg, så skillens opdigtelsesgaranti holdt, men blev aldrig stresstestet. Vi rapporterer uafgørelsen frem for at begrave den.

Hvor skillen tabte — udgivet alligevel

Vores metode kræver, at tabene står ved siden af sejrene, og der var reelle.

Base vandt ren læsbarhed på de to store repoer. På curl og Django foretrak den enkelte blinde bedømmer base-outputtet — dets kuraterede fortællestil, med en dedikeret CVE-sektion på Django, læser bedre end skillens udtømmende 230-linjers Keep-a-Changelog-blok. Bedømmeren kunne ikke se, at base-versionen var usporbar og spredte sine breaking changes; på ren læsbarhed vandt bases prosa. Skillen bytter noget læsbarhed på store udgivelser for struktur og ærlighed, og den handel er synlig.

Base slog endda skillen på FastAPI-sporbar dækning — 67% mod 50%. Det her er vores foretrukne resultat, for skillen havde ret i at tabe det: base citerede tre ekstra interne commits (en mypy-opgradering, en dependency-cache-ændring, en pydantic.mypy-justering), som skillen korrekt droppede som ikke-brugervendte. Metrikken belønnede base for at liste støj, en bruger ikke burde se. Og på Tailwind-breaking-genfinding slog base skillen 4/7 mod 3/7 ved at formulere en deprecation i prosa, som skillen arkiverede under Added — formuleringsheld på et korpus, hvor ingen commit-emnelinje siger "deprecate."

To ærlige forbehold om selve benchmarken: den blinde præferencescore brugte 1 bedømmer, ikke de 3 vi angiver, så den er underdrevet. Og token-omkostning per kørsel blev ikke fanget denne gang — skill-armen betaler ekstra for at læse SKILL.md, og vi kan endnu ikke fortælle dig hvor meget.

Installation

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

Genstart Claude Code. Den udløses af "write a changelog", "release notes for v2.3", "update CHANGELOG.md" og "what changed between 1.4 and 2.0" — og holder sig væk fra blogindlæg, marketingtekst og commit-besked-forfatterskab. Den slutter sig til research-discipline, som skærer i, hvad et researchet svar tager fejl om, og token-discipline, som skærer i, hvad din kontekst koster, i vores benchmarkede disciplin-serie.

FAQ

Hvordan adskiller det her sig fra git-cliff eller conventional-changelog? De er sporbare af konstruktion, men ser kun conventional commits, så ikke-overensstemmende arbejde droppes stille, og de læser som en parset log. Den her skill læser hele intervallet — diffs inkluderet, ikke kun commit-emnelinjer — og skriver brugerpåvirknings-sprog, mens den stadig kræver, at hver linje spores til en rigtig commit. Sporbarhed og læsbarhed, hvilket intet enkelt værktøj i vores gennemgang håndhævede sammen.

Dumper den bare git-loggen med pænere ord? Nej — det modsatte. Den kortlægger hver commit til enten et indlæg eller en bevidst udelukkelse, jager breaking changes i diffen, grupperer efter Keep-a-Changelog-overskrifter og sætter breaking-elementer først med en migrationsnote. På FastAPI droppede den korrekt tre interne commits, base listede, hvilket kostede den et dækningspoint og var det rigtige valg.

Opfinder den versionsnumre eller datoer? Den er bygget til ikke at: versionsoverskriften er det rigtige tag-navn, og datoen er tagets faktiske dato, læst via git i ISO-8601. Ikke-udgivne intervaller kommer under ## [Unreleased] i stedet for at få mintet et nummer. På tværs af otte benchmark-outputs: nul opfundne versioner, datoer eller PR-numre.

Skal jeg stole på benchmarken? Stol på den så langt, den rækker, hvilket vi siger ligeud: opdigtelsesmetrikken var en 0–0-uafgørelse, fordi base-agenten allerede var ærlig på det her korpus, læsbarhedsscoren brugte én bedømmer i stedet for tre, og token-omkostningen blev ikke fanget. Sejrene, der er solide — sporbarhed, format, breaking-change-placering — er mekanisk scoret mod de menneskeskrevne changelogs og reproducerbare. Den fulde bedømmelse udgiver hver celle, inklusive tabene.