Claude Code voor commit-berichten: zet diffs om in heldere commits en release-opmerkingen die gebruikersimpact, risico's en eventuele migratiestappen uitleggen.
Een diff laat zien wat er veranderde, niet waarom het veranderde. Hij kan je vertellen dat een functie is hernoemd, een flag is toegevoegd of een query herschreven is. Hij zegt zelden iets over de intentie, de gebruikersimpact of de afwegingen achter de wijziging.
Diffs verspreiden het verhaal ook over bestanden. Een kleine aanpassing op één plek kan ergens anders een grote gedragsverandering veroorzaken, en reviewers blijven gissen: is dit een bugfix of een gedragswijziging? Is het veilig om terug te porteren? Hebben we een migratie of een feature flag nodig?
Daarom bestaan commit-berichten en changelogs. Ze veranderen ruwe bewerkingen in beslissingen waarmee iemand later kan werken, of dat nu een teamgenoot in code review is, een ontwikkelaar die maanden later een incident debugt, of jijzelf die probeert te begrijpen waarom een release een regressie veroorzaakte.
Een diff kan deze vragen meestal niet zelfstandig beantwoorden:
Tools zoals Claude Code kunnen de diff lezen en een concepttekst opstellen, maar ze hebben nog steeds jouw context nodig. Een diff die “een veld verwijdert” kan veilige opschoning zijn, of het kan een veelgebruikte integratie kapotmaken. Het juiste bericht hangt af van informatie buiten de code.
Het doel is om diffs om te zetten in berichten die impact, risico en migratiestappen vastleggen, met prompt-templates die je hergebruikt voor alledaagse commits en voor release-opmerkingen.
Een goed commit-bericht zou iemand in staat moeten stellen de wijziging te begrijpen zonder de diff opnieuw te lezen. Het moet vertellen wat er veranderde, waarom het veranderde en wat het praktisch betekent.
De meeste sterke commit-berichten behandelen drie dingen:
Implementatiedetails zijn prima, maar alleen wanneer ze helpen bij review of debugging. “Overschakelen naar parameterized query om SQL-injectie te voorkomen” is nuttig. “Refactor services” is dat niet.
Release-opmerkingen zijn anders. Ze zijn voor mensen die het product gebruiken, niet voor mensen die de code schreven. Het doel is iemand te helpen beslissen: moet ik upgraden, wat voelt anders en wat moet ik doen?
Goede release-opmerkingen groeperen wijzigingen op uitkomsten (fixes, verbeteringen, breaking changes). Ze vermijden interne termen zoals “gerefactord”, “bestanden hernoemd” of “handlers verplaatst”, tenzij dat direct gebruikers raakt.
Risico en migraties horen in beide, maar alleen wanneer het ertoe doet. In een commit-bericht helpt een korte risico-opmerking reviewers om aandacht te besteden. In release-opmerkingen moet datzelfde risico in gewone taal worden uitgelegd met een heldere actie.
Migratiedetails zijn het nuttigst wanneer ze praktisch blijven:
Claude Code kan dit snel opstellen wanneer het bewijs in de diff staat. Jij bepaalt nog steeds wat gebruikers zullen merken en wat kan breken.
Claude Code is goed in het omzetten van ruwe diffs naar leesbare tekst. Met een gefocuste change set en een beetje context kan het samenvatten wat veranderde, waarschuwen voor waarschijnlijke gebruikersimpact en commit-berichten of release-opmerkingen opstellen die natuurlijk lezen.
Het is vaak sterk in:
Wat het niet kan weten, is wat niet in de diff staat: productintentie, rollout-plan (flags, gefaseerde uitrol, canary), of verborgen beperkingen (supportafspraken, juridische vereisten, klant-specifiek gedrag). Als een wijziging alleen “veilig” is vanwege iets buiten de code, ziet het dat niet.
Voor het uitrollen moet een mens altijd nog verifiëren:
Een simpel voorbeeld: een diff verwijdert een database-kolom en voegt een nieuwe enumwaarde toe. Claude Code kan opstellen “Verwijder legacy-kolom; voeg statuswaarde toe”, maar alleen jij kunt zeggen of het een breaking change is, hoe bestaande rijen moeten worden gemigreerd en of de uitrol twee stappen nodig heeft.
Een ruwe diff laat zien wat er veranderde, maar zelden waarom, wat gebruikers zullen merken of wat kapot kan gaan. Besteed twee minuten aan het verzamelen van context en je commit-berichten en release-opmerkingen worden veel duidelijker.
Verzamel een paar stukken informatie die antwoorden op: wat was het probleem, wat is het nieuwe gedrag en hoe heb je het geverifieerd. Behandel je prompt als een mini-overdracht naar een teamgenoot die niet aan de wijziging werkte.
Deze inputs zijn meestal het belangrijkst:
Bepaal dan wat je terug wilt. Een enkel commit-bericht is prima voor een kleine, gefocuste wijziging. Meerdere commits maken zin als de diff refactors, gedragswijzigingen en tests mengt. Release-opmerkingen zijn weer anders: die moeten focussen op gebruikersimpact, admin-impact en alles wat iemand na het upgraden moet doen.
Zet grenzen voordat je iets plakt. Verwijder geheimen en alles wat je niet in een publieke repo zou willen: API-sleutels, private tokens, klantnamen, persoonsgegevens, interne hostnames en incidentdetails die niet bedoeld zijn om te delen. Als je de volledige context niet kunt delen, vat het dan veilig samen.
Voorbeeld: een diff voegt een nieuw verplicht veld toe aan een PostgreSQL-tabel en werkt een Go API-handler bij. Voeg het migratiebestand, de handlerwijziging en één zin toe zoals: “Oude clients die het veld weglaten krijgen 400. We rollen eerst clients uit en voeren daarna de migratie uit.” Die ene zin maakt vaak het verschil tussen een veilig bericht en een misleidend bericht.
De kwaliteit die je krijgt hangt af van wat je vraagt. Een goede prompt laat het model de diff als bewijs behandelen en houdt het bericht gebonden aan impact en risico.
Plak de diff (of een kort fragment), voeg dan een klein blok context toe dat de diff niet toont. Houd het kort, maar specifiek:
Vraag om een gestructureerd antwoord zodat je het snel kunt scannen en fouten kunt opmerken voordat je het in Git plakt.
Één diff kan verschillende commit-berichten ondersteunen afhankelijk van wat je wilt benadrukken. Vraag om 2–3 versies zodat je kunt kiezen wat bij je repo past.
Bijvoorbeeld:
Het beste signaal is of de samenvatting overeenkomt met wat de diff daadwerkelijk doet. Als een versie features of fixes noemt die je niet in de code kunt aanwijzen, verwijder die dan.
Een betrouwbaar patroon is om headings te verplichten en “Onbekend” toe te staan wanneer de diff iets niet kan bewijzen.
Probeer: “Geef het uiteindelijke commit-bericht terug met secties: Samenvatting, Motivatie, Impact, Risico, Tests. Als tests niet zichtbaar zijn, zeg ‘Tests: niet getoond’ en stel voor wat te draaien.”
Dat houdt het bericht eerlijk en versnelt reviews, vooral wanneer een wijziging migratiestappen of een zorgvuldige uitrol vereist.
Release-opmerkingen falen wanneer ze als een git-log lezen. Als je bruikbare notities wilt uit meerdere commits of een grote diff, vraag dan eerst wie de lezer is en voeg technische details alleen toe wanneer ze bepalen wat mensen moeten doen.
Geef korte productcontext (wie gebruikt het, welk deel van de app), plak dan diffs of samenvattingen. Vraag om een gestructureerde output die scheidt wat gebruikers ervaren van wat engineers veranderden.
You are writing release notes for [product/app]. Audience: [end users/admins/developers].
Input: the following diffs/commit summaries.
Write release notes with these sections:
1) User-visible changes (what’s new or different)
2) Fixes (symptoms users had, now resolved)
3) Breaking changes (if none, say “None”)
4) Migration steps (numbered, short, actionable)
5) Deprecations (what, when it will be removed, replacement)
6) Risk and rollout notes (what could go wrong, how to verify)
Rules: do not list internal refactors unless they affect behavior. Use plain language.
Dit creëert een duidelijke scheiding tussen gebruikersimpact en interne opschoning, zodat een hernoeming een echte gedragswijziging niet overschaduwt.
Zelfs zorgvuldige modellen missen migraties tenzij je ernaar vraagt. Voeg expliciete vragen toe:
De gewoonte is hetzelfde: vraag altijd om “waarom het belangrijk is” en “wat te doen daarna”, niet alleen “wat veranderde”.
Lees de diff als een reviewer, niet als de auteur. Je taak is codewijzigingen om te zetten in iets waar iemand later op kan vertrouwen: wat veranderde, waarom en wat het betekent.
Als je Claude Code gebruikt, plak dan de diff plus een paar zinnen context (wie is geraakt, wat kapot was, wat je testte) en vraag om output in die structuur. Bewerk het daarna zoals je een door een mens geschreven bericht zou bewerken.
Een snelle formulering maakt het leesbaarder:
Een goed bericht beantwoordt: Wat veranderde? Waarom nu? Wat kan kapot gaan? Hoe weten we dat het werkt? Wat moet iemand doen om het veilig te gebruiken?
Stel je een kleine diff voor die onschuldig lijkt, maar clients kan breken.
- type UserResponse struct {
- FullName string `json:"fullName"`
- }
+ type UserResponse struct {
+ Name string `json:"name"`
+ }
+ if req.Name == "" {
+ return errors.New("name is required")
+ }
Twee dingen gebeurden: een response-field is hernoemd (fullName naar name), en validatie is toegevoegd (name is verplicht). Het werkt het best als je vraagt naar impact, risico en vervolgstappen.
Hier is een concept commit-bericht met de belangrijke context die een diff niet toont:
Rename user response field to `name` and require `name` on create
Why:
- Align API with updated domain naming
Impact:
- Breaking change: clients reading `fullName` must switch to `name`
- Requests without `name` now fail validation
Tests:
- Updated API tests for response payload
- Added validation test for missing name
En een release-opmerking geschreven voor gebruikers, niet voor code:
Breaking: User API field rename and stricter validation
- Response field `fullName` is now `name`
- Create/update requests now require `name`
Migration:
- Update JSON parsing to read `name`
- If you send `fullName`, map it to `name` before calling the API
Verscherp de formulering door gissingen te verwijderen. “Align API with updated domain naming” is vaag. Als je de reden niet weet, zeg dan wat je wel weet, zoals “Naamgeving op meerdere endpoints standaardiseren.” Vermijd ook tests te noemen die je niet hebt uitgevoerd. Vervang “Updated API tests” door de suite-naam of een eerlijke opmerking zoals “Handmatige check: gebruiker aangemaakt via API en payload gecontroleerd.”
De snelste manier om vertrouwen in AI-geschreven commits te verliezen is het bericht meer te laten beloven dan de diff levert. Claude Code kan ruwe wijzigingen omzetten in duidelijk tekst, maar het zal ook “gebruikersgerichte verbeteringen” afleiden uit een interne refactor tenzij je het grondt.
Een veelgemaakte fout is de impact overschatten. Een hernoeming, een nieuwe helper of het verplaatsen van logica tussen bestanden kan als een feature klinken terwijl het alleen plumbing is. Als release-opmerkingen “betere performance” claimen zonder meting of gebruikerssymptoom, merkt men dat.
Een andere fout is breaking changes en migraties missen. Diffs verbergen ze op kleine plekken: een config-standaard is veranderd, een env-var hernoemd, een database-kolom NOT NULL gemaakt, of een response-veld verwijderd. Als commit-bericht en changelog niet zeggen wat iemand na update moet doen, verandert je “schone” release snel in een supportticket.
Vage bewoordingen zijn ook riskant. “Kleine verbeteringen” en “verschillende fixes” verbergen risico in plaats van het te communiceren.
Valkuilen om op te letten wanneer je diffs in een prompt plakt:
Een goede correctie is een “bewijs”-mentaliteit afdwingen. Als de diff een API-veld hernoemt, moet de release-opmerking zeggen wat clients moeten hernoemen en of oude clients breken.
Vraag voordat je de output accepteert om een tweede versie die:
Lees je commit-bericht alsof je de code niet hebt geschreven. Als het niet in eenvoudige woorden de wijziging uitlegt, helpt het niet tijdens een hotfix. Als je Claude Code gebruikte, doe dan een korte controle of het overeenkomt met wat er daadwerkelijk veranderde.
Als het bericht details bevat die niet in de diff of ticket staan, verwijder ze. Een korte, duidelijke “waarom” is beter dan een lange anekdote.
Release-opmerkingen zijn voor lezers die de PR niet zagen.
Verwijder of herschrijf voordat je shipt:
Als je de wijziging niet kunt uitleggen zonder te gokken, pauzeer en voeg eerst de ontbrekende context toe.
Consistentie is belangrijker dan perfectie. Kies een klein format waar je team zich aan houdt voor elke wijziging, zelfs op drukke dagen. Wanneer iedereen in dezelfde vorm schrijft, gaan reviews sneller en stoppen release-opmerkingen met detectivewerk te worden.
Een lichtgewicht format dat werkt:
Gebruik Claude Code om te draften en doe daarna een korte menselijke controle op waarheid en context. Het is het sterkst wanneer je het de diff plus 2–3 zinnen intentie geeft: voor wie is de wijziging, wat probeer je te verbeteren en wat verander je bewust niet.
Om dit op te schalen zonder extra meetings, bouw het in plekken die je al gebruikt: een korte commit- of PR-template met die velden, een checkbox voor migratie en risico, en reviewcomments die focussen op ontbrekende impact in plaats van schrijfstijl.
Als je bouwt in Koder.ai (koder.ai), past dezelfde structuur natuurlijk in de planningsmodus. Schrijf eerst de intentie (impact, risico, migratie) en implementeer daarna tegen dat plan zodat de “waarom” niet verloren gaat zodra de code beweegt.
Schrijf een bericht dat drie dingen dekt:
Voeg Risico, Migratie en Tests alleen toe wanneer het ertoe doet of wanneer je twijfelt.
Omdat een diff laat zien wat er bewerkt is, niet wat de intentie was. Een diff vertelt meestal niet:
Een goed bericht zet de diff om in een beslissing waarop iemand later kan vertrouwen.
Geef de diff plus een klein contextblok dat de diff niet laat zien:
Als je alleen de diff plakt, krijg je vaak een gepolijste samenvatting die het echte risico mist of de impact overdrijft.
Vraag om een gestructureerde output zodat je het snel kunt verifiëren:
Sta ook eerlijke leemtes toe zoals “Tests: niet getoond” zodat het concept niets beweert dat niet verifieerbaar is.
Vraag 2–3 varianten, bijvoorbeeld:
Kies daarna wat het beste bij je repo-stijl past en wat niet iets beweert dat je niet kunt onderbouwen.
Ze zijn voor verschillende lezers:
Als een regel niet relevant is voor een gebruiker, hoort die waarschijnlijk niet in de release-opmerkingen.
Roep het expliciet uit en maak het actiegericht:
Neem alleen de stappen op die iemand echt moet uitvoeren, in volgorde:
Als er geen migratie is, zeg “Migratie: Geen” zodat lezers niet blijven twijfelen.
Behandel het als een claim-check:
Als iets op een gok lijkt, herschrijf het als onzekerheid of verwijder het.
Plak niets dat je niet elders zou willen terugzien. Verwijder of vat samen:
Als volledige context gevoelig is, geef dan een veilige samenvatting zoals “validatie aangescherpt; oude clients krijgen mogelijk 400 tot ze geüpdatet zijn.”
Vermijd vage frasen zoals “kleine wijzigingen” wanneer een upgrade daadwerkelijk kan falen.