Il commit message che combacia col diff, benchmarkato

Un commit message è un'affermazione su un diff. "add rate limiting to login" dice che il diff ha aggiunto rate limiting al login — e o è vero, o ha toccato anche altri tre file che il messaggio non menziona mai, o "migliora le performance" senza che nessuno le abbia misurate. Non puoi saperlo leggendo il messaggio. Devi leggere il diff, e quasi nessuno lo fa. Gestiamo una directory che testa le skill di Claude sul campo, quindi abbiamo fatto la cosa noiosa: abbiamo fatto scrivere a Claude i commit message per 15 diff reali open source, due volte ciascuno, e abbiamo controllato ogni messaggio contro le modifiche staged effettive.

Il risultato è commit-discipline, e arriva con i numeri prima/dopo allegati: la copertura del diff è passata dall'83% al 97%, l'oggetto è entrato in 50 caratteri su 15 diff su 15 (contro 6 su 15), e le affermazioni inventate sono scese da 1 a 0. È gratis e con licenza MIT: github.com/Skillproofdev/commit-discipline.

Il vuoto: tutti controllano il formato, nessuno controlla la verità

Prima di scrivere una riga abbiamo passato in rassegna 80 skill focalizzate sui commit nel nostro indice di 16.682 skill, più le skill standalone pubblicate per Claude Code. Il livello del formato è uno spazio affollato e risolto. La conformità a Conventional Commits è universale. Modo imperativo, oggetti a 50 caratteri, footer BREAKING CHANGE: — comuni, ben documentati, dati per scontati. Se vuoi solo un type(scope): subject formattato bene, decine di skill lo fanno già.

Quello che nessuna applica è il livello sottostante: se il messaggio è vero rispetto al diff. Copre ogni cambiamento logico effettivamente staged? Non inventa nulla — nessun motivo indovinato, nessun "migliora le performance" non misurato, nessun cambiamento descritto che non esiste davvero? Questo è il livello dell'onestà, e nel campo non lo occupava nessuno. Ogni concorrente o esegue git diff --cached come suggerimento non vincolante, oppure lavora apertamente da liste di file — nomi di file, che dicono dove è cambiato qualcosa ma mai cosa o perché. commit-discipline rende la lettura dell'intero diff la Regola 1 e vieta del tutto la scorciatoia dei nomi file.

Otto regole, quattro delle quali nessun altro le codifica

La skill è un insieme di regole rigide (SKILL.md completo). Le parti familiari sono applicate con rigore: un type ricavato da cosa il diff fa al comportamento, uno scope che deve essere derivabile dai path (mai inventato), un oggetto imperativo ≤50 caratteri, breaking change in un footer. Le parti che nessun altro applica:

1. Completezza della copertura diff. Dopo la bozza, confronta il messaggio col diff: ogni cambiamento logico coperto, niente descritto che non è staged. Controllo delle allucinazioni per i commit message.
2. Leggi l'intero diff staged, mai i nomi file. Regola 1, con la scorciatoia vietata. Il messaggio descrive il diff, quindi il diff — tutto — è l'input.
3. Una lista concreta di vaghezze bandite. update, fix stuff, improve, misc, cleanup senza oggetto, wip, address feedback — bloccate come parole portanti, ciascuna con uno schema di sostituzione (update deps → bump axios 1.6→1.7).
4. Un contratto d'output. Il risultato è il messaggio da solo in un blocco di codice — nessun preambolo, nessuna cronaca passo-passo del diff, nessun footer Co-Authored-By a sorpresa.

Più un corpo che spiega perché e impatto invece di ripetere il diff (con un test di eliminazione: se una riga può essere ricostruita leggendo il diff, va tagliata), e una raccomandazione di split per diff multi-concern — confini di file concreti e un oggetto di bozza per commit — invece di un unico messaggio ombrello che copre due cambiamenti.

Il benchmark: 15 diff reali, messaggi originali rimossi

Abbiamo estratto 15 fixture da curl, redis, express, fastapi, eslint, django, rust-analyzer e astro a SHA fissi: feature, bugfix, refactor, due breaking change genuine, due diff multi-concern piantati, chore di documentazione e CI, e commit multi-file oltre le 400 righe. Ogni diff è andato a due agenti Claude Sonnet con prompt identici. L'unica differenza: uno leggeva prima questo SKILL.md, l'altro no. Abbiamo valutato in tre modi: conformità meccanica a Conventional Commits via script, copertura del diff contro una lista di cambiamenti gold pre-registrata, e giudizio di preferenza A/B alla cieca.

Metrica	Baseline	Con skill
Conformità allo spec (7 controlli meccanici, media)	91,4%	98,1%
— oggetto ≤ 50 caratteri	40% (6/15)	100% (15/15)
Copertura diff (vs liste gold, media)	83,2%	96,7%
Affermazioni inventate (totale su 15)	1	0
Recall breaking change (2 fixture)	2/2	2/2
Rilevamento split (2 diff multi-concern piantati)	0/2	2/2
Preferenza A/B alla cieca (skill vs baseline)	—	9 vittorie / 4 sconfitte / 2 pareggi

Due cose spiccano. Primo, la conformità meccanica era già forte al baseline — type corretti, modo imperativo, footer breaking e verbi non vaghi uscivano già di serie. L'intero vuoto sul formato era la lunghezza dell'oggetto: il baseline sforava i 50 caratteri su 9 diff su 15; la skill mai. Secondo, la vera separazione è la copertura. Il baseline perdeva regolarmente i cambiamenti secondari — i test aggiunti, la voce di changelog, il secondo concern nascosto in un diff "singolo" — mentre la skill li copriva. Quel salto dall'83% al 97% è da dove è arrivata la maggior parte delle preferenze vinte, ed è la cosa che nessun format-checker può darti.

Il rilevamento degli split è l'esempio più pulito. Sui due diff multi-concern piantati (t05, t12), il baseline ha scritto un messaggio ombrello ciascuno; la skill ha proposto lo split in entrambi i casi. Su t07 — un commit di curl che rimuove TLS-SRP — la skill ha persino colto un hunk di sei setopt non correlato che il baseline aveva silenziosamente assorbito nel suo messaggio, che è stata l'unica invenzione del run del baseline: una motivazione di rimozione inventata ("virtually unused") che il diff non supportava. La skill ha segnalato quell'hunk come domanda all'utente invece di indovinare.

Dove la skill ha perso — pubblicato comunque

La nostra metodologia richiede di mettere le perdite accanto alle vittorie, e questo non è stato un dominio netto.

Il baseline ha battuto la skill su tre fixture. Su t03 (redis), t13 (rust-analyzer) e t15 (fastapi) — tutti diff con scope stretto — il baseline ha colto un dettaglio specifico che la skill ha sfiorato: un bound del trait &mut dyn SourceDatabase allargato (t13), un'estrazione di deduplicazione _build_dependant (t15), e uno dei due algoritmi di conteggio diff (t03). La pressione di completezza della skill è reale ma non assoluta; sui diff piccoli a file singolo il baseline pareggia o batte.

La disciplina di split della skill ha sparato in eccesso una volta. Su t14 ha splittato un commit CI-più-dipendenza di due righe — aggiungi Node 26 alla matrice, aggiorna mocha — in due, difendibile alla lettera di "un commit, un concern" ma qualcosa che la maggior parte dei reviewer terrebbe come un unico commit ci:. Tre split corretti, uno eccessivo. Contato come sconfitta di preferenza e segnalato.

E l'avvertimento più importante: n=15 è indicativo, non statisticamente significativo, e la valutazione della copertura e della preferenza è stata fatta da un giudice della stessa famiglia di modello — nessun giudice di classe GPT di famiglia diversa era configurato sulla macchina di test. La preferenza in particolare porta un rischio di auto-preferenza: chi scrive e chi giudica condividono la famiglia di modello. Abbiamo mescolato le etichette con un seed pre-registrato e sbloccato dopo la valutazione, ma non facciamo finta che un punteggio di preferenza 9-4-2 da un giudice della stessa famiglia sia un verdetto. È un segnale. Il protocollo completo, i punteggi per fixture e la dichiarazione sul metodo di giudizio sono in bench/results/verdict.md.

Installazione

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

Riavvia Claude Code. Si attiva su "commit this," "write a commit message," commit di modifiche staged, e richieste di revisione o pulizia dei messaggi — e resta fuori dai piedi per le operazioni git che non riguardano i messaggi: branching, rebase, risoluzione conflitti. Fa parte della nostra serie discipline insieme a token-discipline, che taglia quanto costa una sessione, e research-discipline, che taglia quanto una risposta sbaglia. Questa taglia quanto un commit message si perde.

FAQ

Claude non scrive già commit message decenti? Per il formato sì — è stata la sorpresa del benchmark. Il baseline ha azzeccato type, modo e footer breaking già di serie. Dove è mancato è la copertura: ha perso i cambiamenti secondari su più della metà dei diff multi-concern e multi-file, e ha sforato l'oggetto a 50 caratteri su 9 diff su 15. Il lavoro della skill è colmare quel vuoto, non il formato che tutti già fanno bene.

È solo un linter di Conventional Commits? No, ed è proprio questo il punto. La conformità a Conventional Commits è uno spazio affollato e risolto — decine di skill lo fanno. commit-discipline applica il livello sottostante: che il messaggio copra ogni cambiamento logico nel diff e non inventi nulla. Il formato qui è dato per scontato; l'onestà rispetto al diff è il prodotto.

Farà il commit o il push al posto mio? No. Scrivere il messaggio è il lavoro; eseguire git commit è un'istruzione separata che la skill non prende di sua iniziativa. Non aggiunge nemmeno footer Co-Authored-By o "Generated with" a meno che il log del tuo progetto o le tue stesse istruzioni non mostrino che li vuoi.

Devo fidarmi del punteggio 9-4-2? Trattalo come indicativo, non come un verdetto. È stato valutato da un agente della stessa famiglia di modello con le etichette bloccate, perché nessun giudice di famiglia diversa era disponibile sulla macchina di test — quindi porta un rischio di auto-preferenza, e n=15 non è statisticamente significativo. I numeri di copertura (83%→97%) poggiano su una lista di cambiamenti gold pre-registrata e sono il risultato più portante; le tre fixture in cui la skill ha perso sono nominate sopra.