De commit-message die klopt met de diff — benchmark

Een commit-message is een claim over een diff. "add rate limiting to login" zegt dat de diff rate limiting aan login toevoegde — en óf dat klopt, óf hij raakte ook nog drie andere bestanden die het bericht nooit noemt, óf hij "verbetert performance" die niemand heeft gemeten. Je kunt het niet zien aan het bericht. Je moet de diff lezen, en bijna niemand doet dat. Wij runnen een directory die Claude-skills benchmarkt voor de kost, dus deden we het saaie werk: we lieten Claude commit-messages schrijven voor 15 echte open-source diffs, twee keer elk, en checkten elk bericht tegen de daadwerkelijk gestagede wijzigingen.

Het resultaat is commit-discipline, en hij komt met de voor/na-cijfers erbij: diff-dekking ging van 83% naar 97%, subjectregels pasten binnen 50 tekens bij 15 van de 15 diffs (van 6 van de 15), en verzonnen claims daalden van 1 naar 0. Gratis en MIT-licensed: github.com/Skillproofdev/commit-discipline.

Het gat: iedereen checkt het format, niemand checkt de waarheid

Voordat we een regel schreven, bekeken we 80 commit-gerichte skills in onze index van 16.682 skills, plus de losstaande commit-skills die voor Claude Code gepubliceerd zijn. De formatlaag is een druk, opgelost gebied. Conventional Commits-naleving is universeel. Gebiedende wijs, subjectregels van 50 tekens, BREAKING CHANGE:-footers — gangbaar, goed gedocumenteerd, standaard. Wil je alleen type(scope): subject netjes gevormd, dan doen tientallen skills dat al.

Wat geen van hen afdwingt is de laag eronder: is het bericht waar tegenover de diff? Verklaart het elke logische wijziging die gestaged staat? Verzint het niets — geen geraden motief, geen ongemeten "verbetert performance," geen beschreven wijziging die er niet is? Dat is de eerlijkheidslaag, en die was onbetwist terrein. Elke concurrent laat git diff --cached als een niet-afgedwongen suggestie draaien, of werkt openlijk vanuit bestandslijsten — bestandsnamen, die je vertellen waar iets veranderde maar nooit wat of waarom. commit-discipline maakt het lezen van de volledige diff Regel 1 en verbiedt de bestandsnaam-shortcut ronduit.

Acht regels, vier ervan legt niemand anders vast

De skill is een set harde regels (volledige SKILL.md). De bekende onderdelen worden strikt gedaan: een type verdiend aan wat de diff met gedrag doet, een scope die uit de paden afleidbaar moet zijn (nooit verzonnen), een gebiedende subjectregel van ≤50 tekens, breaking changes in een footer. De onderdelen die niemand anders afdwingt:

1. Diff-dekking-volledigheid. Loop na het opstellen het bericht langs de diff: elke logische wijziging verantwoord, niets beschreven dat niet gestaged staat. Hallucinatiecontrole voor commit-messages.
2. Lees de volledige gestagede diff, nooit bestandsnamen. Regel 1, met de shortcut verboden. Het bericht beschrijft de diff, dus de diff — helemaal — is de input.
3. Een concrete verboden-vaagheidslijst. update, fix stuff, improve, misc, cleanup zonder object, wip, address feedback — geblokkeerd als dragende woorden, elk met een vervangingspatroon (update deps → bump axios 1.6→1.7).
4. Een outputcontract. De oplevering is het bericht alleen, in één codeblok — geen inleiding, geen diff-verslag, geen verrassende Co-Authored-By-footer.

Plus een body die waarom en impact uitlegt in plaats van de diff te herhalen (met een verwijdertest: als een regel gereconstrueerd kan worden door de diff te lezen, schrap hem), en een split-aanbeveling voor diffs met meerdere onderwerpen — concrete bestandsgrenzen en een conceptsubject per commit — in plaats van één overkoepelend bericht dat twee wijzigingen dichtplakt.

De benchmark: 15 echte diffs, originele berichten weggehaald

We haalden 15 fixtures uit curl, redis, express, fastapi, eslint, django, rust-analyzer en astro bij vastgepinde SHA's: features, bugfixes, refactors, twee echte breaking changes, twee ingebouwde diffs met meerdere onderwerpen, docs- en CI-chores, en commits met 400-plus regels over veel bestanden. Elke diff ging naar twee Claude Sonnet-agents met identieke prompts. Het enige verschil: één las eerst deze SKILL.md, de ander niet. We scoorden op drie manieren — mechanische Conventional-Commits-naleving via script, diff-dekking tegen een vooraf vastgelegde gold change list, en blinde A/B-voorkeursbeoordeling.

Metriek	Baseline	Met skill
Spec-naleving (7 mechanische checks, gem.)	91,4%	98,1%
— subject ≤ 50 tekens	40% (6/15)	100% (15/15)
Diff-dekking (t.o.v. gold change lists, gem.)	83,2%	96,7%
Verzonnen claims (totaal over 15)	1	0
Breaking-change-recall (2 fixtures)	2/2	2/2
Split-detectie (2 ingebouwde diffs met meerdere onderwerpen)	0/2	2/2
Blinde A/B-voorkeur (skill vs baseline)	—	9 win / 4 verlies / 2 gelijk

Twee dingen springen eruit. Ten eerste was de mechanische naleving al sterk bij de baseline — correcte types, gebiedende wijs, breaking-footers en niet-vage werkwoorden kwamen al standaard mee. Het hele formatgat zat in de subjectlengte: de baseline overschreed 50 tekens bij 9 van de 15 diffs; de skill nooit. Ten tweede: de echte scheiding zit in dekking. De baseline liet routinematig secundaire wijzigingen vallen — de toegevoegde tests, de changelog-regel, het tweede onderwerp verstopt in een "enkele" diff — terwijl de skill die wel verantwoordde. Die sprong van 83% naar 97% is waar het merendeel van de voorkeurswinsten vandaan kwam, en dat is iets wat geen formatchecker je kan geven.

Split-detectie is de duidelijkste illustratie. Op de twee ingebouwde diffs met meerdere onderwerpen (t05, t12) schreef de baseline elke keer één overkoepelend bericht; de skill stelde beide keren de split voor. Bij t07 — een curl-commit die TLS-SRP verwijdert — ving de skill zelfs een losstaande hunk met zes setopt-wijzigingen die de baseline stilletjes in zijn bericht opnam, wat meteen de enige verzinning van de baseline in deze run was: een verzonnen verwijderingsmotief ("vrijwel ongebruikt") dat de diff niet ondersteunde. De skill markeerde die hunk als een vraag aan de gebruiker in plaats van te gokken.

Waar de skill verloor — toch gepubliceerd

Onze methodologie eist dat de verliezen naast de winsten staan, en dit was geen schone sweep.

De baseline versloeg de skill bij drie fixtures. Bij t03 (redis), t13 (rust-analyzer) en t15 (fastapi) — allemaal strak afgebakende diffs — ving de baseline een specifiek detail dat de skill over het hoofd zag: een verbreed &mut dyn SourceDatabase-traitgrens (t13), een _build_dependant-dedup-extractie (t15), en één van twee diff-telalgoritmes (t03). De volledigheidsdruk van de skill is echt maar niet absoluut; bij kleine diffs met één bestand evenaart of verslaat de baseline hem.

De split-discipline van de skill schoot één keer over. Bij t14 splitste hij een tweeregelige commit met CI plus dependency (Node 26 aan de matrix toevoegen, mocha bumpen) in tweeën — verdedigbaar volgens de letter van "one commit, one concern," maar iets wat de meeste reviewers als één ci:-commit zouden houden. Drie correcte splits, één oversplit. Geteld als een voorkeursverlies en gemarkeerd.

En de kanttekening die het meest telt: n=15 is richtinggevend, niet statistisch significant, en de dekkings- en voorkeursbeoordeling gebeurde door een rechter uit dezelfde modelfamilie — er was geen rechter uit een andere modelfamilie beschikbaar op de testmachine. Voorkeur draagt vooral zelfvoorkeur-risico: schrijver en rechter delen een modelfamilie. We hebben de labels geschud met een vooraf vastgelegde seed en na het scoren gedeblindeerd, maar we gaan een 9-4-2-voorkeurstelling van een rechter uit dezelfde familie niet als vonnis voorstellen. Het is een signaal. Het volledige protocol, de scores per fixture en de openheid over de beoordelingsmethode staan in bench/results/verdict.md.

Installatie

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

Herstart Claude Code. Hij triggert op "commit dit," "schrijf een commit-message," gestagede wijzigingen committen, en verzoeken om berichten te reviewen of op te schonen — en blijft weg bij git-operaties die niets met berichten te maken hebben: branchen, rebasen, conflictoplossing. Hij hoort bij onze discipline-reeks naast token-discipline, dat verlaagt wat een sessie kost, en research-discipline, dat verlaagt wat een antwoord fout heeft. Deze verlaagt wat een commit-message mist.

FAQ

Schrijft Claude niet al redelijke commit-messages? Qua format wel — dat was de verrassing in de benchmark. De baseline had type, gebiedende wijs en breaking-footers al standaard onder de knie. Waar het tekortschoot was dekking: hij liet secundaire wijzigingen vallen bij meer dan de helft van de diffs met meerdere onderwerpen of bestanden, en overschreed de subjectregel van 50 tekens bij 9 van de 15. De taak van de skill is dat gat, niet het format dat iedereen al goed doet.

Is dit gewoon een Conventional Commits-linter? Nee, en dat is precies het punt. Conventional Commits-naleving is een druk, opgelost gebied — tientallen skills doen dat al. commit-discipline dwingt de laag eronder af: dat het bericht elke logische wijziging in de diff verantwoordt en niets verzint. Format is standaard hier; eerlijkheid tegenover de diff is het product.

Gaat hij voor mij committen of pushen? Nee. Het bericht schrijven is de taak; git commit uitvoeren is een aparte instructie die de skill niet zelf oppakt. Hij voegt ook geen Co-Authored-By- of "Generated with"-footers toe, tenzij de log van je project of je eigen instructies laten zien dat je die wilt.

Moet ik de 9-4-2-voorkeur vertrouwen? Behandel het als richtinggevend, niet als vonnis. Het werd beoordeeld door een agent uit dezelfde modelfamilie met geblindeerde labels, omdat er geen rechter uit een andere familie beschikbaar was op de testmachine — dus het draagt zelfvoorkeur-risico, en n=15 is niet statistisch significant. De dekkingscijfers (83%→97%) rusten op een vooraf vastgelegde gold change list en zijn het meer dragende resultaat; de drie fixtures die de skill verloor staan hierboven genoemd.