KI-Coding-Agenten brauchen Architektur, die sie lesen können

KI-Coding-Agenten werden besser darin, Code zu schreiben.

Das ist nicht mehr die spannendste Frage.

Die wichtigere Frage ist: Können sie in Ihrer Architektur arbeiten, ohne sie schrittweise zu beschädigen?

Unter Entwicklerinnen und Entwicklern, die mit Claude Code, Cursor, Codex und ähnlichen Werkzeugen arbeiten, bekommt gerade ein sehr praktisches Muster Aufmerksamkeit: Architectural Decision Records im Repository speichern und Coding-Agenten explizit anweisen, diese Entscheidungen zu lesen, bevor sie Änderungen am System vornehmen.

Das klingt klein. Ist es aber nicht.

Dahinter steckt ein größerer Wandel in der KI-unterstützten Softwareentwicklung. Die besten Teams werden nicht einfach die längsten Prompts schreiben. Sie werden ihre Architekturentscheidungen in Projekt-Infrastruktur übersetzen: Entscheidungsdokumente, Repo-Anweisungen, Tests, Lint-Regeln, Security-Checks und Review-Gewohnheiten, die auch ein Agent verstehen und befolgen kann.

Kurz gesagt:

KI-Coding-Agenten brauchen Architektur, die sie lesen können.

Das versteckte Problem bei agentischer Entwicklung

In ernsthaften Softwaresystemen stecken viele Entscheidungen, die man dem Code nicht sofort ansieht.

Warum besitzt genau dieses Modul die Kundendaten?

Warum sind direkte Datenbankzugriffe in diesem Teil der Anwendung verboten?

Warum läuft Billing über Events statt synchron?

Warum wird diese Integration erneut versucht, eine andere aber nicht?

Warum werden Berechtigungen in dieser Schicht geprüft und nicht woanders?

Eine erfahrene Entwicklerin kennt die Antwort vielleicht. Ein Gründer erinnert sich an den Produktionsfehler, der zu dieser Regel geführt hat. Eine Product Ownerin versteht die operative Einschränkung hinter einem seltsam wirkenden Workflow.

Ein KI-Agent sieht erst einmal Dateien.

Er kann Muster erkennen, aber er weiß nicht automatisch, welche Muster absichtlich sind, welche historisch gewachsen sind und welche gefährliche Abkürzungen darstellen. Wenn der wichtigste Projektkontext vor allem in Köpfen gespeichert ist, füllt der Agent die Lücken mit plausiblen Annahmen.

Genau dort entstehen Risiken.

Der Code kompiliert. Die Demo funktioniert. Der Diff sieht vielleicht sogar sauber aus. Aber eine Grenze hat sich verschoben. Eine Sicherheitsregel wurde umgangen. Ein Datenmodell wurde dupliziert. Eine Abkürzung wurde zum Präzedenzfall.

Das Risiko ist nicht, dass Agenten immer schlechten Code schreiben. Das Risiko ist, dass sie plausiblen Code auf Basis eines unvollständigen Systemverständnisses schreiben.

Prompts reichen nicht

Es liegt nahe, das Problem mit besseren Prompts lösen zu wollen.

Sagen Sie dem Agenten, er soll sorgfältig sein. Sagen Sie ihm, er soll wie ein Senior Engineer handeln. Sagen Sie ihm, er soll Best Practices einhalten. Sagen Sie ihm, er soll Security, Wartbarkeit und Skalierbarkeit beachten.

Das hilft. Aber nur begrenzt.

Allgemeine Anweisungen ersetzen keine projektspezifischen Entscheidungen. “Schreibe wartbaren Code” sagt einem Agenten nicht, welcher Service einen Workflow besitzt. “Achte auf Security” sagt ihm nicht, wo Tenant-Scoping erzwungen werden muss. “Folge der Architektur” ist wenig hilfreich, wenn die Architektur nicht an einem Ort dokumentiert ist, den der Agent tatsächlich liest.

Deshalb ist Repository-Kontext so wichtig.

Viele Teams nutzen bereits Dateien wie AGENTS.md, CLAUDE.md, CONTRIBUTING.md oder interne Engineering-Guides. Diese Dateien geben Werkzeugen und Menschen einen Einstieg. Für Architektur ist eine einzige Anweisungsdatei aber oft zu grob. Sie wird entweder vage oder so lang, dass niemand sie pflegt.

Architectural Decision Records lösen ein anderes Problem.

Sie erfassen konkrete Entscheidungen:

• den Kontext der Entscheidung;
• die Entscheidung selbst;
• Konsequenzen und Trade-offs;
• betroffene Codebereiche;
• Checks oder Review-Regeln, die die Entscheidung schützen.

Genau diese Art von dauerhaftem Kontext brauchen KI-Agenten.

ADRs werden zum Gedächtnis der Codebase

Ein Architectural Decision Record ist normalerweise kurz. Er muss kein großes Architekturpapier sein. Ein hilfreicher ADR kann eine einzige Frage beantworten:

Dürfen Feature-Module direkt auf die Datenbank zugreifen?

Werden Rechnungen synchron erzeugt oder über eine Event-Queue?

Wird Tenant-Zugriff in der Datenbankschicht, in der Serviceschicht oder in beiden erzwungen?

Werden KI-generierte Vorschläge gespeichert, auditiert oder verworfen?

Bekommt ein Modul eine öffentliche API oder bleibt es intern?

Diese Entscheidungen wirken unspektakulär. Sind sie aber nicht. Sie formen das System.

Wenn ADRs im Repository liegen, kann ein KI-Coding-Agent sie lesen, bevor er Code ändert. Dann reagiert der Agent nicht nur auf vorhandene Dateien. Er arbeitet mit der dokumentierten Begründung des Teams.

Das verändert die Zusammenarbeit.

Statt dem Agenten in jeder Sitzung erneut zu erklären, dass er niemals direkt aus einem bestimmten Package auf die Datenbank zugreifen darf, kann das Team die Regel einmal dokumentieren, mit den relevanten Modulen verknüpfen und nach Möglichkeit automatisiert prüfen.

Statt darauf zu hoffen, dass ein Senior Developer dieselbe architektonische Abweichung in jedem Review wieder findet, wird die Entscheidung sichtbar, bevor der Diff entsteht.

Statt jede Agenten-Sitzung als neues Gespräch zu behandeln, trägt das Repository Erinnerung nach vorne.

Das ist wichtig, weil KI-unterstützte Entwicklung mehr Implementierungsdurchsatz erzeugt. Mehr Durchsatz bedeutet: Mehr Entscheidungen werden schneller in Code gegossen. Wenn diese Entscheidungen nicht geführt, geprüft und dokumentiert werden, driftet eine Codebase schneller als vorher.

Die besten Entscheidungen sind prüfbar

Dokumentation hilft. Durchsetzung hilft mehr.

Das nützlichste Muster lautet nicht nur: “Schreiben Sie ADRs.” Es lautet: “Verbinden Sie ADRs mit Checks.”

Ein Beispiel:

• Ein ADR sagt, dass alle tenant-bezogenen Queries über eine zentrale Zugriffsschicht laufen müssen.
• Eine Lint-Regel markiert direkte Imports des Datenbank-Clients in Feature-Modulen.
• Tests prüfen Tenant-Isolation.
• Pull-Request-Reviews achten auf Änderungen an dieser Grenze.
• Die Agenten-Anweisung sagt Coding-Agenten, dass sie den ADR lesen müssen, bevor sie Data-Access-Code anfassen.

Jetzt existiert die Entscheidung in vier Formen:

• als menschlich lesbare Begründung;
• als agentenlesbarer Kontext;
• als automatisierte Durchsetzung;
• als Review-Erwartung.

Das ist deutlich stärker als ein Absatz in einem Wiki.

Nicht jede Entscheidung braucht diese Behandlung. Wenn Teams alles erzwingen wollen, wird das System schwerfällig und Menschen umgehen es. Entscheidend ist, die Regeln zu schützen, deren Verletzung teuer, riskant oder peinlich wäre.

Gute Kandidaten sind:

• Authentifizierung und Autorisierung;
• Tenant-Isolation;
• Datenhoheit;
• Payment- und Billing-Flows;
• Audit-Logging;
• Integrationsverträge;
• personenbezogene Daten;
• Deployment- und Rollback-Regeln;
• Modulverantwortung;
• API-Kompatibilität.

Das sind Bereiche, in denen “der Agent wird es schon verstehen” keine ausreichende Antwort ist.

Warum das für Gründer und Mittelstand besonders relevant ist

Für viele Gründer liegt das Versprechen von KI-Coding-Tools in Geschwindigkeit. Ein MVP schneller bauen. Features schneller liefern. Weniger abhängig von knappen Engineering-Kapazitäten sein.

Dieses Versprechen ist real, aber unvollständig.

Solange ein Produkt experimentell ist, kann ein schneller Prototyp wertvoll sein. Sobald Kundinnen und Kunden von der Software abhängen, braucht Geschwindigkeit ein Steuerungssystem. Das Produkt braucht stabile Architektur, vernünftige Betriebsprozesse und klare Verantwortlichkeiten.

Für Mittelstand und etablierte Teams ist das Thema noch schärfer. Bestehende Systeme enthalten oft Jahre an implizitem Geschäftswissen. Preis-Ausnahmen, kundenspezifische Workflows, regulatorische Einschränkungen, manuelle Betriebsabläufe und Integrationsdetails liegen verteilt in Code, Tabellen, Tickets und Köpfen.

KI-Agenten können helfen, solche Systeme zu modernisieren. Aber nur, wenn das System lesbar wird.

Das bedeutet nicht, ein 100-seitiges Architekturhandbuch zu schreiben. Es bedeutet, genug strukturierten Kontext zu schaffen, damit Menschen und Agenten verstehen, was nicht kaputtgehen darf.

Bei McDougall Digital ist genau das der praktische Kern von architecture-first delivery. Bevor KI die Implementierung beschleunigt, wollen wir wissen, welche Entscheidungen wichtig sind, wo die riskanten Grenzen liegen und welche Regeln automatisiert geprüft werden sollten. Sonst hilft KI nur dabei, mehr Code um ungeklärte Ambiguität herum zu erzeugen.

Wie agentenlesbare Architektur aussieht

Eine agentenlesbare Architekturschicht muss nicht kompliziert sein.

Ein gesunder Einstieg kann so aussehen:

1. Eine kurze Repo-Anweisung für Agenten

Diese Datei erklärt, wie sich Agenten im Projekt verhalten sollen. Sie kann Tech Stack, Befehle, Review-Erwartungen, verbotene Abkürzungen und Links zu Architekturentscheidungen enthalten.

Zum Beispiel:

“Bevor du Authentifizierung, Billing, Tenant-Daten oder Integrationen änderst, lies die relevanten ADRs in docs/adr/.”

2. Ein kleiner ADR-Ordner

Beginnen Sie mit Entscheidungen, die in Entwicklung oder Reviews regelmäßig auftauchen. Dokumentieren Sie nicht alles. Dokumentieren Sie, was Verhalten verändert.

Ein ADR kann einfach aufgebaut sein:

• Titel;
• Datum;
• Status;
• Kontext;
• Entscheidung;
• Konsequenzen;
• betroffene Dateien oder Module;
• Durchsetzung oder Review-Hinweise.

3. Eine Test- und Check-Übersicht

Für jede kritische Entscheidung sollte klar sein, welcher Check sie schützt.

Manche Entscheidungen werden durch Unit Tests geschützt. Andere durch Integrationstests. Manche durch Lint-Regeln. Manche durch Code Review. Manche durch Monitoring.

Es geht nicht darum, jede Regel sofort zu automatisieren. Es geht darum, dass das Team weiß, welche Entscheidungen maschinell geschützt sind und welche noch von menschlicher Prüfung abhängen.

4. Klare Modulgrenzen

Agenten arbeiten besser, wenn Grenzen sichtbar sind. Ordnernamen, öffentliche APIs, Import-Regeln und Ownership-Hinweise helfen.

Wenn ein Modul intern ist, schreiben Sie es hin. Wenn ein Service der einzige erlaubte Weg ist, Kundendaten zu verändern, machen Sie das sichtbar. Wenn zwei Domänen nicht voneinander abhängen dürfen, kodieren Sie das über Import-Regeln oder Architekturtests.

5. Die Gewohnheit, Entscheidungen zu aktualisieren

Architektur ändert sich. Gute Teams frieren Entscheidungen nicht für immer ein. Sie aktualisieren den Stand, wenn sich die Realität ändert.

Das ist bei KI-Agenten besonders wichtig, weil der Agent bei der Pflege helfen kann. Am Ende eines Features kann das Team fragen:

“Hat diese Änderung eine neue Architekturentscheidung eingeführt oder eine bestehende verändert?”

Wenn ja, wird der ADR Teil der Arbeit.

Was man vermeiden sollte

Es gibt ein paar Fallen.

Die erste ist Bürokratie. Wenn jedes kleine Implementierungsdetail ein Decision Record wird, liest niemand mehr die Dokumente. ADRs sollten echte Entscheidungen abdecken, nicht persönliche Vorlieben.

Die zweite ist Dokumentation ohne Verbindung zum Code. Wenn ein ADR sagt “nutze die zentrale Berechtigungsschicht”, aber nichts im Repository diese Regel stützt, wird sie irgendwann ignoriert. Mindestens sollte der ADR mit relevanten Dateien und Review-Regeln verknüpft sein. Bei kritischen Regeln gehören automatisierte Checks dazu.

Die dritte ist die Annahme, dass Agenten immer alles lesen. Das tun sie nicht, wenn Workflow und Konfiguration es nicht einfach und explizit machen. Repo-Anweisungen, Prompt-Templates und Tooling sollten Agenten vor der Arbeit zu den richtigen Entscheidungen führen.

Die vierte ist, veraltete Entscheidungen als Wahrheit stehen zu lassen. Ein alter ADR kann schlimmer sein als kein ADR, weil er Agenten falsche Sicherheit gibt. Statuslabels müssen klar sein: vorgeschlagen, akzeptiert, ersetzt, verworfen.

Die fünfte ist, Architektur als einmalige Setup-Aufgabe zu behandeln. Agentenlesbare Architektur ist eine Betriebsgewohnheit. Sie verbessert sich, wenn das Team sieht, wo Agenten Fehler machen, wo Reviews langsam werden und welche Regeln stärkere Durchsetzung verdienen.

Eine praktische erste Woche

Wenn Ihr Team bereits KI-Coding-Tools nutzt, brauchen Sie kein großes Programm, um anzufangen.

In der ersten Woche:

1. Erstellen Sie eine Repo-Anweisung für Agenten.

Halten Sie sie kurz. Befehle, Coding-Standards, verbotene Abkürzungen und Links zu Architekturentscheidungen reichen für den Anfang.

2. Schreiben Sie fünf ADRs.

Wählen Sie Entscheidungen, die heute wichtig sind. Für viele SaaS- und Internal-Tool-Teams sind das Authentifizierung, Tenant-Scoping, Datenhoheit, Billing-Änderungen und Deployment-Rollback.

3. Fügen Sie eine prüfbare Regel hinzu.

Nehmen Sie eine Entscheidung, die leicht automatisiert zu prüfen ist. Vielleicht sind direkte Datenbank-Imports außerhalb eines Data-Access-Packages verboten. Vielleicht dürfen UI-Komponenten keine externen APIs direkt aufrufen. Vielleicht dürfen Produktions-Secrets nicht in lokalen Config-Dateien auftauchen.

4. Lassen Sie den Agenten die Records benutzen.

Nehmen Sie eine echte Aufgabe und weisen Sie den Agenten explizit an, den relevanten ADR vor dem Implementierungsvorschlag zu lesen. Beobachten Sie, wo er das System trotzdem missversteht. Genau dort fehlt Kontext.

5. Prüfen Sie das Review.

Nach dem Pull Request: Was musste der menschliche Reviewer erklären, das eigentlich im Repository stehen sollte? Das Beste daraus wird ADR, Test, Lint-Regel oder Agenten-Anweisung.

Das ist keine glamouröse Arbeit. Es ist die Arbeit, die KI-Adoption ernsthaft macht.

Der Business Case

Der geschäftliche Wert lautet nicht: “Wir haben ADRs.”

Der Wert lautet: Architektur bleibt besser erhalten, während das Team schneller arbeitet.

Das kann Review-Aufwand reduzieren. Es kann Onboarding vereinfachen. Es kann Agenten-Output verlässlicher machen. Es kann Security-Entscheidungen schützen. Und es kann Gründerinnen, CTOs und Produktverantwortlichen mehr Sicherheit geben, wenn mehr Code von Werkzeugen erzeugt wird, die nicht automatisch das Gedächtnis des Unternehmens teilen.

Außerdem entsteht eine bessere Grundlage für weitere Automatisierung.

Wenn Entscheidungen und Checks im Repository leben, können Agenten mehr tun als nur implementieren. Sie können prüfen, ob eine vorgeschlagene Änderung bestehende Architektur verletzt. Sie können Dokumentation aktualisieren, wenn sich eine Entscheidung ändert. Sie können Tests für Regeln schreiben, die heute nur manuell geprüft werden. Sie können alten Code Schritt für Schritt in Richtung klarer Grenzen refaktorieren.

Das ist eine deutlich stärkere Nutzung von KI als isolierte Features schneller schreiben zu lassen.

Es geht nicht darum, KI auszubremsen

Gute Architektur existiert nicht, um Entwicklung langsamer zu machen. Sie existiert, damit Veränderung sicherer wird.

KI-Coding-Agenten erhöhen die Menge an Veränderung, die ein Team anstoßen kann. Dadurch wird Architektur wichtiger, nicht unwichtiger.

Die Teams, die am meisten von KI-unterstützter Entwicklung profitieren, werden Agenten nicht einfach durch eine vage Codebase laufen lassen und auf das Beste hoffen. Sie werden die wichtigen Teile des Systems lesbar, prüfbar und durchsetzbar machen.

Für McDougall Digital Kunden ist das oft der Unterschied zwischen einer sinnvollen KI-Adoptionsstrategie und einer Sammlung beeindruckender Demos. Wir helfen Teams, Architektur, Produktgrenzen und Betriebsregeln so zu definieren, dass schnellere Implementierung überhaupt wertvoll wird.

Wenn Sie KI-Coding-Tools bewerten, fragen Sie also nicht nur, welcher Agent den besten Code schreibt.

Fragen Sie die härtere Frage:

Kann Ihre Architektur sich gut genug erklären, damit ein Agent zuverlässig in ihr arbeiten kann?

Wenn die Antwort nein lautet, ist genau das der beste Startpunkt.