Git als Dokumentation: So vermeidest du Chaos für Stakeholder

Als frisch gebackener Softwareentwickler schrieb ich anfangs Commit-Nachrichten wie diese:

feat: build core payment feature

fix: broken links

Sie waren ehrlich und wurden akzeptiert. Doch sobald das Team wuchs oder Investoren und Auditoren nach den Gründen für eine Änderung fragten, die vor Monaten stattfand, reichte ein fix: broken links nicht mehr aus. Plötzlich wurde aus einer simplen Nachricht ein Risiko.

Spätestens wenn du mehr Zeit in veraltete Slack-Kanäle und unstrukturierte Notion-Seiten investierst als in die eigentliche Entwicklung, wird klar: Dokumentation ist kein Luxus, sondern eine Notwendigkeit. Und Git ist in 99 % der Fälle die einzige zuverlässige Dokumentation – wenn man sie richtig nutzt.

Wann Git-Disziplin wirklich zählt

Nicht jedes Projekt verlangt nach strengen Commit-Regeln. Ein internes Tool, ein Prototyp oder eine Datenpipeline, die nur zwei Personen nutzen, kommen auch mit vagen Commit-Nachrichten aus. Doch sobald Stakeholder wie CEOs, Investoren oder externe Prüfer ins Spiel kommen, wird Git zur verbindlichen Quelle der Wahrheit.

Die Faustregel lautet: Wenn das Projekt überwacht wird, auf langfristige Wartung ausgelegt ist oder von Mikromanagement betroffen ist, sind klare Commit-Strukturen unverzichtbar.

Warum Git die beste Dokumentation ist

Externe Tools wie Wikis oder Runbooks mögen für Architekturentscheidungen oder geschäftliche Rahmenbedingungen sinnvoll sein. Doch kein Dokument bleibt so zuverlässig mit dem Code synchron wie Git. Maschinen – sei es ein KI-Agent, ein automatischer Changelog-Parser oder ein technischer Prüfer – lesen heute primär die Commit-Historie.

Wenn du technische Entscheidungen oder Implementierungsdetails in Notion oder Confluence festhältst, besteht immer die Gefahr, dass sie veralten oder verloren gehen. Git hingegen ist die einzige Instanz, die garantiert zum aktuellen Code passt. Nutze diese Eigenschaft.

1. Commit-Struktur: Mehr Kontext, weniger Rätsel

Generische Commit-Nachrichten wie feat: add Stripe support sind zwar besser als nichts, aber sie geben kaum Aufschluss über die tatsächlichen Änderungen. Scoped Commits hingegen schaffen eine klare Struktur – besonders, wenn du Tools wie git log --grep nutzt.

Die Conventional Commits-Konvention hilft dabei, sofortigen Kontext zu liefern. Statt:

feat: add Stripe support

sollte es heißen:

feat(payments): add Stripe integration for subscription billing

Und ein Bugfix nicht einfach:

fix: broken links

sondern:

fix(payments): add missing idempotency key in Stripe webhook

So lassen sich Änderungen sofort filtern und nachvollziehen – etwa alle Commits, die das Zahlungssystem betreffen.

2. Pull Requests: Nicht nur Code, sondern eine Geschichte

Ein Pull Request (PR) ist mehr als ein Code-Snapshot. Er sollte eine schlüssige Erzählung sein, die Geschäftsziele, technische Entscheidungen und Testergebnisse verbindet. Hier die wichtigsten Regeln:

• Begrenzte Größe: Halte PRs unter 200 bis 300 Zeilen, um Review-Prozesse effizient zu gestalten.

• Geschäftszweck erklären: Beschreibe nicht nur das Wie, sondern das Warum. Warum wurde diese Änderung vorgenommen? Welches Problem löst sie?

• Beweise liefern: Füge Screenshots, Videos oder Terminal-Ausgaben bei, um die Funktionsweise zu demonstrieren.

• Verknüpfung herstellen: Nenne die Ticket-Nummer im PR-Titel (z. B. feat(payments): add Stripe integration #125). So entsteht eine bidirektionale Verbindung zwischen Aufgabe und Code.

• Draft-Modus nutzen: Markiere PRs als Work in Progress, bis sie bereit für Reviews sind.

• Eigenrevision vorab: Prüfe deinen eigenen PR, bevor du ihn zur Review freigibst.

• Diszipliniertes Squashing: Nach dem Review sollten Fixup-Commits mit den Hauptcommits zusammengefasst werden, um die Historie sauber zu halten.

3. Commit-Body: Der unsichtbare Mehrwert

Die meisten Entwickler behandeln Commit-Nachrichten wie eine SMS – kurz und ohne Details. Dabei liegt hier der größte Wert: im Commit-Body. Besonders bei großen Features oder Refactorings lohnt es sich, die technischen Entscheidungen und Trade-offs festzuhalten.

Ein Beispiel:

feat(payments): implement PayPal strategy in Payment Gateway

- Added PayPal to PaymentService strategy pattern implementation.
- Extended PaymentService test suite to cover multi-provider edge cases.
- Implemented Circuit Breaker pattern to handle PayPal API downtime.

Note: This was a priority request from the sales team to unblock the European market expansion.

Für kleine Bugfixes mag das übertrieben wirken. Doch bei architektonischen Änderungen oder geschäftskritischen Features ist dieser Aufwand Gold wert – er dokumentiert die verwendeten Artefakte und die getroffenen Kompromisse zum Zeitpunkt der Umsetzung.

4. Branches: Klarheit durch präzise Namensgebung

Branches sind isolierte Arbeitsumgebungen, die es Teams ermöglichen, parallel an verschiedenen Features zu arbeiten, ohne sich gegenseitig zu behindern. Doch ihre volle Kraft entfalten sie nur, wenn sie sinnvoll benannt werden.

• Keine Commits in `main`: Die main-Branch ist heilig – sie repräsentiert die produktive Version, die dem Unternehmen Umsatz bringt.

• Zweck im Namen: Ein Branch wie feat/payments-paypal oder fix/auth-login-loop verrät dem Team sofort, woran gearbeitet wird – ohne Code öffnen zu müssen.

• Verknüpfung zu Tickets: Branches nach Ticket-Nummern zu benennen (z. B. feature/PROJECT-125) schafft eine permanente Verbindung zwischen Geschäftsanforderungen und technischer Umsetzung.

Fazit: Git als Produktgedächtnis

Git ist weit mehr als ein reines Versionskontrollsystem – es ist das kollektive Gedächtnis deines Produkts. Indem du Commit-Nachrichten strukturierst, Pull Requests als narratives Werkzeug nutzt und Branches bewusst benennst, vermeidest du endlose Diskussionen in Slack oder veraltete Dokumentationen.

Eine klare Git-Historie macht dein Produkt nicht nur für neue Entwickler, sondern auch für CEOs oder automatisierte Systeme verständlich. Und das spart Zeit, reduziert Fehler und schafft Vertrauen.

Ich arbeite derzeit an einem Tool namens Fabric, das GitHub-Commits in verständliche Berichte für nicht-technische Manager verwandelt. Weitere Informationen folgen.