Warum unbewiesene Code-Logik gefährlicher ist als schlechter Code

In jedem größeren Softwareprojekt sammelt sich irgendwann Code an, der zwar läuft, aber niemand mehr vollständig versteht. Nicht weil die Entwickler:innen unfähig wären, sondern weil die Logik nie dokumentiert wurde. Während wir uns über Codequalität, Lesbarkeit oder KI-generierte Skripte streiten, übersehen wir oft das eigentliche Problem: Kann das Repository überhaupt beweisen, was es tun soll?

Git zeigt uns Änderungen, Commits und Verantwortliche – aber nicht die Begründung hinter einer Funktion. Ein historischer Commit mag erklären, was sich geändert hat, doch selten, warum diese Logik existiert. Das ist kein kleines Detail. Es ist der Unterschied zwischen einem System, das wir kontrollieren, und einem, das uns kontrolliert.

Code ≠ Verhalten: Das stille Versagen der Code-Historie

Ein Repository ist ein Archiv von Änderungen, nicht von Entscheidungen. Tools wie Git liefern uns:

• Wer hat diese Datei wann bearbeitet?
• Welche Zeilen wurden hinzugefügt oder entfernt?
• Welche Tests wurden zuletzt geändert?

Doch sie beantworten nicht:

• Warum verarbeitet diese Funktion Duplikate von Webhooks?
• Welche Auswirkungen hätte eine Änderung der Retry-Logik auf mobile Clients?
• Ist die aktuelle Timeout-Einstellung eine temporäre Lösung oder ein kritisches Feature?

Diese Fragen leben oft nur in Köpfen einzelner Teammitglieder – oder sind längst in Slack-Archiven oder vergessenen Jira-Tickets verschollen. Das Problem verschärft sich, je älter ein System wird. Was einst klar war, wird zur stillen Annahme. Und stille Annahmen sind die Brutstätte von Bugs.

KI verschärft das Problem – löst es aber nicht aus

KI-Tools wie Coding-Assistenten oder Agenten generieren Code, der syntaktisch korrekt und testbar ist. Doch sie erzeugen keine Erklärung für das Verhalten. Ein klassisches Beispiel:

if (user.country === "US" && order.total > 0) {
  enableManualReview = true;
}

Warum existiert diese Bedingung? Ist es eine Steuerregel? Ein Betrugspräventionsmechanismus? Ein Relikt aus einer längst abgeschlossenen Promotion? Niemand weiß es. Jetzt kommt ein KI-Tool ins Spiel: Es sieht die Logik und versucht, sie zu "optimieren". Eine saubere Code-Änderung, ein Review, das die Tests besteht – und plötzlich funktioniert etwas nicht mehr, weil die ursprüngliche Intention verloren ging.

Das Paradoxe: KI beschleunigt die Code-Produktion, aber nicht das Systemverständnis. Teams generieren mehr Code, während die Dokumentation der Begründung hinter dem Code immer lückenhafter wird.

Green Tests sind kein Freibrief für Verständnis

Tests sind essenziell – doch sie beweisen nur, was jemand bewusst geprüft hat. Ein Test kann bestätigen, dass eine API einen Statuscode 200 zurückgibt. Aber er prüft nicht:

• Ob die Funktion idempotent sein muss (weil der Zahlungsanbieter Retries durchführt).
• Ob die Timeout-Einstellung existiert, weil mobile Apps auf eine bestimmte Antwortzeit angewiesen sind.
• Ob Änderungen an der Logik unerwartete Nebenwirkungen in anderen Systemteilen haben.

Ein grüner Test-Suite bedeutet oft nur: „Die Checks, die wir geschrieben haben, bestehen noch.“ Nicht: „Das Verhalten, das Nutzer:innen erwarten, ist weiterhin sichergestellt.“

Die neue Frage im Code-Review: Wo ist die Beweiskette?

Traditionelle Code-Reviews prüfen Syntax, Sicherheit und Testabdeckung. Doch bei riskanten Änderungen sollte eine zentrale Frage hinzukommen:

Welches Verhalten soll diese Änderung bewahren – und wo ist der Beweis dafür?

Stellen Sie sich vor, ein Pull Request ändert die Logik für Rechnungs-Webhooks. Eine klassische Review würde fragen:

• Ist der Code korrekt?
• Gibt es Tests?
• Ist die Implementierung sicher?

Doch die entscheidende Frage fehlt:

• Beeinflusst diese Änderung das Verhalten bei Duplikaten?
• Wird die Retry-Logik des Zahlungsanbieters korrekt berücksichtigt?
• Gibt es Tests, die die Idempotenz der Webhooks explizit prüfen?

Ohne solche Beweise basiert die Zustimmung zum Merge nur auf Vertrauen – und Vertrauen ist kein Ersatz für Beweise.

Dokumentation ist nur der erste Schritt – Beweise sind der nächste

Viele Teams reagieren auf dieses Problem mit mehr Dokumentation. READMEs, Wiki-Seiten oder ADRs (Architecture Decision Records) sind wertvoll, solange sie aktuell bleiben. Doch Dokumentation hat einen kritischen Nachteil: Sie driften.

Ein README sagt vielleicht: „Webhooks sind idempotent.“ Doch was bedeutet das konkret?

• Welche Tests prüfen die Idempotenz?
• Welche Code-Pfade sind betroffen?
• Gibt es Ausnahmen oder Edge Cases?

Eine bessere Lösung ist evidenzbasierte Dokumentation, die direkt mit dem Code verknüpft ist:

• Hier ist die Behauptung (z. B. „Retries sind sicher“).
• Hier ist der Beweis (z. B. ein Test, der Duplikate simuliert).
• Hier sind die Dateien und Funktionen, die dies gewährleisten.

Ein Repository sollte in der Lage sein, zu sagen: „Hier ist, was wir wissen – und hier ist, was wir nicht wissen.“ Das ist ehrlicher als die Illusion von Vollständigkeit.

Ein „Verständnis-Score“ für Repositories?

Wir messen Testabdeckung, Build-Zeit oder Sicherheitsrisiken – doch selten, ob ein Repository seine eigene Logik erklären kann. Ein hypothetischer „Understanding Score“ könnte Bereiche wie diese bewerten:

• Authentifizierung: Starke Beweiskette (Tests, Dokumentation, Decision Records).
• Rechnungs-Webhooks: Teilweise Beweise (einige Tests, aber keine ADRs).
• Datei-Uploads: Schwache Dokumentation (keine klaren Anforderungen).
• Admin-Berechtigungen: Unklar (keine Tests, keine Dokumentation).

Dieser Score wäre kein Bewertungsinstrument, sondern ein Frühwarnsystem. Er würde Teams auf Bereiche aufmerksam machen, in denen das Vertrauen in den Code größer ist als die tatsächliche Beweiskette.

Das eigentliche Flaschenhals-Problem

KI wird den Code schneller und billiger machen. Doch Verständnis lässt sich nicht automatisieren. Solange Repositories keine Beweise für ihre eigene Logik liefern können, bleiben wir abhängig von:

• Dem Gedächtnis einzelner Entwickler:innen.
• Verstreuten Slack-Nachrichten aus dem Jahr 2022.
• Unvollständigen Dokumentationen, die niemand pflegt.

Die größte Gefahr ist nicht schlechter Code – sondern Code, den niemand mehr versteht.

Die Zukunft der Softwarewartung liegt nicht in mehr Dokumentation, sondern in Systemen, die sich selbst erklären können. Bis dahin bleibt die wichtigste Frage im Code-Review nicht nur „Funktioniert es?“ – sondern „Können wir beweisen, dass es funktioniert?“