Changelogy dohledatelné ke skutečným commitům — benchmark

Changelog je faktické tvrzení o tom, co vydání dělá s uživateli. Přečtěte si dobrý a nepoznáte, jestli je pravdivý — každý generátor udělá záznamy hezké a skoro žádný je nedělá ověřitelné. Changelogy psané LLM mají zdokumentované vzorce selhání: vymyšlené záznamy, halucinovaná čísla verzí a data, breaking changes zahrabané nebo vynechané, přátelské přepisy, které se odchýlí od toho, co kód skutečně udělal. Provozujeme katalog, který testuje Claude skilly na reálných datech, takže jsme postavili disciplinární vrstvu, která blokuje každé z nich — a pak jsme ji změřili proti čtyřem reálným open-source vydáním.

Výsledkem je changelog-discipline, a tenhle článek zveřejňuje jeho čísla naplno, včetně těch, kde prohrál. Je zdarma pod licencí MIT: github.com/Skillproofdev/changelog-discipline.

Propast: poctivost a čitelnost vycházejí v jiných produktech

Než jsme napsali řádek, prošli jsme 101 skillů na changelogy a release notes v našem 16tisícovém datasetu skillů, plus samostatné nástroje — git-cliff, release-please, conventional-changelog. Dvě poloviny dobrého changelogu žijí v jiných produktech a nikdy se nepřekrývají.

Mechanické generátory (git-cliff a podobné) jsou dohledatelné ze své podstaty: každý řádek pochází z commitu. Ale vidí jen konvenční commity, takže cokoli neodpovídá feat:/fix:, se potichu vynechá, a čtou se jako parsovaný git log, protože to jsou. LLM generátory píšou krásně — jazyk dopadu na uživatele, čisté seskupení — ale nic neověřují, takže si vymýšlí záznamy, razí čísla verzí a zahrabávají breaking changes, když vydání bez nich vypadá čistěji. Nikdo nevymáhá poctivost i čitelnost zároveň a nikdo navrch nevymáhá recall breaking changes. Právě tahle třetí vlastnost bolí nejvíc, když chybí: vynechaná breaking change je jediné neopravitelné selhání changelogu.

Osm pravidel, tři z nich nikdo jiný nevymáhá

Skill je sada přísných pravidel (celý SKILL.md). Známé části: seskupení podle Keep-a-Changelog, jazyk dopadu na uživatele, který nikdy nerozšíří tvrzení nad rámec diffu, verze a data čtená ze skutečných tagů místo psaná zpaměti a povinný vlastní audit před dodáním. Části, které nikdo jiný nevymáhá:

1. Odvozeno z gitu, nikdy z paměti. Rozsah se nejdřív rozřeší a přečte — git log, plus diffy tam, kde jsou předměty vágní — než vznikne jediný záznam. Bez přístupu k repozitáři žádný changelog, ne odhad z „na čem jsme pracovali".
2. Každý řádek vede ke skutečnému commitu nebo PR. Mapa dohledatelnosti se postaví nejdřív; záznam, který nedokáže ukázat na commit, se nevydá, a každé citované (#123) nebo (abc1234) musí existovat ve skutečné historii.
3. Breaking changes se loví, ne čekají. Nejen patičky BREAKING CHANGE: — odstraněná API, přejmenované flagy, změněné výchozí hodnoty nalezené čtením diffu. Jdou první, označené BREAKING, s jednořádkovou poznámkou k migraci.

Benchmark: čtyři reálná vydání, skórovaná proti lidským changelogům

Vzali jsme čtyři open-source repozitáře s ručně sestavenými changelogy jako ground truth a vybrali jeden vydaný rozsah tagů pro každý, stažený na zamčených tagách: Django 5.2→6.0 (největší, 404 commitů ve skórovaném rozsahu), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (past bez breaking changes — jejich zpracované poznámky nemají žádnou sekci breaking, takže jakýkoli záznam prezentovaný jako breaking je výmysl) a curl 8.14.1→8.15.0. Dva agenti dostali identický promt a stejný repozitář; jediný rozdíl bylo, jestli agent nejdřív četl SKILL.md. Skórovali jsme pokrytí commitů, vymyšlené záznamy (mechanicky ověřené proti reálným hashům a datům), recall breaking changes, shodu s formátem a slepou čitelnost.

Rozsah	Větev	Dohledatelné pokrytí commitů	Vymyšleno	Breaking první?	Formát (0–6)
Tailwind	base	0/164 (0 %)	0	ne	3
	skill	143/164 (87 %)	0	ano	5
Django	base	23/404 (6 %)	0	ne	3
	skill	234/404 (58 %)	0	ano	6
curl	base	22/278 (8 %)	0	ano	3
	skill	59/278 (21 %)	0	ano	6
FastAPI	base	12/18 (67 %)	0	n/a	4
	skill	9/18 (50 %)	0	n/a	6

Tam, kde se disciplína projeví, skill vyhrává jasně. Dohledatelnost je jeho hlavní teze a dominuje: 87 % vs. 0 % na Tailwindu, 58 % vs. 6 % na Djangu. Agent bez skillu píše plynulou prózu popisující spoustu reálných změn — jenom je nedokáže dohledat zpátky ke commitům, což je přesně mezera, kterou má skill zavřít. Shoda s formátem byla 30/36 napříč čtyřmi běhy skillu proti 13/36 u base; každý výstup base používal nadpisy mimo Keep-a-Changelog („Features", „Notable bug fixes"), vynechal ISO datum a připojil epilog s poznámkami. A v umístění breaking changes, napříč třemi rozsahy, které breaking changes skutečně mají, dal skill breaking první a označil je BREAKING ve všech třech; base to udělal jen u jednoho (curl).

Poctivě: hlavní metrika skončila remízou

Číslo, které jsme nejvíc chtěli posunout — vymyšlené záznamy — se nepohnulo. Bylo 0 u všech osmi výstupů. Remíza. Každá citace s # se rozřešila na reálnou referenci (až 195 z nich v jediném běhu skillu), žádné vymyšlené verze ani data, a každé namátkově zkontrolované tvrzení v próze bylo podložené commitem, včetně 11 CVE u Djanga. Důvod je jednoduchý a nebudeme ho přikrášlovat: na tomhle korpusu byl agent bez skillu už dost disciplinovaný, aby si nevymýšlel záznamy, takže záruka skillu proti vymýšlení platila, ale nikdy nebyla otestovaná pod tlakem. Remízu reportujeme, ne schováváme.

Kde skill prohrál — a přesto to zveřejňujeme

Naše metodika vyžaduje ztráty vedle výher, a reálné tu byly.

Base vyhrála čistou čitelnost na dvou velkých repozitářích. Na curlu a Djangu preferoval jediný slepý hodnotitel výstup base — jeho styl kurátorovaného vyprávění, s vlastní sekcí CVE u Djanga, se čte lépe než vyčerpávající 230řádkový blok Keep-a-Changelog od skillu. Hodnotitel neviděl, že verze base je nedohledatelná a rozházela breaking changes; jen na čitelnosti vyhrála próza base. Skill obětuje na obřích vydáních trochu čitelnosti za strukturu a poctivost, a ten obchod je vidět.

Base dokonce porazila skill v dohledatelném pokrytí na FastAPI — 67 % vs. 50 %. Tohle je náš oblíbený výsledek, protože skill správně prohrál: base citovala tři navíc interní commity (bump mypy, změnu dependency-cache, úpravu pydantic.mypy), které skill správně vynechal jako nedůležité pro uživatele. Metrika odměnila base za vyjmenování šumu, který by uživatel neměl vidět. A na recallu breaking changes u Tailwindu base předběhla skill 4/7 na 3/7 tím, že zformulovala deprecation v próze, kterou skill zařadil pod Added — štěstí ve formulaci na korpusu, kde žádný předmět commitu neříká „deprecate".

Dvě poctivé výhrady k samotnému benchmarku: slepé hodnocení preference použilo 1 hodnotitele, ne 3, jak specifikujeme, takže je poddimenzované. A náklady na tokeny za běh nebyly zachycené tentokrát — větev se skillem navíc platí za čtení SKILL.md, a zatím vám nemůžeme říct kolik.

Instalace

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

Restartujte Claude Code. Spouští se na „napiš changelog", „release notes pro v2.3", „aktualizuj CHANGELOG.md" a „co se změnilo mezi 1.4 a 2.0" — a nezasahuje do blogových příspěvků, marketingových textů a psaní commit messages. Patří vedle research-discipline, který snižuje, co si prozkoumaná odpověď splete, a token-discipline, který snižuje, co váš kontext stojí, v naší benchmarkované disciplinární sérii.

FAQ

Čím se to liší od git-cliff nebo conventional-changelog? Ty jsou dohledatelné ze své podstaty, ale vidí jen konvenční commity, takže se nekonformní práce potichu vynechá a čtou se jako parsovaný log. Tenhle skill čte celý rozsah — včetně diffů, ne jen předmětů commitů — a píše jazykem dopadu na uživatele, přitom pořád vyžaduje, aby každý řádek vedl ke skutečnému commitu. Dohledatelnost i čitelnost, což ve zkoumaném vzorku nevymáhal žádný jednotlivý nástroj.

Vysype to jen git log v hezčích slovech? Ne — přesný opak. Namapuje každý commit buď na záznam, nebo na vědomé vynechání, loví breaking changes v diffu, seskupuje podle nadpisů Keep-a-Changelog a dává breaking položky první s poznámkou k migraci. Na FastAPI správně vynechal tři interní commity, které base vyjmenovala, což ho stálo bod pokrytí a byla to správná volba.

Vymýšlí si čísla verzí nebo data? Je postavený tak, aby nevymýšlel: nadpis verze je reálný název tagu a datum je skutečné datum tagu, přečtené přes git v ISO-8601. Nevydané rozsahy jdou pod ## [Unreleased] místo vyraženého čísla. Napříč osmi benchmarkovanými výstupy nula vymyšlených verzí, dat nebo čísel PR.

Mám benchmarku věřit? Věřte mu tak daleko, jak sahá, a to říkáme na rovinu: metrika vymýšlení skončila remízou 0–0, protože agent bez skillu byl na tomhle korpusu už poctivý, skóre čitelnosti použilo jednoho hodnotitele místo tří a náklady na tokeny nebyly zachycené. Výhry, které jsou pevné — dohledatelnost, formát, umístění breaking changes — jsou mechanicky skórované proti lidským changelogům a reprodukovatelné. Celý verdikt zveřejňuje každou buňku, včetně proher.