Zum Hauptinhalt springen

Architektur

Architektur des KI-nativen Repositorys

Wie das Repository dieses Portfolios KI-Coding-Agenten sinnvolle Änderungen sicher ermöglicht: deterministisches Kontext-Routing vor einer Änderung, schmale Agentenrollen währenddessen und danach dieselben Validatoren, Tests und dieselbe menschliche Prüfung.

Veröffentlicht am 5. Oktober 2026

Dieses Portfolio wird jeden Tag von KI-Coding-Agenten verändert, die mit mir zusammenarbeiten. Diese Fallstudie handelt vom System um diese Agenten herum: wie das Repository einem Agenten sagt, was er wissen muss, bevor er etwas ändert, welche Arbeit ein Agent selbstständig erledigen darf und welche Prüfungen jede Änderung bestehen muss, bevor sie in Produktion geht. Die Prämisse ist dieselbe wie beim Fotografie-Assistenten: Das Modell ist ein leistungsfähiger, probabilistischer Teil eines deterministischen Systems. KI vergrößert, was sich an einem Tag umsetzen lässt. Die Architektur des Repositorys entscheidet, wie sicher sich diese Fähigkeit nutzen lässt.

Das Problem

Ein Coding-Agent kann Code schreiben, der kompiliert, seine Tests besteht und für dieses Repository trotzdem falsch ist. Die Qualität der Generierung ist nicht das Hauptrisiko. Die Risiken liegen in dem, was ein Modell aus der Datei, die es bearbeitet, nicht erkennen kann:

  • Architektur. Welche Domäne welche importieren darf, wo Datenbankzugriff erlaubt ist, welche Schicht eine Entscheidung verantwortet.
  • Konventionen, die optional wirken. Jeder sichtbare Text existiert auf Englisch und Deutsch; jede Datenbankzeile wird vor der Verwendung gegen ein Schema geprüft; Admin-Schreibzugriffe laufen über eine authentifizierte Prozedur.
  • Einschränkungen, die spät scheitern. Manche Fehler bestehen Typprüfung, Linter, Unit-Tests und den Produktions-Build und brechen erst im ausgelieferten Container.
  • Plausibler, aber falscher Kontext. Eine selbstbewusste Zusammenfassung eines Subsystems, von einem Modell oder aus einem veralteten Dokument, ist leicht zu übernehmen und schwer zu bemerken.

Das technische Problem ist also Kontrolle in zwei Richtungen: welcher Kontext den Agenten erreicht, bevor er etwas ändert, und was danach deterministisch geprüft wird.

Was ich gebaut habe

Ich habe die agentenseitige Architektur des Repositorys entworfen und gebaut: die Hierarchie der Anweisungen, eine deterministische Routing-Schicht für Kontext, eine validierte Wissensschicht, die Validatoren für Architektur und Repository-Hygiene, die lokalen Hooks und CI-Gates, die sie ausführen, und eine kleine Zahl spezialisierter Agentenrollen mit durchgesetzten Grenzen. Außerdem habe ich die Experimente durchgeführt, die entschieden haben, welche Rollen es gibt und welches Modell jede davon nutzt.

Es dient einem Entwickler (mir) und mehreren KI-Agenten an einer produktiven Codebasis mit rund 4.500 versionierten Dateien. Manche Entscheidungen unten sind von diesem Maßstab geprägt; ich sage es jeweils dazu.

Die Architektur im Überblick

  1. Anfrage von mir
  2. Primärer Agent klassifiziertRouting-Manifest → Wissenskonzepte · Skills · CodeGraph-Einstiegspunkte · Validierung
    • Begrenzte RechercheExplorer (nur lesend)
    • Begrenzte Umsetzungentschiedenes Paket → Bounded Implementer (Vertrag, Schreibgrenze, Ownership-Check)
  4. Primärer Agent prüft + integriert
  5. Pre-Commit-HookLint · Hygiene · Architektur · Wissen · generierter Index
  6. Pre-Push-HookAktualität · Wissens-Health · Hygiene · Architektur · statische Analyse · Typen · Unit-Tests
  7. CI (Pull Request, dann main)statische Analyse · vier Validatoren · Tests · Build → Deployment
  8. Ich prüfe, committe und liefere aus
  • Hierarchie der Anweisungen. Eine Datei (CLAUDE.md) enthält die Verhaltensregeln für jeden Agenten; die Anweisungsdateien anderer Werkzeuge verweisen darauf, statt sie zu wiederholen. Sie sagt, wie man sich verhält, und verlinkt, wo Wissen liegt; das System selbst beschreibt sie bewusst nicht.
  • Routing-Manifest. Eine Nachschlagetabelle mit zwölf Aufgabenkategorien, die jeweils die Wissenskonzepte, Workflow-Skills, CodeGraph-Einstiegspunkte und Validierungsbefehle auflisten, die eine Kategorie braucht.
  • Wissensschicht. Rund vierzig kurze Konzeptdateien zu Architektur, Entscheidungen, Sicherheit, Tests und Frontend-Regeln, jede mit maschinell geprüften Metadaten und Quellenangaben.
  • CodeGraph. Ein lokaler Index aller Symbole und Aufrufkanten, den Agenten abfragen, statt Dateien einzeln zu lesen.
  • Validatoren. Deterministische Prüfungen für Architekturgrenzen, Repository-Hygiene, Integrität des Wissens und des Routings, ausgeführt von Hooks und noch einmal in CI.
  • Agentenrollen. Ein primärer Agent, der die Aufgabe verantwortet, und schmale Subagenten für Recherche und für bereits entschiedene Umsetzung, jeweils begrenzt durch Werkzeugkonfiguration und Guards.

Die zentrale Architekturentscheidung

Autorität kommt aus Konfiguration und Prüfungen, nie aus dem Modell.

Der Agent, der eine Aufgabe verantwortet, entscheidet, was sie bedeutet, welcher Code die Änderung verantwortet und was als erledigt gilt. Was er abgibt, kommt bei einem Subagenten bereits begrenzt an: eine Rechercheaufgabe mit definiertem Umfang oder ein Umsetzungspaket mit schriftlichem Vertrag, einer expliziten Liste beschreibbarer Pfade und Abnahmebefehlen, die tatsächlich laufen. Was ein Subagent darf, legen seine Werkzeugliste und ein Guard-Skript fest, das vor jedem seiner Werkzeugaufrufe läuft – nicht seine Anweisungen und nicht, wie fähig das Modell dahinter ist. Alles, was ein Subagent zurückgibt, gilt als Beleg, den der primäre Agent erneut liest, bevor er darauf handelt.

Deshalb kann das günstigste Modell im System sicher echte Arbeit erledigen: Es hat die geringste Autorität. In der gemessenen Historie meiner eigenen Anfragen kam keine von 177 so begrenzt an, dass sie sich direkt hätte abgeben lassen. Eine mehrdeutige Anfrage in begrenzte Arbeit zu verwandeln, bleibt beim stärksten Reasoning im Ablauf.

Kontext vor der Generierung

Vor einer nicht trivialen Änderung ordnet ein Agent die Aufgabe über die Auslösebegriffe einer Kategorie im Routing-Manifest ein und öffnet dann nur, was diese Kategorie auflistet: ein bis drei Konzeptdateien, gegebenenfalls einen Skill für den Ablauf und die CodeGraph-Einstiegspunkte. Bevor er etwas ändert, nennt er, was er geöffnet hat. Passt keine Kategorie, sagt er das und greift auf eine Navigationsseite zurück. Stillschweigendes Überspringen ist das eine Ergebnis, das die Anweisungen verbieten.

Das ist bewusst kein semantisches Retrieval. Manifest, Wissensvalidator und Routing-Validator nutzen keine Embeddings, kein Ranking und keine Modellaufrufe; es sind statische Tabellen und Linter. Ich habe das so gewählt, weil der Fehler, den ich verhindern wollte, ein Agent war, der plausiblen Kontext lädt. Eine Nachschlagetabelle kann falsch sein, aber jedes Mal auf dieselbe Weise; sie lässt sich in einem Diff prüfen, und ein Validator kann kontrollieren, dass jeder genannte Pfad existiert und von der richtigen Art ist.

CodeGraph ist anders: ein Werkzeug eines Drittanbieters mit eigenem Volltext-Ranking für die Suche und exakter Traversierung für Aufrufer, Aufgerufene und Auswirkungen. Agenten lesen damit den tatsächlichen Quelltext der Symbole rund um eine Änderung in einem Aufruf, statt Suchen und Dateizugriffe aneinanderzureihen.

Die Wissensschicht wird geprüft, nicht vorausgesetzt. Jedes Konzept deklariert die Quelldateien und Abschnitte, die es beschreibt. Eine Prüfung kontrolliert bei jedem Commit Metadaten, Links und die Abdeckung der Navigation; eine weitere vergleicht vor jedem Push jedes Konzept mit der Git-Historie und meldet, welche Konzepte sich von ihren Quellen entfernt haben könnten.

Leitplanken

Jede Prüfung läuft an einer festgelegten Grenze, und die Grenzen überlappen, sodass das Überspringen einer Grenze die Prüfung nicht entfernt.

Bei jedem Commit führt ein Hook den Linter aus, wenn Code vorgemerkt ist, dazu die Hygiene- und Architekturprüfung der vorgemerkten Dateien, die Wissensvalidierung und eine Prüfung, ob der generierte Wissensindex aktuell ist.

Bei jedem Push führt ein zweiter Hook die Berichte zu Aktualität und Zustand des Wissens aus, die vollständigen Hygiene- und Architekturvalidatoren, die statische Analyse des ganzen Repositorys, den TypeScript-Compiler und die Unit-Tests. Beide Hooks brechen beim ersten Fehler ab.

Bei jedem Pull Request und noch einmal auf dem Weg in Produktion führt CI die statische Analyse, dieselben vier Repository-Validatoren als einzeln benannte Schritte, die Tests und den Produktions-Build aus. Das Deployment hängt von diesem Job ab; ein Validatorfehler stoppt also ein Deployment.

Der Architekturvalidator ist der Kern. Domänen und ihre erlaubten Importe sind in einem Manifest deklariert, und er meldet als Fehler: verbotene domänenübergreifende Importe, Zyklen zwischen Domänen, Datenbankzugriff aus einer Datei, die kein deklarierter Owner ist, Produktionscode, der Tests oder Diagnoseskripte importiert, fest verdrahtete Speicherpfade und eine Bundler-Direktive, die bei lokalen Importen missbraucht wird. Deklarierte Owner und Ausnahmen tragen eine schriftliche Begründung; eine Owner-Liste ist eine Bestandsaufnahme dessen, was existiert, keine Vorabgenehmigung für das, was kommen könnte. Warnungen, etwa Dokumentation, die nicht mehr zum Manifest passt, werden ausgegeben, ohne zu blockieren.

Der Hygienevalidator schützt die Evaluationsarbeit, auf die das Produkt angewiesen ist: Kanonische Benchmarks und menschliche Relevanzurteile können in einer Routineänderung nicht gelöscht werden, archiviertes Material kann keine aktive Abhängigkeit werden, und ein Evaluationsskript kann den produktiven Retrieval-Code, den es messen soll, nicht nachbauen.

Die Grenze zwischen Agent und Werkzeug

Es gibt vier spezialisierte Rollen, jede mit festgelegtem Modell und eingeschränkten Werkzeugen:

  • Repository-Explorer (Sonnet). Nur lesende Werkzeuge und eine Shell, die gegen Schreibzugriffe abgesichert ist. Er sammelt Belege und kennzeichnet jede Aussage als beobachtet, abgeleitet oder unbekannt.
  • Bounded Implementer (Haiku). Er darf Quelldateien schreiben. Ein Guard verweigert Repository-Autorität (Commits, Pushes, Installationen, Deployments) und jede Änderung an den Dateien, die die Regeln für die Bewertung seiner Arbeit festlegen. Ein Ownership-Check vergleicht danach, was sich tatsächlich geändert hat, mit den Pfaden, die der Vertrag erlaubt.
  • Execution Manager (Haiku). Er arbeitet einen Plan ab, den der primäre Agent bereits geschrieben hat, Schritt für Schritt über ein deterministisches Ausführungsprotokoll, und kann nur die beiden Rollen oben beauftragen. Die abschließende Übergabe schreibt das Protokoll, nicht der Manager.
  • Visual QA (Haiku). Experimentell. Er prüft Screenshots und Zustände, die ein deterministisches Browserskript erfasst hat, und kann selbst keinen Browser steuern.

Subagenten laufen auf einem ausdrücklich gewählten Modell; der allgemeine Standard ist Sonnet, nicht das Modell des primären Agenten. Architektur, Produktsemantik, Sicherheits- und Vertrauensgrenzen, Abnahmekriterien und alles Mehrdeutige werden nie delegiert. Auch UI-Arbeit wird standardmäßig nicht delegiert, weil es keine deterministische Prüfung des gerenderten Zustands gibt, die sie abnehmen könnte.

Die Guards sind Mustererkennung, keine Sandboxen. Sie machen den vorgesehenen Weg zum einfachen Weg und blockieren bekannte Fehler; Missbrauch machen sie nicht unmöglich. Die eigentlichen Gates sind deshalb die Validatoren, die Tests und meine Prüfung – sie greifen unabhängig davon, wer die Änderung gemacht hat.

Getrennt von den Coding-Agenten stellt das Produkt seine Pipelines für Anschreiben und Lebenslauf als Werkzeuge über das Model Context Protocol bereit. Diese Werkzeuge sind dünne Transportadapter über denselben deterministischen Modulen, die die Webanwendung nutzt: Ein KI-Client kann die Pipeline aufrufen, aber nicht ändern, wie Belege ausgewählt werden.

Was gescheitert ist

Eine aufgeschriebene Regel hat sich nicht durchgesetzt. Problem: Die Regel, dass nur die Abfrageschicht die Datenbank berührt, stand viermal in den Agentenanweisungen, und nichts prüfte sie. Ergebnis: Eine wiederholte Anweisung bleibt eine Anweisung. Konsequenz: Sie wurde zu einem Architekturfehler mit fünf deklarierten Ownern, jeder mit Begründung. Die Anweisungen sagen jetzt außerdem, welcher Teil der Regel maschinell geprüft wird und welcher eine Review-Konvention bleibt, statt jede Klausel gleich zu gewichten.

Grüne Builds, die Produktion gebrochen hätten. Problem: Eine Bundler-Direktive bei lokalen Importen bestand Typprüfung, Linter, Tests und den Produktions-Build und wäre erst im eigenständigen Produktions-Image gescheitert. Ein zweiter Fehler verdrahtete einen Speicherpfad fest, der von der Umgebung abhängen sollte. Experiment: Ich habe beide in Validatorregeln übersetzt und gegen die historischen Commits laufen lassen. Ergebnis: fünf bzw. ein Fund bei den fehlerhaften Commits, null nach den echten Korrekturen. Der bestehende Importgraph hätte den ersten Fehler nicht finden können: Er ignoriert dynamisch zusammengesetzte Importpfade absichtlich, und genau darauf beruht der Missbrauch. Konsequenz: eine eigene Prüfung. Zwei Dinge, die ein Agent bisher bemerken musste, muss er jetzt nicht mehr bedenken.

Lokale Gates waren die einzigen Gates. Problem: Eine Zeit lang liefen die vier Validatoren nur in lokalen Git-Hooks, und Hooks lassen sich überspringen. Konsequenz: Jeder Validator wurde ein eigener, benannter Schritt in der Pull-Request-CI und in der Deployment-Pipeline. Manche Prüfungen haben bis heute keine CI-Entsprechung, etwa die Aktualität des Wissens; die Anweisungen dokumentieren diese Ausnahme, statt zu behaupten, das Überspringen der Hooks sei harmlos.

Eine Aktualitätsprüfung, die zu oft Alarm schlug. Problem: Die Aktualitätsprüfung des Wissens markierte Konzepte, sobald sich eine zitierte Datei änderte. Experiment: Bevor die Prüfung in CI aufgenommen werden konnte, wurde jede Markierung von Hand geprüft. Ergebnis: 15 von 17 Markierungen waren falsch oder übervorsichtig. Der einzige harte Fehler war ein Fehlalarm, während das einzige tatsächlich veraltete Konzept nur weich markiert war. Konsequenz: Konzepte deklarieren jetzt die Abschnitte einer Datei, von denen sie abhängen. Gegen dieses Ziel hatte der reparierte Detektor weder Fehlalarme noch Auslassungen. „Veraltet“ blockiert jetzt nur noch, wenn eine zitierte Quelle fehlt oder nicht auflösbar ist; alles andere ist ein Hinweis.

Ein gerouteter Pfad, der nichts lieferte. Problem: Das Routing-Manifest verwies Agenten auf das Datenbankschema als CodeGraph-Einstiegspunkt. Die Datei existierte, also bestand die Validierung, aber CodeGraph extrahiert aus SQL keine Symbole. Bei näherer Prüfung lieferten fünf von 21 Einstiegspunkten nichts. Konsequenz: eine eigene Liste für Dateien, die direkt gelesen werden, und ein Validatorfehler, wenn ein CodeGraph-Eintrag keine Symbolquelle ist. Entscheidend ist nicht, ob eine Datei im Index ist, sondern ob sie Symbole liefert.

Das günstigste Modell als Standard-Explorer. Experiment: fünf geprüfte Rechercheläufe mit Haiku. Ergebnis: wesentliche Mängel, darunter falsche Aussagen und übersehene Konfigurationsfakten, in drei von fünf. Konsequenz: Recherche läuft auf Sonnet. Die größeren Kosten lagen woanders: Die Neubewertung von 101 historischen Subagent-Läufen zeigte, dass der Großteil der Ausgaben von Subagenten kam, die stillschweigend das teuerste Modell erbten. Deshalb ist der Standard jetzt festgelegt.

KI-Reviewer haben sich die Rolle nicht verdient. Experiment: Unabhängige Reviewer bekamen die historischen Fehler, die deterministische Prüfungen übersehen hatten, dazu fehlerfreie Kontrolländerungen. Ergebnis: Ein Sonnet-Reviewer fand zwei von sieben, bei einer vor dem ersten Lauf festgelegten Schwelle von drei, und sein einziger eigenständiger Fund ließ sich nicht reproduzieren. Ein günstigeres gehostetes Modell fand ohne Hilfe keinen und lieferte bei einer fehlerfreien Änderung nie ein leeres Review. Konsequenz: keine KI-Review-Stufe. Wiederkehrende Fehlerklassen werden zu deterministischen Regeln.

Die Grenze war der Vertrag, nicht das Modell. Experiment: acht eingefrorene Umsetzungspakete, jedes einmal mit Haiku und mit Sonnet. Ergebnis: Haiku bestand sieben von acht ohne Korrektur, Sonnet sechs. Beide Modelle lieferten bei einem Paket dasselbe falsche Ergebnis, weil der Vertrag die Regel ungenau beschrieb. Bei zwei weiteren konnte der Abnahmebefehl nie bestehen. Konsequenz: Haiku verantwortet begrenzte Umsetzung, und Verträge samt Abnahmebefehlen werden so sorgfältig geprüft wie Code.

Kommentare, die sich vom Code entfernten. Problem: Innerhalb von drei Monaten stieg die Kommentardichte im Quellbaum auf mehr als das Zehnfache. Ergebnis: Eine Prüfung ergab, dass die meisten Kommentare wertvoll waren, aber jede bestätigte veraltete Aussage wiederholte eine Tatsache, die anderswo festgelegt ist: eine Anzahl, einen „einzigen Aufrufer“, eine Aussage über Daten. Eine hatte eine Sicherheitsbegründung entfernt. Konsequenz: eine Regel, dass Kommentare das Warum und die Invariante neben dem Code festhalten, den sie schützen, nie Tatsachen, die einer anderen Datei gehören – dazu eine Hygienewarnung, wenn ein Kommentar eine gelöschte Datei nennt.

Abwägungen

  • Mehr Leitplanken, mehr Pflege. Jede Regel braucht Testfälle, eine Begründung für jede Ausnahme und Pflege, wenn sich die Architektur ändert. Meine Messlatte: Eine Fehlerregel muss eine echte Invariante abbilden, die aktuell null Verstöße hat. Alles Schwächere bleibt Warnung oder Review-Konvention.
  • Mehr Kontext ist nicht besserer Kontext. Das Routing lädt bewusst ein bis drei Konzeptdateien, nicht die ganze Wissensschicht. Das lässt dem Agenten Raum zum Denken – mit dem Risiko, dass ein relevantes Konzept nie geroutet wird.
  • Langsamere lokale Abläufe. Der Pre-Push-Hook führt die Typprüfung und Tausende Unit-Tests aus. Diese Minuten nehme ich in Kauf, damit eine kaputte Änderung selten meinen Rechner verlässt.
  • Delegation kostet Zeit. Arbeit an einen Subagenten abzugeben spart Kontext des primären Agenten, ist aber nachweislich langsamer, wenn sie Schritt für Schritt geschieht. Sie lohnt sich bei großer Recherche oder parallelen Untersuchungen, nicht bei einer einzelnen bekannten Datei.
  • Zentrales Wissen kann veralten. Explizites Wissen ist nur nützlich, solange es stimmt. Aktualitätsprüfung, Quellenangaben und die Regel gegen wiederholte Fakten sind der Preis dafür, es ehrlich zu halten.
  • Guards sind keine Sandboxen. Mustererkennende Guards sind einfach und nachvollziehbar, aber keine Sicherheitsgrenze. Die eigentlichen Gates sind die, die jede Änderung unabhängig von ihrer Herkunft passiert.

Was menschlich bleibt

Agenten entscheiden nicht, ob etwas existieren soll. Ich entscheide, was gebaut wird und warum; ob eine Abstraktion gerechtfertigt oder eine Dopplung vertretbar ist; wie sich eine Oberfläche anfühlen soll; was eine mehrdeutige Anforderung bedeutet; und ob ein Experiment ausgeliefert wird. Experimente enden hier mit einem Urteil gegen Kriterien, die vor dem ersten Lauf feststanden, und einige der nützlichsten Urteile in diesem Repository sind Ablehnungen. Ich prüfe jede Änderung und mache jeden Commit; eine KI entwirft die Commit-Nachricht aus dem vorgemerkten Diff, und ich bestätige sie.

Ergebnis

Was die Architektur leistet und was ich zeigen kann:

  • Relevante Architekturverstöße sind maschinell erkennbar, mit derselben Regel lokal und in CI.
  • Ein Agent beginnt eine Aufgabe, indem er den eigenen Kontext des Repositorys für diese Art von Aufgabe abruft, nicht allgemeine Ratschläge oder eigene Vermutungen.
  • Validierung läuft, bevor eine Änderung meinen Rechner verlässt, und noch einmal, bevor sie ausgeliefert werden kann.
  • Architekturwissen ist aufgeschrieben, belegt und gegen den Quelltext geprüft, statt nur in meinem Kopf zu existieren.
  • Von KI geschriebene Änderungen passieren genau dieselben Gates wie meine.

Einen Produktivitätsfaktor behaupte ich nicht. Was ich sagen kann, ist enger: Fehler, die hier gemacht wurden, von mir oder von einem Agenten, wurden zu Prüfungen, und jede Prüfung gilt jetzt für jede folgende Änderung.

Weiterlesen

Das Engineering-Journal erzählt Teile dieser Geschichte in erzählender Form: Vom Portfolio zur KI-gesteuerten Engineering-Plattform, Agentenautomatisierung, ohne die Kontrolle zu verlieren, KI braucht nicht mehr Kontext – sie braucht besseren Kontext und Deterministische KI-Workflows rund um Claude gestalten. Die Fallstudie zum Fotografie-Assistenten wendet dasselbe Prinzip auf ein produktives LLM-Feature an.