Changelogi, które da się prześledzić do realnych commitów

Changelog to twierdzenie faktograficzne o tym, co wydanie robi swoim użytkownikom. Czytasz dobry changelog i nie potrafisz stwierdzić, czy jest prawdziwy — każdy generator sprawia, że wpisy są ładne, a prawie żaden nie sprawia, że są weryfikowalne. Changelogi napisane przez LLM mają udokumentowane tryby awarii: wymyślone wpisy, zhalucynowane numery wersji i daty, breaking changes zakopane albo pominięte, przyjazne przepisania, które dryfują od tego, co kod faktycznie zrobił. Na co dzień prowadzimy katalog, w którym benchmarkujemy skille Claude, więc zbudowaliśmy warstwę dyscypliny, która blokuje każdy z tych trybów — a potem zmierzyliśmy ją na czterech prawdziwych wydaniach open source.

Efektem jest changelog-discipline, a ten wpis publikuje jego liczby w pełni, razem z tymi, w których przegrał. Jest darmowy, na licencji MIT: github.com/Skillproofdev/changelog-discipline.

Luka: uczciwość i czytelność są dostarczane w różnych produktach

Zanim napisaliśmy pierwszą linijkę, przejrzeliśmy 101 skilli do changelogów i release notes w naszym zestawie 16 tys. skilli, plus samodzielne narzędzia — git-cliff, release-please, conventional-changelog. Dwie połowy dobrego changeloga żyją w różnych produktach i nigdy się nie pokrywają.

Generatory mechaniczne (git-cliff i podobne) są śledzalne z konstrukcji: każda linijka pochodzi z commita. Ale widzą tylko conventional commits, więc wszystko, co nie pasuje do feat:/fix:, jest po cichu porzucane, i czytają się jak sparsowany git log, bo tym właśnie są. Generatory LLM piszą pięknie — język skupiony na wpływie na użytkownika, czyste grupowanie — ale niczego nie weryfikują, więc wymyślają wpisy, kują numery wersji i zakopują breaking changes, gdy wydanie wygląda czyściej bez nich. Nikt nie egzekwuje jednocześnie uczciwości i czytelności, i nikt na dodatek nie egzekwuje recall breaking changes. Ta trzecia właściwość jest tą, która faktycznie boli, gdy jej brakuje: porzucona breaking change to jedyna nienaprawialna porażka changeloga.

Osiem reguł, trzech nie egzekwuje nikt inny

Skill to zestaw twardych reguł (pełny SKILL.md). Znajome elementy: grupowanie Keep-a-Changelog, sformułowania skupione na wpływie na użytkownika, które nigdy nie poszerzają twierdzenia poza diff, wersje i daty odczytane z realnych tagów zamiast pisane z pamięci, i obowiązkowy przebieg samoaudytu przed dostarczeniem. Elementy, których nikt inny nie egzekwuje:

1. Wyprowadzony z gita, nigdy z pamięci. Zakres jest rozwiązany i odczytany — git log, plus diffy tam, gdzie tematy są niejasne — zanim napisany zostanie choć jeden wpis. Brak dostępu do repo oznacza brak changeloga, nie domysł z „nad czym pracowaliśmy”.
2. Każda linijka wynika z prawdziwego commita lub PR-a. Mapa śledzenia jest budowana najpierw; wpis, który nie potrafi wskazać commita, nie zostaje wysłany, a każdy cytowany (#123) albo (abc1234) musi istnieć w faktycznej historii.
3. Na breaking changes się poluje, nie czeka. Nie tylko stopki BREAKING CHANGE: — usunięte API, przemianowane flagi, zmienione domyślne wartości znalezione przez czytanie diffa. Idą pierwsze, oznaczone BREAKING, z jednolinijkową notką migracyjną.

Benchmark: cztery prawdziwe wydania, oceniane względem ludzkich changelogów

Wzięliśmy cztery repozytoria open source z ręcznie wykuratorowanymi changelogami jako stan faktyczny i wybraliśmy po jednym wydanym zakresie tagów, pobranym przy przypiętych tagach: Django 5.2→6.0 (największy, 404 commity w ocenianym zestawie), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (pułapka zero-breaking — jego wykuratorowane notatki nie mają sekcji breaking, więc każdy wpis przedstawiony jako breaking jest fabrykacją) i curl 8.14.1→8.15.0. Dwaj agenci dostali identyczny prompt i to samo repo; jedyną różnicą było to, czy agent najpierw przeczytał ten SKILL.md. Oceniliśmy pokrycie commitów, sfabrykowane wpisy (zweryfikowane mechanicznie względem prawdziwych hashy i dat), recall breaking changes, zgodność formatu i ślepą czytelność.

Zakres	Wariant	Pokrycie śledzalnych commitów	Fabrykacje	Breaking pierwsze?	Format (0–6)
Tailwind	base	0/164 (0%)	0	nie	3
	skill	143/164 (87%)	0	tak	5
Django	base	23/404 (6%)	0	nie	3
	skill	234/404 (58%)	0	tak	6
curl	base	22/278 (8%)	0	tak	3
	skill	59/278 (21%)	0	tak	6
FastAPI	base	12/18 (67%)	0	nd.	4
	skill	9/18 (50%)	0	nd.	6

Tam, gdzie dyscyplina się pokazuje, skill wygrywa wyraźnie. Śledzalność to jego główna teza i dominuje: 87% vs 0% na Tailwind, 58% vs 6% na Django. Agent bazowy pisze płynną prozę opisującą mnóstwo prawdziwych zmian — po prostu nie potrafi ich prześledzić do commitów, co jest dokładnie tą luką, którą skill ma zamknąć. Zgodność formatu wyniosła 30/36 dla czterech przebiegów skilla wobec 13/36 dla base; każdy wynik base używał nagłówków spoza Keep-a-Changelog („Features”, „Notable bug fixes”), gubił datę ISO i doklejał epilog z notatkami. A jeśli chodzi o umieszczenie breaking changes, na trzech zakresach, które faktycznie je mają, skill umieścił je pierwsze i oznaczył BREAKING we wszystkich trzech; base zrobił to w jednym (curl).

Bądźmy uczciwi: metryka nagłówkowa to był remis

Jedna liczba, którą najbardziej chcieliśmy ruszyć — sfabrykowane wpisy — się nie ruszyła. Było 0 dla wszystkich ośmiu wyników. Remis. Każde cytowanie # rozwiązywało się do prawdziwego odniesienia (do 195 z nich w jednym przebiegu ze skillem), żadnych wymyślonych wersji ani dat, a każde wyrywkowo sprawdzone twierdzenie prozy było poparte commitem, wliczając 11 CVE Django. Powód jest prosty i nie będziemy go upiększać: na tym korpusie agent bazowy był już wystarczająco zdyscyplinowany, żeby nie wymyślać wpisów, więc gwarancja skilla przeciw fabrykacji się utrzymała, ale nigdy nie została porządnie przetestowana. Raportujemy remis, zamiast go zakopać.

Gdzie skill przegrał — i tak to publikujemy

Nasza metodologia wymaga pokazywania porażek obok zwycięstw, a były prawdziwe.

Base wygrał czystą czytelność na dwóch dużych repo. Na curl i Django jedyny ślepy oceniający preferował wynik base — jego wykuratorowany styl narracyjny, z dedykowaną sekcją CVE na Django, czyta się lepiej niż wyczerpujący 230-liniowy blok Keep-a-Changelog skilla. Oceniający nie widział, że wersja base była nieśledzalna i rozrzuciła swoje breaking changes; jeśli chodzi wyłącznie o czytelność, wygrała proza base. Skill wymienia trochę czytelności na ogromnych wydaniach za strukturę i uczciwość, i ta wymiana jest widoczna.

Base pobił skill nawet na śledzalnym pokryciu FastAPI — 67% vs 50%. To nasz ulubiony wynik, bo skill słusznie to przegrał: base zacytował trzy dodatkowe wewnętrzne commity (podbicie mypy, zmiana cache zależności, poprawka pydantic.mypy), które skill poprawnie porzucił jako niewidoczne dla użytkownika. Metryka nagrodziła base za wylistowanie szumu, którego użytkownik nie powinien widzieć. A przy recall breaking na Tailwind base wyprzedził skilla 4/7 do 3/7, formułując deprecation w prozie, którą skill zaklasyfikował pod Added — szczęście frazowania na korpusie, gdzie żaden temat commita nie mówi „deprecate”.

Dwa uczciwe zastrzeżenia co do samego benchmarku: wynik ślepej preferencji użył 1 oceniającego, nie 3, które określamy, więc jest niedostatecznie zasilony. I koszt tokenów na przebieg nie został przechwycony w tym uruchomieniu — wariant ze skillem dodatkowo płaci za czytanie SKILL.md, a nie potrafimy jeszcze powiedzieć, ile.

Instalacja

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

Zrestartuj Claude Code. Uruchamia się na „write a changelog”, „release notes for v2.3”, „update CHANGELOG.md” i „what changed between 1.4 and 2.0” — i nie wtrąca się przy wpisach na bloga, tekstach marketingowych i pisaniu commit message'y. Dołącza do research-discipline, który tnie to, w czym research'owana odpowiedź się myli, i token-discipline, który tnie to, ile kosztuje twój kontekst, w naszej zbenchmarkowanej serii dyscyplin.

FAQ

Czym różni się to od git-cliff albo conventional-changelog? Te są śledzalne z konstrukcji, ale widzą tylko conventional commits, więc niepasująca praca jest po cichu porzucana, i czytają się jak sparsowany log. Ten skill czyta pełny zakres — wliczając diffy, nie tylko tematy commitów — i pisze językiem skupionym na wpływie na użytkownika, jednocześnie wymagając, żeby każda linijka wynikała z prawdziwego commita. Śledzalność i czytelność, czego żadne pojedyncze narzędzie w naszym przeglądzie nie egzekwowało razem.

Czy to po prostu zrzuca git log ładniejszymi słowami? Nie — wręcz przeciwnie. Mapuje każdy commit albo na wpis, albo na świadome wykluczenie, poluje na breaking changes w diffie, grupuje wg nagłówków Keep-a-Changelog i umieszcza pozycje breaking pierwsze z notką migracyjną. Na FastAPI poprawnie porzucił trzy wewnętrzne commity, które wylistował agent bazowy, co kosztowało go punkt pokrycia i było słuszną decyzją.

Czy wymyśla numery wersji albo daty? Zbudowany, żeby tego nie robić: nagłówek wersji to prawdziwa nazwa tagu, a data to faktyczna data tagu, odczytana przez git w ISO-8601. Zakresy niewydane trafiają pod ## [Unreleased], zamiast dostawać wykuty numer. W ośmiu wynikach benchmarku zero wymyślonych wersji, dat czy numerów PR.

Czy powinienem ufać benchmarkowi? Ufaj mu tak daleko, jak sięga, a mówimy o tym wprost: metryka fabrykacji to był remis 0–0, bo agent bazowy był już uczciwy na tym korpusie, ocena czytelności użyła jednego oceniającego zamiast trzech, a koszt tokenów nie został przechwycony. Zwycięstwa, które są solidne — śledzalność, format, umieszczenie breaking changes — są oceniane mechanicznie względem ludzkich changelogów i odtwarzalne. Pełny werdykt publikuje każdą komórkę, wliczając porażki.