Konformitätsregeln (Guardrails)

Konformitätsregeln sind deterministische Prüfungen, die Codeänderungen gegen Ihre Architekturentscheidungen validieren. Sie setzen Namenskonventionen, Technologievorgaben, Schichtgrenzen und Sicherheitsmuster durch — ganz ohne KI.

Öffnen Sie in der Seitenleiste den Agent Hub, um Ihre Konformitätsregeln zu verwalten.

Warum Konformitätsregeln?

Wenn KI-Coding-Agenten (Claude Code, Cursor, Copilot) Code generieren, kennen sie Ihre Architekturentscheidungen nicht. Konformitätsregeln bilden diese Entscheidungen als ausführbare Vorgaben ab:

• Der Agent kann MongoDB nicht verwenden, wenn Ihr Technologieradar PostgreSQL vorsieht
• Der Agent kann keine Datenbankaufrufe in HTTP-Handler legen, wenn Ihre Architektur eine Service-Schicht verlangt
• Der Agent kann kein fmt.Println hinzufügen, wenn Ihr Team strukturiertes Logging verwendet

Regeln werden deterministisch ausgewertet — kein LLM, keine probabilistische Ausgabe. Derselbe Code liefert immer dasselbe Ergebnis.

Regeltypen

Archyl unterstützt sieben Typen von Konformitätsregeln:

Erforderliches Muster

Prüft auf Muster, die in Ihrem Code vorkommen müssen oder nicht vorkommen dürfen.

Konfiguration:

• File glob — Nur Dateien prüfen, die einem Muster entsprechen (z. B. *.go, *.{ts,tsx})
• Forbidden patterns — Regex-Muster, die eine Verletzung auslösen, wenn sie gefunden werden
• Required patterns — Regex-Muster, die eine Verletzung auslösen, wenn sie fehlen

Datei-Globs unterstützen Klammererweiterung: *.{js,jsx,ts,tsx} erfasst alle JavaScript- und TypeScript-Dateien.

Namenskonvention

Validiert Namensmuster für Dateien, Typen und Funktionen.

Konfiguration:

• Patterns — Liste aus Geltungsbereich (Datei/Typ/Funktion) + Regex + Beschreibung

Technologiebeschränkung

Schränkt ein, welche Sprachen und Bibliotheken in einem Container erlaubt sind.

Konfiguration:

• Allowed languages — Kommagetrennte Liste (z. B. go, typescript)
• Forbidden imports — Ein Import pro Zeile

Schichtgrenze

Setzt Importregeln zwischen Schichten nach Clean Architecture, hexagonaler Architektur oder DDD durch.

Konfiguration:

• Layers — Definieren Sie jede Schicht mit einem Namen, einem Pfadmuster (Glob) und den erlaubten Importquellen
• Klicken Sie auf Schichtnamen, um Importberechtigungen umzuschalten

Vertragskonformität

Validiert, dass Endpoint-Handler-Dateien eine korrekte API-Vertragsdokumentation enthalten.

Konfiguration:

• Contract type — HTTP (OpenAPI), gRPC, GraphQL oder AsyncAPI
• Endpoint file patterns — Globs für Dateien mit Endpoint-Definitionen
• Strict mode — Wenn aktiviert, löst jede passende Datei ohne Vertragsdokumentation eine Verletzung aus

Abhängigkeitsregel

Setzt verbotene Importpfade zwischen Architekturgrenzen durch.

Konfiguration:

• Scope — Container- oder Komponentenebene
• Forbidden pairs — Quell- und Zielpfadmuster, die niemals voneinander abhängen dürfen (z. B. **/service/** -> **/handler/**)

Event-Kanal-Konformität

Validiert, dass die Muster von Event-Produzenten und -Konsumenten Namenskonventionen folgen.

Konfiguration:

• Producer patterns — Regex-Muster, die Code zum Erzeugen von Events erkennen (z. B. kafka\.Send)
• Consumer patterns — Regex-Muster, die Code zum Konsumieren von Events erkennen
• Topic regex — Muster, dem gültige Topic-Namen entsprechen müssen (z. B. ^[a-z]+\.[a-z]+\.[a-z]+$)

Regelpakete

Pakete sind kuratierte Sammlungen von Regeln, die Sie mit einem Klick installieren. Statt Regeln einzeln hinzuzufügen, installieren Sie ein Paket und erhalten einen vollständigen Regelsatz für Ihren Stack.

Klicken Sie in der Toolbar auf Packs, um die verfügbaren Pakete zu durchsuchen.

Architekturpakete

Sprachpakete

Domänenpakete

Regelkatalog

Archyl liefert einen Katalog mit 169 vorgefertigten Regeln für 23 Technologien mit. Öffnen Sie den Katalog im Agent Hub mit einem Klick auf Katalog durchsuchen.

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

Klicken Sie im Katalog auf eine beliebige Regel, um sie hinzuzufügen — das Konfigurationsformular wird automatisch vorausgefüllt.

Schweregrade

Jede Regel hat einen Schweregrad, der ihre Auswirkung bestimmt:

Eine Konformitätsprüfung schlägt fehl, sobald kritische oder hohe Verletzungen gefunden werden. Mittlere und niedrige Verletzungen werden gemeldet, lassen die Prüfung aber nicht fehlschlagen.

Konformitäts-Dashboard

Der Tab Dashboard im Agent Hub bietet einen Echtzeit-Überblick über alle Konformitätsprüfungen Ihrer Projekte.

Was angezeigt wird

• Statistikkarten — Gesamtzahl der Prüfungen, Erfolgsrate (farbcodiert), Anzahl bestandener und Anzahl fehlgeschlagener Prüfungen
• Verhältnis Bestanden / Fehlgeschlagen — Balken, der das Verhältnis auf einen Blick zeigt
• Banner zur letzten Prüfung — Status der jüngsten Prüfung mit Link zum vollständigen Bericht
• Liste der letzten Prüfungen — Alle Prüfungen mit Status, Auslöser, Projektname, Anzahl der Dateien, Anzahl der Verletzungen und vergangener Zeit

Filtern

Filtern Sie die Prüfungen über das Projekt-Dropdown oben nach Projekt, oder wählen Sie "Alle Projekte", um alles zu sehen.

Prüfberichte

Klicken Sie auf eine beliebige Prüfung, um den vollständigen Bericht zu öffnen:

• Balken der Schweregradverteilung — Anteilige Darstellung der kritischen, hohen, mittleren und niedrigen Verletzungen
• Verletzungen nach Datei gruppiert — Aufklappbare Abschnitte mit Schweregrad, Titel, Beschreibung und Vorschlag für jede Verletzung
• Prüfungsdetails — Auslöser, Commit-SHA, Startzeit, Dauer

Jeder Prüfbericht hat eine eigene teilbare URL (z. B. /agent/dashboard/:checkId).

Prüfungen löschen

Mit der Mehrfachauswahl löschen Sie mehrere Prüfungen auf einmal:

1. Aktivieren Sie die Checkboxen neben einzelnen Prüfungen oder verwenden Sie "Alle auswählen"
2. Klicken Sie auf die rote Schaltfläche Delete, die daraufhin erscheint
3. Die Prüfungen und ihre Verletzungen werden endgültig entfernt

CI/CD-Integration

Konformitätsregeln können bei jedem Pull Request automatisch ausgeführt werden. Die Einrichtung ist unter GitHub-Actions-Integration beschrieben.

Funktionsweise

1. Ein PR wird auf GitHub geöffnet oder aktualisiert
2. Die Archyl GitHub Action ruft die geänderten Dateien ab
3. Die Dateien werden zur Auswertung an die Archyl-API gesendet
4. Die Ergebnisse erscheinen als PR-Kommentar und als Commit-Status-Check
5. Der Workflow schlägt fehl, wenn kritische oder hohe Verletzungen gefunden werden

PR-Kommentar

Werden Verletzungen gefunden, veröffentlicht Archyl einen ausführlichen Kommentar im PR:

• Übersichtstabelle mit der Anzahl der Verletzungen je Schweregrad
• Verletzungen pro Datei mit Beschreibungen und Vorschlägen
• Der Kommentar wird bei weiteren Pushes aktualisiert (nicht dupliziert)

Regeln verwalten

Regeln erstellen

1. Klicken Sie auf Packs, um einen kuratierten Regelsatz für Ihren Stack zu installieren, oder
2. Klicken Sie auf Katalog durchsuchen, um aus den 169 vorgefertigten Regeln auszuwählen, oder
3. Klicken Sie auf Benutzerdefinierte Regel, um eine neue Regel manuell zu erstellen

Regeln aktivieren/deaktivieren

Mit dem Schalter neben einer Regel aktivieren oder deaktivieren Sie sie. Deaktivierte Regeln werden nicht ausgewertet.

Regeln bearbeiten

Klicken Sie bei einer Regel auf das Bearbeiten-Symbol (Stift), um Name, Beschreibung, Schweregrad oder Konfiguration zu ändern.

Regeln löschen

Klicken Sie auf das Löschen-Symbol (Papierkorb) und bestätigen Sie. Dieser Schritt lässt sich nicht rückgängig machen.

Regeln filtern

• Suche — Nach Regelname oder Beschreibung filtern
• Typfilter — Klicken Sie auf die Typ-Pills, um nur Regeln eines bestimmten Typs anzuzeigen

MCP-Integration

KI-Agenten greifen über den MCP-Server auf Konformitätsregeln zu:

Verfügbare MCP-Tools

Prüfungen aus einem Agenten ausführen

Mit dem Tool run_conformance_check validieren KI-Agenten Code, bevor sie ihn committen. Der Agent sendet die Dateien, an denen er arbeitet:

{
  "projectId": "your-project-uuid",
  "changedFiles": [
    { "path": "internal/handler/user.go", "status": "modified" }
  ],
  "fileContents": {
    "internal/handler/user.go": "package handler\nimport..."
  }
}

Die Antwort enthält:

• passed — Ob die Prüfung bestanden wurde (keine kritischen oder hohen Verletzungen)
• violations — Liste der Verletzungen mit Schweregrad, Dateipfad, Titel und Vorschlag
• rulesEvaluated — Welche Regeln ausgewertet wurden
• filesAnalyzed — Wie viele Dateien analysiert wurden
• checkId — Die ID der Prüfung (im Dashboard sichtbar)

Mit diesem Feedback kann der Agent Verletzungen beheben, bevor der Code committet wird.

Agentenkontext

Das MCP-Tool get_agent_context liefert alle aktiven Konformitätsregeln als Teil des Architektur-Briefings. KI-Agenten, die dieses Tool vor Arbeitsbeginn aufrufen, wissen, welche Leitplanken sie einhalten müssen.

REST API

# Rules
GET    /api/v1/conformance/rules              # List rules
POST   /api/v1/conformance/rules              # Create rule
POST   /api/v1/conformance/rules/bulk         # Create multiple rules (used by packs)
GET    /api/v1/conformance/rules/:id          # Get rule
PUT    /api/v1/conformance/rules/:id          # Update rule
DELETE /api/v1/conformance/rules/:id          # Delete rule
POST   /api/v1/conformance/rules/:id/toggle   # Enable/disable

# Checks
POST   /api/v1/projects/:id/conformance/check # Trigger check with changed files
GET    /api/v1/conformance/checks             # List all checks (org-wide, ?projectId= filter)
GET    /api/v1/conformance/checks/:id/report  # Get check report with violations
POST   /api/v1/conformance/checks/delete      # Bulk delete checks { ids: [...] }

# Stats
GET    /api/v1/conformance/stats              # Org-wide statistics
GET    /api/v1/projects/:id/conformance/stats  # Project statistics

Alle Endpoints erfordern eine Authentifizierung (JWT oder API-Schlüssel mit Schreibberechtigung für Mutationen).