Konformitatsregeln (Guardrails)
Konformitatsregeln sind deterministische Pruefungen, die Codeanderungen gegen Ihre architektonischen Entscheidungen validieren. Sie erzwingen Namenskonventionen, Technologiebeschraenkungen, Schichtgrenzen und Sicherheitsmuster — ohne jegliche KI.
Navigieren Sie zu Agent Hub in der Seitenleiste, um Ihre Konformitatsregeln zu verwalten.
Warum Konformitatsregeln?
Wenn KI-Codierungsagenten (Claude Code, Cursor, Copilot) Code generieren, kennen sie Ihre architektonischen Entscheidungen nicht. Konformitatsregeln kodieren diese Entscheidungen als ausfuehrbare Einschraenkungen:
- Der Agent kann MongoDB nicht verwenden, wenn Ihr Technologieradar PostgreSQL vorschreibt
- Der Agent kann keine Datenbankaufrufe in HTTP-Handler platzieren, wenn Ihre Architektur eine Service-Schicht erfordert
- Der Agent kann kein
fmt.Printlnhinzufuegen, wenn Ihr Team strukturiertes Logging verwendet
Regeln werden deterministisch ausgewertet — kein LLM, keine probabilistische Ausgabe. Derselbe Code erzeugt immer dasselbe Ergebnis.
Regeltypen
Archyl unterstuetzt sieben Typen von Konformitatsregeln:
Erforderliches Pattern
Pruefen, ob Patterns in Ihrem Code vorhanden sein muessen oder nicht vorhanden sein duerfen.
| Anwendungsfall | Beispiel |
|---|---|
| Debug-Logging verbieten | fmt.Println, console.log, print() verbieten |
| Sicherheitsrisiken verbieten | eval(), innerHTML, hartcodierte Passwoerter verbieten |
| Fehlerbehandlung erfordern | set -euo pipefail in Shell-Skripten erfordern |
| Standards durchsetzen | SELECT * in SQL-Abfragen verbieten |
Konfiguration:
- File glob — Nur Dateien pruefen, die einem Muster entsprechen (z.B.
*.go,*.ts) - Verbotene Patterns — Regex-Muster, die eine Verletzung ausloesen, wenn sie gefunden werden
- Erforderliche Patterns — Regex-Muster, die eine Verletzung ausloesen, wenn sie fehlen
Namenskonvention
Namenspatterns fuer Dateien, Typen und Funktionen validieren.
| Geltungsbereich | Beispiel |
|---|---|
| Datei | Go-Dateien muessen snake_case.go sein |
| Typ | Exportierte Typen muessen PascalCase sein |
| Funktion | Funktionen sollten mit einem Verb beginnen (Get, Create, Delete) |
Konfiguration:
- Patterns — Liste von Geltungsbereich (Datei/Typ/Funktion) + Regex + Beschreibung
Technologiebeschraenkung
Einschraenken, welche Sprachen und Bibliotheken in einem Container erlaubt sind.
| Anwendungsfall | Beispiel |
|---|---|
| Sprachbindung | Backend darf nur Go sein |
| Abhaengigkeitsverbot | Kein lodash (natives JS verwenden) |
| Migrationsdurchsetzung | Kein moment.js (date-fns verwenden) |
Konfiguration:
- Erlaubte Sprachen — Kommagetrennte Liste (z.B.
go, typescript) - Verbotene Imports — Ein Import pro Zeile
Schichtgrenze
Clean Architecture, Hexagonale Architektur oder DDD-Schicht-Importregeln durchsetzen.
| Schicht | Kann importieren von |
|---|---|
| Domain | Nichts (reine Geschaeftslogik) |
| Service | Nur Domain |
| Adapter | Domain, Service |
| Infrastructure | Nur Domain |
Konfiguration:
- Schichten — Jede Schicht mit einem Namen, Pfadmuster (glob) und erlaubten Importquellen definieren
- Klicken Sie auf Schichtnamen, um Importberechtigungen umzuschalten
Vertragskonformitaet
Validieren, dass Code-Endpoints mit Ihren in Archyl gespeicherten API-Vertraegen uebereinstimmen.
Konfiguration:
- Vertragstyp — HTTP (OpenAPI), gRPC, GraphQL oder AsyncAPI
- Endpoint-Dateimuster — Globs fuer Dateien mit Endpoint-Definitionen
- Strikter Modus — Wenn aktiviert, loest jeder Endpoint, der nicht im Vertrag steht, eine Verletzung aus
Abhaengigkeitsregel
Sicherstellen, dass Abhaengigkeiten zwischen Komponenten dem C4-Beziehungsmodell entsprechen.
Konfiguration:
- Geltungsbereich — Container- oder Komponentenebene
- Beziehung muss existieren — Jeder Code-Import muss eine entsprechende C4-Beziehung haben
- Verbotene Paare — Bestimmte Elementpaare, die niemals voneinander abhaengen duerfen
Event-Channel-Konformitaet
Validieren, dass Event-Produzenten/Konsumenten im Code mit deklarierten EventChannels uebereinstimmen.
Konfiguration:
- Produzenten-Patterns — Regex-Muster zur Identifikation von Event-Produktionscode
- Konsumenten-Patterns — Regex-Muster zur Identifikation von Event-Konsumptionscode
- Topic-Regex — Muster zum Extrahieren von Topic-Namen aus dem Code
Regelpakete
Pakete sind kuratierte Sammlungen von Regeln, die Sie mit einem Klick installieren koennen. Anstatt Regeln einzeln hinzuzufuegen, installieren Sie ein Paket und erhalten ein komplettes Regelset fuer Ihren Stack.
Klicken Sie auf Packs in der Toolbar, um verfuegbare Pakete zu durchsuchen.
Architektur-Pakete
| Paket | Regeln | Was es durchsetzt |
|---|---|---|
| Clean Architecture | 5 | Domain/Service/Adapter/Infra-Schichtgrenzen, Modul-Isolation |
| Hexagonal Architecture | 4 | Ports & Adapters Pattern, Kern-Isolation |
| Domain-Driven Design | 3 | DDD-Schichten, CQRS Command/Query-Trennung |
Sprach-Pakete
| Paket | Regeln | Was es abdeckt |
|---|---|---|
| Go Backend | 26 | Error-Wrapping, Goroutine-Sicherheit, Context-Propagation, Benennung, kein panic, kein init() |
| React Frontend | 23 | TypeScript-Strenge, Komponenten-Patterns, Datenabruf, keine DOM-Manipulation |
| Next.js Full-Stack | 20 | React-Regeln + SSR-Sicherheit, Window-Guards, localStorage-Hooks |
| Python Backend | 16 | Exception-Handling, Async-Patterns, Type Hints, kein globaler State |
| Java Backend | 11 | Spring DI-Patterns, Exception-Handling, kein System.exit |
| Rust Backend | 8 | Kein unwrap/unsafe, korrekte Error-Typen, kein todo!() |
| Kotlin / Android | 5 | Null-Sicherheit, Unveraenderlichkeit, kein println |
| Vue Frontend | 10 | Kein v-html, TypeScript-Strenge, kein innerHTML |
| .NET / C# Backend | 5 | Async-Patterns, Exception-Handling, ILogger |
| Swift / iOS | 3 | Optional-Sicherheit, kein Force Unwrap |
Domain-Pakete
| Paket | Regeln | Was es abdeckt |
|---|---|---|
| Security Essentials | 17 | Hartcodierte Geheimnisse, Injection, schwache Krypto, TLS, CORS |
| DevOps & Infrastructure | 24 | Docker, Kubernetes, Terraform, GitHub Actions, Shell-Skripte |
| API Best Practices | 9 | Statuscodes, SQL-Sicherheit, Vertragsdokumentation, keine hartcodierten URLs |
| Testing & Reliability | 5 | Keine uebersprungenen Tests, kein .only(), kein sleep, kein TODO |
| Event-Driven Architecture | 3 | Kafka/RabbitMQ Topic-Benennung, keine hartcodierten Topics |
Regelkatalog
Archyl wird mit einem Katalog von 170+ vorgefertigten Regeln fuer 24 Technologien geliefert. Durchsuchen Sie den Katalog, indem Sie im Agent Hub auf Catalog klicken.
Abgedeckte Technologien
Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, React, Vue, Angular, Next.js, Docker, Kubernetes, Terraform, SQL, Shell, YAML, GitHub Actions
Kategorien
| Kategorie | Beispiele |
|---|---|
| Architecture & Design | Clean Architecture, Hexagonal, DDD, MVC, handler-service-repository |
| Sicherheit | Keine hartcodierten Geheimnisse, kein eval(), keine SQL-Injection, kein deaktiviertes TLS, kein CORS-Wildcard |
| Codequalitaet | Kein Debug-Logging, keine leeren Catch-Bloecke, kein bare except, kein any-Typ, kein unwrap() |
| Infrastructure & DevOps | Docker-Versionen pinnen, K8s-Ressourcenlimits, keine privilegierten Container, Terraform-Tags |
| Namenskonventionen | snake_case, PascalCase, camelCase je nach Sprache |
| Tests & Zuverlaessigkeit | Keine uebersprungenen Tests, kein .only(), kein TODO/FIXME |
| Performance | Kein synchroner Sleep, keine N+1-Abfragen, kein await in Schleifen |
| API & Daten | Kein rohes SQL, korrekte HTTP-Statuscodes, Request-Bodies validieren |
Klicken Sie auf eine beliebige Regel im Katalog, um sie hinzuzufuegen — das Konfigurationsformular wird automatisch ausgefuellt.
Schweregrade
Jede Regel hat einen Schweregrad, der ihre Auswirkung bestimmt:
| Schweregrad | Bedeutung | Beispiel |
|---|---|---|
| Critical | Muss vor dem Merge behoben werden | Keine hartcodierten Geheimnisse, kein eval(), Schichtgrenzverletzungen |
| High | Sollte vor dem Merge behoben werden | Kein Debug-Logging, Docker-Versionen pinnen, kein panic in Go |
| Medium | Bei Gelegenheit beheben | Namenskonventionen, kein any-Typ, kein var in JS |
| Low | Informativ | Kein TODO/FIXME, keine Inline-Styles in React |
Regelverwaltung
Regeln erstellen
- Klicken Sie auf Packs, um ein kuratiertes Regelset fuer Ihren Stack zu installieren, oder
- Klicken Sie auf Catalog, um aus den 170+ vorgefertigten Regeln auszuwaehlen, oder
- Klicken Sie auf Custom, um eine neue manuell zu erstellen
Regeln aktivieren/deaktivieren
Schalten Sie den Schalter neben einer Regel um, um sie zu aktivieren oder zu deaktivieren. Deaktivierte Regeln werden nicht ausgewertet.
Regeln bearbeiten
Klicken Sie auf das Bearbeitungssymbol (Stift) bei einer Regel, um deren Namen, Beschreibung, Schweregrad oder Konfiguration zu aendern.
Regeln loeschen
Klicken Sie auf das Loeschsymbol (Papierkorb) und bestaetigen Sie. Dies kann nicht rueckgaengig gemacht werden.
Regeln filtern
- Suche — Nach Regelname oder Beschreibung filtern
- Typfilter — Klicken Sie auf Typ-Pills, um nur Regeln eines bestimmten Typs anzuzeigen
CI/CD-Integration
Konformitatsregeln koennen automatisch bei jedem Pull Request ausgefuehrt werden. Siehe GitHub Actions Integration fuer Einrichtungsanweisungen.
Funktionsweise
- Ein PR wird auf GitHub geoeffnet oder aktualisiert
- Die Archyl GitHub Action holt die geaenderten Dateien
- Die Dateien werden zur Auswertung an die Archyl API gesendet
- Ergebnisse erscheinen als PR-Kommentar und Commit-Status
- Der Workflow schlaegt fehl, wenn kritische oder hohe Verletzungen gefunden werden
PR-Kommentar
Wenn Verletzungen gefunden werden, postet Archyl einen detaillierten Kommentar auf dem PR:
- Zusammenfassungstabelle mit Verletzungsanzahl nach Schweregrad
- Verletzungen pro Datei mit Beschreibungen und Vorschlaegen
- Der Kommentar wird bei nachfolgenden Pushes aktualisiert (nicht dupliziert)
MCP-Integration
Konformitatsregeln sind fuer KI-Agenten ueber den MCP-Server zugaenglich:
Verfuegbare MCP-Tools
| Tool | Beschreibung |
|---|---|
list_conformance_rules |
Alle Regeln mit optionalem Projektfilter auflisten |
create_conformance_rule |
Eine neue Regel erstellen |
update_conformance_rule |
Regelkonfiguration, Schweregrad oder Aktivierungsstatus aktualisieren |
delete_conformance_rule |
Eine Regel loeschen |
get_agent_context |
Den vollstaendigen architektonischen Kontext inklusive aktiver Guardrails abrufen |
Agentenkontext
Das MCP-Tool get_agent_context gibt alle aktiven Konformitatsregeln als Teil des architektonischen Briefings zurueck. KI-Agenten, die dieses Tool vor Arbeitsbeginn aufrufen, wissen, welche Guardrails zu beachten sind.
Der Kontext umfasst auch:
- C4 model (Systeme, Container, Komponenten, Beziehungen)
- Aktive ADRs mit Begruendung
- Technologie-Stack
- API-Vertraege
- Event-Channels
REST API
Konformitatsregeln sind auch ueber die REST API verfuegbar:
GET /api/v1/conformance/rules # Regeln auflisten
POST /api/v1/conformance/rules # Regel erstellen
POST /api/v1/conformance/rules/bulk # Mehrere Regeln erstellen (von Paketen verwendet)
GET /api/v1/conformance/rules/:id # Regel abrufen
PUT /api/v1/conformance/rules/:id # Regel aktualisieren
DELETE /api/v1/conformance/rules/:id # Regel loeschen
POST /api/v1/conformance/rules/:id/toggle # Aktivieren/deaktivieren
POST /api/v1/projects/:id/conformance/check # Pruefung mit geaenderten Dateien ausloesen
GET /api/v1/projects/:id/conformance/checks # Pruefungshistorie auflisten
GET /api/v1/conformance/checks/:id/report # Pruefungsbericht abrufen
GET /api/v1/projects/:id/conformance/stats # Projektstatistiken abrufen
Alle Endpoints erfordern Authentifizierung (JWT oder API-Schluessel mit Schreibberechtigung fuer Mutationen).