Architekturgrenzen automatisch prüfen
#Ein Agent liefert deutlich bessere Arbeit, wenn seine Umgebung ihm sofort und automatisch zeigt, was «korrekt» bedeutet. Pre-Flight-Checks schaffen genau diese Umgebung: Linting, Type-Checking, Tests und – was viele Teams auslassen – Checks, die Architekturgrenzen automatisch durchsetzen. Verletzt ein Modul eine Grenze, schlägt ein Check fehl, statt dass der Fehler erst im Review auffällt.
Im Frontend-Modul des Referenzprojekts laufen diese Prüfungen zweimal: im Pre-Commit-Hook und noch einmal in der CI-Pipeline. Der Hook fängt ganze Fehlerklassen ab, bevor eine Änderung überhaupt committet wird. Der Agent kann einen fehlgeschlagenen Check lesen, verstehen, was beanstandet wurde, das Problem im selben Durchlauf beheben und die Checks erneut starten. So wird schon ein einzelner Durchlauf besser, denn das erste Review machen die Checks, nicht ein Mensch.
Bei Architekturgrenzen funktioniert das genauso. Statt zu hoffen, dass jemand eine Architekturregel im richtigen Moment beachtet, formuliert man sie als Check. Der Agent arbeitet dadurch von vornherein innerhalb der vorgegebenen Leitplanken. Pre-Flight-Checks sind mit wenig Aufwand umzusetzen und zahlen sich bei jedem Durchlauf aus. Kaum eine Investition bringt bei agentengestützter Entwicklung mehr.
Konkret durchläuft jeder Commit dasselbe Gate. Zuerst prüft es die Formatierung der geänderten Dateien und führt Linting, Type-Checking und Tests aus – für die von der Änderung betroffenen Packages und für alle, die von ihnen abhängen. Anschliessend laufen dreissig weitere Checks, höchstens vier gleichzeitig. Jeder davon prüft eine projektspezifische Regel, von der ein allgemeiner Linter nichts wissen kann:
- Navigations-RegistryJeder Navigationseintrag zeigt auf eine existierende Route, keiner ist doppelt, und keine Plattform überschreitet ihr Tab-Budget.
- Routen-ParitätJede gemeinsame Route der Referenz-App existiert auch in jeder Whitelabel-App.
- App-IconsIcon- und Splash-Assets liegen in den geforderten Dimensionen vor, und die App-Manifeste zeigen auf die Dateien, die tatsächlich da sind.
- Admin-GuardsJede Admin-Seite und jedes Admin-Layout bindet den Session-Guard ein, jedes Admin-Layout erzwingt dynamisches Rendering, und jede Seite, die auf einer eigenen Liste steht, prüft zusätzlich, ob der Aufrufer den Mandanten aus ihrer URL verwaltet.
- Sticky-Footer-AbdeckungJede Seite mit Endlos-Scrolling ist für den Sticky Footer registriert, damit Impressum und Datenschutz auch unter einer endlos nachladenden Liste erreichbar bleiben.
- Doku-AbdeckungDie Doku-Site enthält für jedes katalogisierte Feature eine eigene Seite.
- Sprach-ParitätDie Menge der unterstützten Sprachen stimmt an allen vier Stellen überein, an denen sie unabhängig deklariert wird.
- Marken-VollständigkeitJede Marke ist in jeder Registry verdrahtet, die von ihr wissen muss, bis hin zu Logo, Secret-Referenz und Testprojekt.
- Marken-SEOSEO-Blöcke sind pro Marke vorhanden, voneinander verschieden und ohne zurückgebliebene Test-Platzhalter.
- MarkenkontrastDie Farben jeder Whitelabel-Marke erreichen im hellen und im dunklen Modus den WCAG-Kontrast, gedrückte Zustände heben sich sichtbar vom Normalzustand ab, und eine genehmigte Ausnahme gilt nur bis zu ihrem Ablaufdatum.
- Agent-Docs-StrukturDie Agentendokumentation erfüllt dreizehn strukturelle Regeln, darunter Grössenbudgets und einen Lebenszyklus-Status pro Dokument.
- Agent-Docs-AktualitätDie Pfade und Befehle, die diese Dokumente zitieren, existieren noch.
- Shell-Skript-LintDie Shell-Skripte des Commit-Gates werden mit ShellCheck geprüft, und der Check lehnt jede ShellCheck-Version unter der festgelegten Mindestversion ab – so kann eine ältere lokale Installation nicht durchlassen, was die CI beanstandet.
- RechtsdokumenteDie Rechtstexte jeder Marke sind vorhanden, decken jede Sprache ab, die diese Marke anbietet, und bleiben innerhalb des erlaubten HTML-Vokabulars.
- RechtsversionenÄndert sich ein Rechtsdokument, muss seine Versionsnummer steigen; bei Nutzungsbedingungen und Datenschutzerklärung muss die Einstufung der Änderung zur Grösse des Versionssprungs passen und darf sich innerhalb einer Release-Linie nicht ändern. Geprüft wird jeweils gegen den vorherigen Commit.
- Mobile Kanal-SprachenTexte für Notification-Kanäle existieren in jeder geforderten Sprache, mit denselben Schlüsseln.
- Design-TokensKein reines Web-Token gelangt in Mobile-Code, wo es stillschweigend zu nichts aufgelöst würde.
- Text-DeckkraftKeine kontrastgeprüfte Textfarbe wird per Opacity-Modifier abgeschwächt – das würde sie unter ihren Mindestkontrast drücken.
- Import-FirewallDie öffentlichen SDK-Packages importieren nichts aus den internen Packages und aus dem gemeinsamen Message-Contract nur Typen, damit kein interner Code bei Dritten landet.
- Widget-TierDie einbettbaren Widget-Routen halten, was sie einer fremden Seite versprechen: keine Client-Komponente ausserhalb der Allowlist, kein eingehender Message-Listener, kein Provider-Stack und kein Import, der die Routengruppe verlässt.
- API-PräfixeJedes URL-Präfix, unter dem die generierten Clients Endpunkte aufrufen, ist als browserseitig oder dienstintern eingestuft, und die Allowlist des Backend-Proxys enthält genau die browserseitigen – nicht mehr und nicht weniger.
- VerfügbarkeitsfilterJede Datei, die Verfügbarkeitsfilter setzt, verwendet entweder eine gemeinsame, vollständige Vorgabe oder ist nach Prüfung ausdrücklich als Sonderfall erfasst – denn das Backend schaltet manche weggelassenen Filter standardmässig ein, und bestimmte unvollständige Kombinationen liefern dann ohne Fehlermeldung eine leere Liste.
- Dockerfile-AbhängigkeitenJede Workspace-Abhängigkeit der Web-App wird im Image-Build auch wirklich kopiert.
- Notification-RoutenJedes Notification-Ereignis ist ausdrücklich einem Screen zugeordnet oder ausdrücklich ohne Ziel eingetragen, und jeder zugeordnete Screen existiert im Web und in der Mobile-App und ist als App-Link registriert.
- Typen der End-to-End-TestsAuch die Browser-Test-Suite wird typgeprüft – sie liegt ausserhalb des Workspaces, deshalb erreicht die repositoryweite Typprüfung sie nie.
- Lint der End-to-End-TestsEigene Lint-Regeln für die Browser-Test-Suite finden Assertions, die nie ausgeführt werden, und Tests, die versehentlich noch übersprungen werden.
- Aktualität generierter KonfigurationDie eingecheckte generierte Konfiguration passt noch zu der Quelle, aus der sie erzeugt wurde.
- Index der Mock-HandlerDer Index der API-Mock-Handler stimmt mit den tatsächlich generierten Handlern überein, damit kein Endpunkt unbemerkt aus den Tests fällt.
- Isolierte Test-MocksHandgeschriebene Test-Mocks liegen nie in Code, den andere Packages mitverwenden – sonst ersetzen sie das echte Modul in den Tests jedes abhängigen Packages.
- CI-DriftDie Pipelines für Pull-Requests und für den Main-Branch reagieren auf dieselben Pfade, und jeder CI-Check läuft auch bei jedem lokalen Commit, es sei denn, er ist namentlich und mit Begründung ausgenommen – so landet kein Check mehr versehentlich nur in der CI.
Interessant an dieser Liste ist weniger der einzelne Eintrag als das Muster dahinter. Fast nichts davon ist allgemeine Codequalität; es ist Wissen, das sonst ein Reviewer im Kopf haben müsste – so festgeschrieben, dass es niemand mehr vergessen kann.