Changelog tracciabili fino ai commit reali — benchmarkato

Un changelog è un'affermazione fattuale su cosa fa una release ai suoi utenti. Leggine uno buono e non puoi dire se è vero — ogni generatore rende le voci belle, e quasi nessuno le rende verificabili. I changelog scritti da LLM hanno failure mode documentati: voci inventate, numeri di versione e date allucinati, breaking change sepolti o persi, riscritture amichevoli che deviano da quello che il codice ha davvero fatto. Gestiamo una directory che testa le skill di Claude sul campo, quindi abbiamo costruito il livello di disciplina che blocca ciascuno di questi — e poi lo abbiamo misurato contro quattro release open source reali.

Il risultato è changelog-discipline, e questo articolo pubblica i suoi numeri per intero, incluse le volte in cui ha perso. È gratis e con licenza MIT: github.com/Skillproofdev/changelog-discipline.

Il vuoto: onestà e leggibilità vengono spedite in prodotti diversi

Prima di scrivere una riga abbiamo passato in rassegna 101 skill di changelog e release notes nel nostro dataset di 16k skill, più gli strumenti standalone — git-cliff, release-please, conventional-changelog. Le due metà di un buon changelog vivono in prodotti diversi e non si incontrano mai.

I generatori meccanici (git-cliff e simili) sono tracciabili per costruzione: ogni riga viene da un commit. Ma vedono solo i conventional commit, quindi tutto ciò che non combacia con feat:/fix: viene scartato in silenzio, e si leggono come un git log riformattato perché è quello che sono. I generatori LLM scrivono in modo splendido — linguaggio orientato all'impatto utente, raggruppamento pulito — ma non verificano nulla, quindi inventano voci, coniano numeri di versione, e seppelliscono i breaking change quando la release sembra più pulita senza. Nessuno applica sia l'onestà che la leggibilità, e nessuno applica il recall dei breaking change sopra entrambe. Quella terza proprietà è quella che fa davvero male quando manca: un breaking change perso è l'unico fallimento di changelog irrecuperabile.

Otto regole, tre delle quali nessun altro applica

La skill è un insieme di regole rigide (SKILL.md completo). Le parti familiari: raggruppamento Keep-a-Changelog, linguaggio orientato all'impatto utente che non allarga mai un'affermazione oltre il diff, versioni e date lette da tag reali invece che scritte a memoria, e una passata di autoaudit obbligatoria prima della consegna. Le parti che nessun altro applica:

1. Derivato da git, mai dalla memoria. L'intervallo viene risolto e letto — git log, più i diff dove gli oggetti sono vaghi — prima che venga scritta anche una sola voce. Niente accesso al repo significa niente changelog, non un'ipotesi da "cosa abbiamo lavorato".
2. Ogni riga risale a un commit o PR reale. Una mappa di tracciamento viene costruita per prima; una voce che non può indicare un commit non viene pubblicata, e ogni (#123) o (abc1234) citato deve esistere davvero nella cronologia.
3. I breaking change si cacciano, non si aspettano. Non solo i footer BREAKING CHANGE: — anche API rimosse, flag rinominati, default cambiati trovati leggendo il diff. Vanno per primi, marcati BREAKING, con una nota di migrazione di una riga.

Il benchmark: quattro release reali, valutate contro changelog umani

Abbiamo preso quattro repo open source con changelog curati a mano come ground truth e scelto un intervallo di tag rilasciato per ciascuno, recuperato ai tag fissati: Django 5.2→6.0 (il più grande, 404 commit nel set valutato), Tailwind CSS v4.0.0→v4.1.0, FastAPI 0.116.2→0.117.0 (una trappola a zero breaking change — le sue note curate non hanno una sezione breaking, quindi qualsiasi voce presentata come breaking è un'invenzione), e curl 8.14.1→8.15.0. Due agenti hanno ricevuto lo stesso prompt e lo stesso repo; l'unica differenza era se l'agente leggeva prima questo SKILL.md. Abbiamo valutato copertura commit, voci inventate (verificate meccanicamente contro hash e date reali), recall dei breaking change, conformità di formato, e leggibilità alla cieca.

Intervallo	Braccio	Copertura commit tracciabile	Inventate	Breaking in cima?	Formato (0–6)
Tailwind	base	0/164 (0%)	0	no	3
	skill	143/164 (87%)	0	sì	5
Django	base	23/404 (6%)	0	no	3
	skill	234/404 (58%)	0	sì	6
curl	base	22/278 (8%)	0	sì	3
	skill	59/278 (21%)	0	sì	6
FastAPI	base	12/18 (67%)	0	n/a	4
	skill	9/18 (50%)	0	n/a	6

Dove la disciplina si vede, la skill vince chiaramente. La tracciabilità è la sua tesi centrale e domina: 87% contro 0% su Tailwind, 58% contro 6% su Django. L'agente base scrive prosa fluente che descrive molti cambiamenti reali — semplicemente non riesce a ricollegarli ai commit, che è esattamente il vuoto che la skill esiste per colmare. La conformità di formato era 30/36 sui quattro run della skill contro 13/36 per il base; ogni output base usava intestazioni non-Keep-a-Changelog ("Features", "Notable bug fixes"), perdeva la data ISO, e aggiungeva un epilogo di note. E sul posizionamento dei breaking change, sui tre intervalli che hanno davvero breaking change, la skill li ha messi per primi e marcati BREAKING in tutti e tre; il base lo ha fatto in uno solo (curl).

Sii onesto: la metrica principale è finita in pareggio

Il numero che più volevamo smuovere — le voci inventate — non si è mosso. È stato 0 su tutti e otto gli output. Un pareggio. Ogni citazione con # risolveva a un riferimento reale (fino a 195 in un singolo run della skill), nessuna versione o data inventata, e ogni affermazione di prosa controllata a campione risaliva a un commit, inclusi gli 11 CVE di Django. La ragione è semplice e non la addolciamo: su questo corpus l'agente base era già abbastanza disciplinato da non inventare voci, quindi la garanzia anti-invenzione della skill ha tenuto ma non è mai stata messa sotto stress. Riportiamo il pareggio invece di nasconderlo.

Dove la skill ha perso — pubblicato comunque

La nostra metodologia richiede di mettere le perdite accanto alle vittorie, e ce ne sono state di reali.

Il base ha vinto sulla pura leggibilità sui due repo grandi. Su curl e Django, l'unico valutatore cieco ha preferito l'output base — il suo stile narrativo curato, con una sezione CVE dedicata su Django, si legge meglio del blocco Keep-a-Changelog esaustivo di 230 righe della skill. Il valutatore non poteva vedere che la versione base era intracciabile e sparpagliava i breaking change; sulla sola leggibilità, ha vinto la prosa del base. La skill scambia un po' di leggibilità sulle release enormi per struttura e onestà, e quello scambio si vede.

Il base ha persino battuto la skill sulla copertura tracciabile di FastAPI — 67% contro 50%. Questo è il nostro risultato preferito, perché la skill aveva ragione a perderlo: il base ha citato tre commit interni extra (un bump di mypy, un cambio di cache delle dipendenze, una modifica a pydantic.mypy) che la skill ha correttamente scartato come non rilevanti per l'utente. La metrica ha premiato il base per aver elencato rumore che un utente non dovrebbe vedere. E sul recall dei breaking change di Tailwind, il base ha battuto la skill 4/7 a 3/7 formulando in prosa una deprecazione che la skill ha archiviato sotto Added — fortuna di formulazione su un corpus dove nessun oggetto di commit dice "deprecate".

Due avvertimenti onesti sul benchmark stesso: il punteggio di preferenza cieca ha usato 1 valutatore, non i 3 che specifichiamo, quindi è sottodimensionato. E il costo in token per run non è stato registrato in questa esecuzione — il braccio con skill paga in più per leggere il SKILL.md, e non possiamo ancora dirti quanto.

Installazione

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

Riavvia Claude Code. Si attiva su "scrivi un changelog", "release notes per v2.3", "aggiorna CHANGELOG.md", e "cosa è cambiato tra 1.4 e 2.0" — e resta fuori dai piedi per post di blog, copy di marketing, e scrittura di commit message. Fa parte della serie research-discipline, che taglia quanto una risposta ricercata sbaglia, e token-discipline, che taglia quanto il tuo contesto costa, nella nostra serie discipline benchmarkata.

FAQ

In cosa è diverso da git-cliff o conventional-changelog? Quelli sono tracciabili per costruzione ma vedono solo i conventional commit, quindi il lavoro non conforme viene scartato in silenzio, e si leggono come un log riformattato. Questa skill legge l'intero intervallo — diff inclusi, non solo gli oggetti dei commit — e scrive un linguaggio orientato all'impatto utente pur richiedendo che ogni riga risalga a un commit reale. Tracciabilità e leggibilità, cosa che nessuno strumento nel nostro censimento applicava insieme.

Si limita a scaricare il git log con parole più belle? No — il contrario. Mappa ogni commit a una voce o a un'esclusione consapevole, caccia i breaking change nel diff, raggruppa per intestazioni Keep-a-Changelog, e mette gli elementi breaking per primi con una nota di migrazione. Su FastAPI ha correttamente scartato tre commit interni che l'agente base aveva elencato, il che le è costato un punto di copertura ma era la scelta giusta.

Inventa numeri di versione o date? È costruita per non farlo: l'intestazione di versione è il nome del tag reale e la data è la data reale del tag, letta via git in ISO-8601. Gli intervalli non rilasciati vanno sotto ## [Unreleased] invece che ricevere un numero coniato. Su otto output di benchmark, zero versioni, date o numeri di PR inventati.

Devo fidarmi del benchmark? Fidatene fin dove arriva, e lo diciamo chiaramente: la metrica delle invenzioni è finita in pareggio 0-0 perché l'agente base era già onesto su questo corpus, il punteggio di leggibilità ha usato un valutatore invece di tre, e il costo in token non è stato registrato. Le vittorie che sono solide — tracciabilità, formato, posizionamento dei breaking change — sono valutate meccanicamente contro i changelog umani e riproducibili. Il verdetto completo pubblica ogni cella, perdite incluse.