Changelogs automatisch aus Commits generieren lassen mit Claude

1. Conventional Commits als Grundlage

Jede automatisierte Changelog-Generierung steht und fällt mit der Qualität der zugrunde liegenden Commit-Nachrichten. Die Conventional-Commits-Konvention strukturiert jede Nachricht in einen Typ wie feat, fix, refactor oder chore, einen optionalen Scope in Klammern und eine kurze Beschreibung, ergänzt um einen optionalen Body und Footer für Breaking Changes. Diese Struktur macht Commits maschinell auswertbar, weil ein Typ wie fix eindeutig einer Kategorie im Changelog zugeordnet werden kann, ohne den Freitext interpretieren zu müssen.

Ohne diese Konvention bleibt sowohl klassischen Tools als auch Claude nur die Interpretation von Freitext-Commits, was bei uneinheitlichem Team-Stil zu deutlich schlechteren Ergebnissen führt. Teams, die noch keine Konvention etabliert haben, sollten diese vor der Einführung einer Changelog-Automatisierung festlegen, etwa über einen commit-msg-Hook, der falsch formatierte Commits bereits lokal ablehnt.

# Beispiele für Conventional-Commits-Nachrichten
feat(checkout): Gastbestellung ohne Kundenkonto ermöglichen
fix(cart): doppelte Versandkosten bei mehreren Adressen beheben
refactor(api): ProductRepository von Legacy-Klasse entkoppeln
chore(deps): guzzlehttp/guzzle auf 7.9 anheben

BREAKING CHANGE: Der Endpunkt /api/v1/cart liefert jetzt ein
Array statt eines einzelnen Objekts zurueck.

2. Warum reines Parsing an Grenzen stößt

Klassische Tools wie semantic-release oder conventional-changelog parsen Commit-Typen zuverlässig und generieren daraus rein mechanisch eine gruppierte Liste, meist eins zu eins nach dem Muster Typ, Scope, Beschreibung. Das funktioniert gut für eine technische Rohfassung, liefert aber selten einen Text, den ein Produktmanager oder Endkunde ohne Nacharbeit lesen möchte, weil zusammenhängende Commits nicht erkannt und redundante oder widersprüchliche Einträge nicht bereinigt werden.

Claude ergänzt genau diese Lücke: Statt jeden Commit einzeln aufzulisten, kann das Modell mehrere zusammengehörige Commits, etwa eine Feature-Implementierung mit drei nachfolgenden Bugfix-Commits zum selben Feature, zu einem einzigen, verständlichen Changelog-Eintrag verdichten. Das ist eine semantische Aufgabe, für die reines Pattern-Matching nicht ausreicht, weil sie Kontextverständnis über mehrere Commits hinweg erfordert.

3. Workflow: Commits zwischen zwei Releases einsammeln

Der erste Schritt jeder Changelog-Generierung ist rein mechanisch: Mit git log lassen sich alle Commits zwischen zwei Tags oder Branches abrufen, idealerweise inklusive Commit-Hash, Autor und vollständiger Nachricht, damit Claude bei Bedarf auf den Body und den Footer zugreifen kann. Wichtig ist, Merge-Commits ohne eigenen inhaltlichen Wert herauszufiltern, damit sie die spätere Zusammenfassung nicht unnötig aufblähen.

Diese Rohdaten bilden die alleinige Eingabe für den nächsten Schritt. Claude erhält damit ausschließlich Informationen, die tatsächlich im Repository vorhanden sind, und erfindet keine Funktionen, die nicht committet wurden, solange der Prompt klar auf die gelieferte Commit-Liste als einzige Quelle verweist.

# Alle Commits zwischen zwei Tags sammeln, Merge-Commits ausschliessen
git log v2.3.0..v2.4.0 --no-merges \
  --pretty=format:'%H|%an|%s%n%b%n---' > commits-v2.4.0.txt

wc -l commits-v2.4.0.txt

4. Kategorisierung und Zusammenfassung durch Claude

Sobald die Commit-Liste vorliegt, übernimmt Claude zwei Aufgaben gleichzeitig: die Kategorisierung nach Typ, etwa Neue Funktionen, Fehlerbehebungen und Breaking Changes, sowie die sprachliche Verdichtung technischer Commit-Nachrichten zu Sätzen, die auch ohne Codebasis-Kenntnis verständlich sind. Ein Commit wie fix(cart): race condition bei parallelem addItem behoben wird dabei zu einer nutzerorientierten Formulierung wie Ein seltener Fehler beim gleichzeitigen Hinzufügen mehrerer Artikel zum Warenkorb wurde behoben.

Entscheidend für die Qualität ist ein klar strukturierter Prompt, der die gewünschte Kategorisierung, die Zielgruppe des Changelogs und den gewünschten Detailgrad vorgibt. Ohne diese Vorgaben tendiert das Modell dazu, entweder zu technisch für Endnutzer oder zu oberflächlich für ein technisches Entwicklerteam zu formulieren.

5. Praxisbeispiel: Prompt und Ausgabe für einen Release

In der Praxis hat sich ein zweistufiger Prompt bewährt: Zunächst wird Claude gebeten, jeden Commit einer Kategorie zuzuordnen und thematisch verwandte Commits zu gruppieren, danach folgt ein zweiter Durchlauf, der aus dieser Gruppierung den finalen, für Menschen lesbaren Changelog-Text formuliert. Diese Trennung verbessert die Nachvollziehbarkeit, weil sich die Zwischenkategorisierung separat prüfen lässt, bevor der finale Text erzeugt wird.

Für ein Team, das monatlich release, reicht ein einziger Prompt-Durchlauf pro Release meist aus, während Teams mit mehreren Releases pro Woche von einem automatisierten Skript profitieren, das den zweistufigen Prompt bei jedem Tag-Push auslöst und das Ergebnis als Entwurf in einer Pull-Request-Beschreibung ablegt.

from anthropic import Anthropic

client = Anthropic()

with open("commits-v2.4.0.txt", encoding="utf-8") as f:
    commits = f.read()

prompt = f'''Kategorisiere die folgenden Commits in Neue Funktionen,
Fehlerbehebungen, Breaking Changes und Sonstiges. Fasse thematisch
zusammengehörige Commits zu einem einzigen, für Endnutzer
verständlichen Satz zusammen. Erfinde keine Funktionen, die nicht
in den Commits vorkommen.

Commits:
{commits}'''

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[{"role": "user", "content": prompt}],
)
print(response.content[0].text)

6. Integration in die CI/CD-Pipeline

Für eine dauerhaft nutzbare Lösung lohnt sich die Einbettung in die bestehende Release-Pipeline: Ein Job läuft beim Setzen eines neuen Tags, sammelt die Commits seit dem letzten Tag, ruft die Claude API mit dem oben skizzierten Prompt auf und legt das Ergebnis als Entwurf in einer Datei oder als Kommentar in der zugehörigen Release-Pull-Request ab. Wichtig ist, den generierten Text nicht automatisch und ungeprüft zu veröffentlichen, sondern als Vorschlag zu behandeln, der von einem Menschen bestätigt wird.

In GitLab CI lässt sich ein solcher Job leicht als eigene Stage nach dem Build, aber vor dem eigentlichen Deployment einrichten, sodass der Changelog-Entwurf vorliegt, bevor die neue Version tatsächlich ausgerollt wird. Das gibt dem Team die Möglichkeit, den Text vor der Veröffentlichung noch anzupassen.

# .gitlab-ci.yml (Auszug)
generate-changelog:
  stage: pre-deploy
  image: python:3.12-slim
  rules:
    - if: '$CI_COMMIT_TAG'
  script:
    - pip install anthropic
    - git fetch --tags
    - PREV_TAG=$(git describe --tags --abbrev=0 "$CI_COMMIT_TAG^")
    - git log "$PREV_TAG..$CI_COMMIT_TAG" --no-merges
        --pretty=format:'%H|%an|%s%n%b%n---' > commits.txt
    - python scripts/generate_changelog.py commits.txt > CHANGELOG_DRAFT.md
  artifacts:
    paths: [CHANGELOG_DRAFT.md]

7. Qualitätskontrolle der generierten Texte

Ein automatisch generierter Changelog-Entwurf ersetzt keine menschliche Prüfung, insbesondere weil Claude gelegentlich zwei thematisch ähnliche, aber inhaltlich unterschiedliche Commits fälschlich zusammenfasst oder eine Formulierung wählt, die technisch ungenau ist. Ein kurzer Review-Schritt vor der Veröffentlichung, bei dem ein Entwickler den Entwurf gegen die tatsächlichen Commits gegenliest, bleibt deshalb ein fester Bestandteil des Prozesses, auch wenn er nur wenige Minuten dauert.

Besonders bei Breaking Changes ist diese Prüfung nicht verhandelbar, weil eine ungenaue oder unvollständige Beschreibung einer Breaking Change bei Nutzern zu fehlerhaften Upgrades führen kann. Der Prompt sollte deshalb explizit anweisen, Breaking Changes gesondert, ausführlich und mit konkretem Migrationshinweis zu formulieren, statt sie in der allgemeinen Zusammenfassung untergehen zu lassen.

8. Grenzen und typische Fallstricke

Die größte Fehlerquelle bleibt die Qualität der Eingabedaten: Schlecht formulierte oder inkonsistente Commit-Nachrichten wie Fix oder WIP liefern Claude keine ausreichende Grundlage für eine sinnvolle Kategorisierung, egal wie gut der Prompt formuliert ist. In solchen Fällen hilft nur die Verbesserung der Commit-Disziplin im Team, nicht ein ausgefeilterer Prompt.

Ein weiterer Fallstrick ist die Vermischung mehrerer nicht zusammengehöriger Änderungen in einem einzigen Commit, was Claude dazu zwingt, eine einzige Nachricht künstlich in mehrere Changelog-Kategorien aufzuteilen, was leicht zu Ungenauigkeiten führt. Kleinere, thematisch fokussierte Commits verbessern deshalb nicht nur die Code-Review-Qualität, sondern direkt auch die Qualität der automatisch generierten Changelogs.

9. Best Practices für den Teameinsatz

Wer Changelog-Generierung mit Claude dauerhaft einführen will, sollte zunächst die Commit-Konvention über einen automatisierten Hook durchsetzen, danach den Prompt für die Zielgruppe des Changelogs klar formulieren und schließlich einen verbindlichen, kurzen Review-Schritt vor jeder Veröffentlichung einplanen. Diese drei Bausteine zusammen liefern deutlich konsistentere Ergebnisse als eine einmalige, unstrukturierte Anfrage an das Modell.

Sinnvoll ist außerdem, den Prompt selbst zu versionieren und im Repository abzulegen, damit Änderungen an der Kategorisierungslogik nachvollziehbar bleiben und im Team diskutiert werden können, statt in einer einzelnen Chat-Sitzung verloren zu gehen. Ein solcher Prompt wird damit zu einem echten Teil der Projektinfrastruktur, nicht zu einem einmaligen Experiment.

10. Zusammenfassung

11. FAQ: Changelog-Generierung aus Commits: Das Wichtigste auf einen Blick