Dokumentation · Konzepte
Baseline und Stack-Packs, blockierende und meldende Regeln, eigene Regel-Pakete, die Kanäle fast/stable und der signierte, öffentlich einsehbare Katalog.
Guardrails sind die Regeln, an die sich jeder Lauf hält — nicht als Nachlese am Ende, sondern schon beim Erzeugen jedes einzelnen Arbeitsschritts. Dieses Kapitel erklärt das Konzept dahinter: den Guardrail-Katalog. Wie du eigene Regeln anlegst und Vorschläge aus dem Lauf-Lernen freigibst, beschreibt Guardrails & Stack-Profile.
Was ein Guardrail-Pack ist
Ein Guardrail-Pack ist ein Bündel zusammengehöriger Regeln für einen Technologie-Stack — etwa für Spring Boot oder React/Vite. Jede Regel darin fliesst in den KI-Prompt ein, bevor Code entsteht, und wird danach noch einmal geprüft. Ein Verstoss ist damit kein nachträglicher Kommentar in einem Review, sondern ein Befund am Lauf selbst.
Zwei Ebenen bilden den Grundstock jedes Projekts:
- Baseline — plattformweite Mindeststandards, die für jeden Stack gelten, unabhängig von der gewählten Technologie.
- Stack-Packs — Regeln für einen bestimmten Stack, zum Beispiel Spring Boot, Node/Web oder React/Vite. Ein Projekt bekommt automatisch die Baseline und die Packs, die zu seinem Stack-Profil passen.
Schweregrade und begründbare Ausnahmen
Nicht jede Regel wiegt gleich schwer. Eine Regel gilt entweder als blockierend — ein Verstoss hält den Lauf an — oder als meldend: er erscheint als Hinweis, ohne den Lauf zu stoppen.
Manchmal passt eine Regel nicht zu einer bestimmten Ausnahme im Projekt. Dafür gibt es begründbare Ausnahmen: du senkst die Schwere einer Regel oder schaltest sie für ein Projekt ab, mit einer Begründung und optional einem Ablaufdatum. Wie streng eine Regel dabei bleibt, bestimmt die Regel selbst — manche lassen sich nur lockern, manche gar nicht.
Eigene Regel-Pakete (Custom-Packs)
Über die mitgelieferten Packs hinaus kannst du eigene, organisationsweite Regel-Pakete anlegen — mehrere zusammengehörige Regeln, gebündelt und versioniert wie ein Plattform-Pack. Ein solches Paket entsteht als Entwurf, den nur du siehst; erst wenn du es veröffentlichst, lässt es sich an Projekte binden. Bis dahin wirkt es an keinem Lauf mit.
Update-Kanäle: fast und stable
Jede Organisation läuft auf einem von zwei Update-Kanälen. Fast — der Standard — übernimmt automatisch die jeweils neueste Fassung jedes Packs. Stable übernimmt eine neue Fassung erst, wenn wir sie ausdrücklich dafür freigegeben haben — der langsamere, bewusst nachgezogene Weg. Die Wahl triffst du unter Guardrails, im Kopf des Katalog-Abschnitts.
Signiert und öffentlich einsehbar
Der Plattform-Katalog ist mit einem Ed25519-Schlüssel signiert. Eine kuratierte Auswahl der Packs spiegeln wir öffentlich unter github.com/anvil-coder/guardrail-catalog, unter der Apache-2.0-Lizenz. Dort findest du zu jeder Datei einen sha256-Fingerabdruck und die Signatur über das Verzeichnis — nachprüfbar mit einem einzigen Kommando:
openssl pkeyutl -verify -pubin -inkey <(base64 -d catalog-signing.pub | openssl pkey -pubin -inform DER) \
-rawin -in public-manifest.json -sigfile <(base64 -d public-manifest.sig)
Wo du das im Cockpit findest
Unter Guardrails siehst du den Katalog als Karten — je Pack den Bindungsstatus für dein Projekt, ein Signiert-Abzeichen für jedes im öffentlichen Spiegel geführte Pack sowie einen Link auf die dort veröffentlichte Originaldatei. Deine eigenen Regel-Pakete stehen in einem eigenen Abschnitt darüber, mit Entwurf, Veröffentlichen und Zurückziehen.