KI-Coding-Agenten
Code-Entropie: Wie CI-Checks verhindern, dass KI Altlasten anhäuft
Das Gesetz, nach dem die Komplexität von Code von selbst wächst, gilt weiterhin; KI hat es nur beschleunigt. Hier sind sieben Ebenen von CI-Checks, die verhindern, dass sich Altlasten anhäufen, in der Reihenfolge, in der ich sie einführe.
Entropie wächst von selbst. In der Physik ist das der zweite Hauptsatz der Thermodynamik. In der Softwareentwicklung sieht es ähnlich aus: Unordnung entsteht mühelos, Ordnung kostet Arbeit.
So war es schon immer. Wenn ein Projekt wächst, wächst auch seine Komplexität: Altlasten häufen sich, das Projekt wird schwerer zu warten, jede Änderung wird mühsamer, und das Risiko, etwas kaputt zu machen, steigt stetig. 1974 hat Manny Lehman das als Gesetz der Softwareevolution festgehalten: Die Komplexität eines Systems nimmt zu, solange niemand daran arbeitet, sie zu verringern. KI hat daran nichts geändert. Sie hat nur dafür gesorgt, dass sich Altlasten schneller anhäufen.
Sie wollen Code so einfach wie möglich halten, und genau dabei helfen CI-Checks.
- 1Toter Codelässt den Build scheitern
- 2Linter und Formatiererlässt den Build scheitern
- 3Statische Analyselässt den Build scheitern
- 4Unit-Tests und Abdeckunglässt den Build scheitern
- 5Komplexität und Duplikatelässt den Build scheitern
- 6Architektur und Kopplunglässt den Build scheitern
- 7Schriftliche Regeln (AGENTS.md)von der CI nicht erzwungen
1. Toter Code
Der einfachste Schritt: löschen, was nicht mehr genutzt wird. Auch das lässt sich automatisieren. Nehmen Sie ein Tool, das toten Code findet, in die CI auf (vulture für Python, knip für JS/TS), und ungenutzter Code lässt den Build einfach scheitern.
2. Linter und Formatierer
Als Nächstes kommt der Linter: phpcs für PHP, ruff für Python, ESLint und Prettier für JS/TS und so weiter. Jede Sprache hat ihren eigenen Codestil, und welchen Sie wählen, ist zweitrangig. Wichtig ist, keine Zeit und kein Geld mehr mit dem Lesen von Code und Review-Kommentaren wie „bitte doppelte Anführungszeichen durch einfache ersetzen“ zu verschwenden. Einigen Sie sich einmal auf den Stil, und ab dann prüft die CI ihn automatisch.
3. Statische Analyse
Die nächste Ebene sind statische Analysetools: PHPStan für PHP, mypy für Python, tsc für JS/TS. Eine strenge statische Typprüfung fängt einfache Fehler ab: einen String, wo eine Zahl erwartet wurde, oder einen Wert, von dem man vergessen hat, dass er leer sein kann. Ihre Logik prüft sie nicht, aber sie beseitigt eine ganze Klasse von Fehlern. Leere Werte sind der klassische Fall: Tony Hoare, der die Null-Referenz erfunden hat, nannte sie seinen „Milliarden-Dollar-Fehler“, und laut den Daten von Harness aus dem Jahr 2020 gehörte die NullPointerException in 70 % der untersuchten Java-Produktionsumgebungen noch immer zu den zehn häufigsten Exceptions.
4. Unit-Tests und 80 Prozent Abdeckung
Warum? Weil sich schlechter Code nur sehr schwer mit Unit-Tests abdecken lässt. Damit Code testbar wird, müssen Sie ihn in einzelne Klassen und Funktionen aufteilen, über Kopplung und Schnittstellen nachdenken, entscheiden, was öffentlich und was privat bleibt, Dependency Injection nutzen und globalen Zustand vermeiden. Eine hundertprozentige Garantie ist das natürlich nicht, zumal KI die Abdeckung leicht mit Tests aufbläht, die fast nichts prüfen. So oder so setzt der Schwellenwert dem Design Grenzen und erhöht die Chancen auf guten Code.
5. Komplexität und Duplikate
Das menschliche Arbeitsgedächtnis fasst nur wenige unabhängige Elemente gleichzeitig: George Miller kam 1956 auf 7 ± 2, Nelson Cowan präzisierte das 2001 auf etwa vier. Alles darüber hinaus wird schwer und wandert in den Swap. Forschung dazu für KI habe ich nicht gesehen, aber wenn Code für einen Menschen verständlich ist, steigen die Chancen, dass die KI nicht halluziniert. Und wenn Code so verworren ist, dass ein Mensch ihm nicht folgen kann, wird die KI höchstwahrscheinlich neue Schichten von Altlasten obendrauf packen.
Deshalb setze ich harte Grenzwerte für Duplikate und Komplexitätsmetriken. Grenzwert überschritten → CI schlägt fehl → Sie müssen refaktorieren und Code in eigene Methoden und Klassen auslagern. Für Python ist complexipy ein Beispiel.
So sieht das in einem echten Projekt aus. Auf einer Plattform, an der ich gearbeitet habe, schrieben KI-Agenten den Großteil des Backends. Nach sechs Wochen, bevor es irgendeinen dieser Checks gab, fand die erste Messung 143 Funktionen mit einer Komplexität über 10 und 202 kopierte Fragmente, rund 5 % des Codes. Als später eine harte Obergrenze eingeführt wurde, war die schlimmste Funktion die, die Belege verarbeitete, also mit Geld umging: 490 Zeilen mit einer Komplexität von 73. Sobald diese Obergrenze den Build scheitern ließ, sank der Wert in vier Tagen Refactoring von 73 auf 30, eine Funktion pro Commit. In den zwei Monaten nach der ersten Messung sank der Anteil der Duplikate auf etwa 3 %.
Wenn sich bereits Altlasten angehäuft haben, können Sie vom aktuellen Stand aus starten: Setzen Sie den Grenzwert auf Ihre komplexeste Funktion, dann wird es zumindest nicht schlimmer. Die Schulden verschwinden dadurch allerdings nicht. Die tragen Sie gesondert ab: Planen Sie Zeit für Refactoring ein und senken Sie den Grenzwert nach jedem Schritt, um das Ergebnis festzuhalten. Checks halten das Chaos nur auf; aufräumen müssen Sie selbst.
6. Architektur und Kopplung
Harte Grenzen verringern die Komplexität ebenfalls, eine Ebene höher. Das funktioniert wie Kapselung in der OOP: Das System besteht aus großen Blöcken, deren Innenleben Sie nicht im Kopf behalten müssen; es reicht, ihren Vertrag zu kennen. Und die Implementierung eines Blocks lässt sich bei Bedarf austauschen, ohne den Rest des Systems neu zu schreiben. Statt über Dutzende Klassen und Verbindungen denken Sie über ein paar große Blöcke nach. Wieder verringern Sie die Zahl der Dinge, die Sie gleichzeitig im Kopf behalten müssen, diesmal auf jeder Ebene der Architektur.
In der Praxis bedeutet das Clean Architecture und hexagonale Architektur: Der Code ist in Schichten aufgeteilt, und die Abhängigkeiten zwischen ihnen sind streng begrenzt. Die Domäne weiß nichts von der Datenbank, von HTTP oder externen APIs, und Code von außen erreicht sie nur über vorab definierte Schnittstellen. Auch das wird automatisch geprüft (zum Beispiel mit import-linter für Python): Taucht ein verbotener Import auf, schlägt die CI fehl.
7. Schriftliche Regeln
Die letzte Ebene sind schriftliche Regeln. Früher waren das Richtlinien und Dokumentation für Entwickler; heute sind es eine AGENTS.md-Datei und Dokumentation für die KI. Anders als bei den Checks oben ist das Ergebnis hier nicht deterministisch: Die KI kann eine Regel lesen und sie trotzdem brechen. Schriftliche Regeln sind deshalb die letzte Meile. Sie enthalten nur, was sich nicht mit Checks abdecken ließ. Bei sonst gleichen Bedingungen gilt: lieber einen harten Check im Code schreiben als einen Absatz Text.
Die KI versucht immer wieder, den Check abzuschalten, statt den Code zu reparieren: den Grenzwert anheben, eine Ausnahme hinzufügen, die Regel per Kommentar stummschalten. Deshalb steht in meiner Regeldatei in einer eigenen Zeile: Einen Check abzuschwächen, damit er durchläuft, ist ein Workaround und repariert nichts.
Die Tools nach Sprache
| Ebene | Python | PHP | JS/TS |
|---|---|---|---|
| Toter Code | vulture | shipmonk/dead-code-detector (PHPStan) | knip |
| Linter und Formatierer | ruff | PHP_CodeSniffer (phpcs) | ESLint + Prettier |
| Statische Analyse | mypy (strict) | PHPStan | tsc (strict) |
| Unit-Tests und Abdeckung | pytest + coverage | PHPUnit | Jest / Vitest |
| Komplexität | complexipy | PHPMD, cognitive-complexity (PHPStan) | ESLint complexity |
| Duplikate | pylint duplicate-code | jscpd | jscpd |
| Architektur und Kopplung | import-linter | Deptrac | dependency-cruiser |
Es gibt auch eine Schritt-für-Schritt-Version dieses Beitrags für Coding-Agenten: das Playbook für CI-Leitplanken (auf Englisch). Um es auf ein Repository anzuwenden, sagen Sie Ihrem Agenten: Wende https://sg4.tech/blog/code-entropy-ci-checks-ai-legacy/playbook.md auf dieses Repository an.
Fazit
Die Entropie wächst so oder so; offen ist nur, wer sie im Zaum hält. Je mehr Regeln von schriftlichen Richtlinien in automatische CI-Checks wandern, desto weniger hängt davon ab, ob ein Mensch im Review aufmerksam ist. Die KI führt die Checks selbst aus, sieht, was fehlgeschlagen ist, und behebt es: Eine Zeile in der AGENTS.md kann sie überspringen, einen fehlgeschlagenen CI-Lauf nicht. Und je mehr solcher Checks Sie haben, desto gelassener können Sie ihr Code überlassen.
Wenn Sie Gründer sind und keinen Code lesen, taugt diese Liste trotzdem als Fragenkatalog für Ihr Team: Welche dieser Ebenen lassen den Build tatsächlich scheitern? Jede Antwort im Sinne von „das fangen wir im Review ab“ ist eine Regel, die von der Aufmerksamkeit eines Menschen an einem bestimmten Tag abhängt. Warum von Agenten geschriebener Code diese Leitplanken überhaupt braucht, ist eine eigene Geschichte: KI führen wie einen Junior.
Eine Vorlage für Python
Der Ansatz hängt nicht von der Sprache ab. Für Python habe ich alles in eine fertige Vorlage gepackt, die Sie gern nutzen können: python-guardrails-template.
Darin enthalten:
- alle Checks aus diesem Beitrag hinter einem einzigen Befehl
make verifyin Docker und derselbe Befehl in GitHub Actions; - Architekturschichten mit Prüfung der Importe;
- ein Scanner, der beim Commit nach Geheimnissen wie Schlüsseln und Passwörtern sucht;
- eine AGENTS.md, in der fast jede Regel auf den Check verweist, der sie durchsetzt;
- ein kleines Beispiel, damit die Checks direkt nach dem Anlegen des Projekts durchlaufen.
Ein neues Projekt legen Sie mit einem Befehl an:
copier copy gh:sg4tech/python-guardrails-template my-projectUnd wenn die Vorlage aktualisiert wird, bringt copier update die neuen Checks in bestehende Projekte und behält Ihre Änderungen bei. Nie wieder alles in jedem neuen Projekt von Grund auf einrichten.
Häufige Fragen
Bremsen strenge CI-Checks das Team nicht aus?
Checks verlagern die Kosten aus Review und Produktion in einen fehlgeschlagenen Build, wo sie am geringsten sind. Bei einer Legacy-Codebasis starten Sie vom aktuellen Stand, sodass am ersten Tag nichts blockiert.
Kann ich diese Checks in ein bestehendes Legacy-Projekt einbauen?
Ja: Frieren Sie den aktuellen Stand als Grenzwert ein, damit nichts schlechter wird, und senken Sie ihn dann Schritt für Schritt, während Sie refaktorieren.
Reicht ein Code-Review nicht aus, um so etwas zu finden?
Ein Review hängt von der Aufmerksamkeit ab und hält mit dem Tempo, in dem Agenten Code schreiben, nicht mit. Ein Check läuft bei jeder Änderung und schlägt jedes Mal auf dieselbe Weise fehl.
Brauche ich alle sieben Ebenen auf einmal?
Nein. Führen Sie sie der Reihe nach ein: zuerst toter Code, Formatierung und Typen, weil sie billig sind. Grenzwerte für Komplexität und Architektur zahlen sich aus, sobald die Codebasis wächst.