Dokumentation / Qualität und Governance

Qualitätsvertrag

Die Qualitätsregeln liegen in einer versionierten Datei im Repository, nicht im Prompt – und gelten für Menschen und Agenten gleichermaßen.

Der Qualitätsvertrag ist die Datei .ai/contract.json deines Projekts. Er legt fest, wie viel Strenge das Team verlangt: Messschwellen, Testabdeckung, Komplexität, Umfang von Änderungen, geschützte Pfade und Ausnahmen.

Durchgesetzt wird er vom Gate der Engine, von den Git-Hooks, der CI und den Agenten. Das Ergebnis hängt nicht davon ab, wer den Code schreibt: ein Mensch, Yuli, Claude Code, Codex, Kiro oder Antigravity.

Existiert die Datei nicht oder ist sie ungültig, nutzt Yuli die Standardwerte (Kritikalität Geschäftlich). Jedes Feld ist optional, also funktioniert auch ein unvollständiger Vertrag.

Wo du ihn bearbeitest

Öffne das Governance-Center (rechte Leiste → Weitere Werkzeuge oder in der Befehlspalette mit Governance-Center öffnen) und wechsle zum Tab Vertrag.

Beim Speichern mit Speichern und signieren erfasst Yuli die Änderung mit deinem git config user.name. Alle Änderungen siehst du im Vertragsverlauf.

Kritikalität

Die Kritikalität wählt ein vollständiges Profil an Schwellenwerten. Es gibt vier Stufen:

Wert in der Datei Bezeichnung in Yuli Wann verwenden
low Niedrig Prototypen, interne Tools, Experimente.
business Geschäftlich Geschäftsanwendungen. Das ist der Standardwert.
regulated Reguliert Systeme, die Audits oder Regulierung unterliegen.
safety Sicherheitskritisch Software, bei der ein Fehler schwere Folgen hat.

Profile

Schwellenwert Niedrig Geschäftlich Reguliert Sicherheitskritisch
Akzeptanzpunktzahl 80 90 92 95
Messrunden 2 3 4 5
Mindestabdeckung 50 % 70 % 80 % 90 %
Max. kognitive Komplexität 20 15 15 10
Max. zyklomatische Komplexität 15 10 10 8
Mindest-Mutationsscore 0 % 0 % 60 % 75 %
Dateien pro Änderung 60 40 25 15
Zeilen pro Änderung 2000 1000 600 400
Unabhängiges Review Nein Nein Ja Ja
Test-Manipulation blockieren Nein Ja Ja Ja
Strikte Durchsetzung Nein Nein Ja Ja

Einzelne Schwellenwerte kannst du in gates überschreiben. Nur dieses Feld ändert sich; der Rest kommt weiterhin aus dem Profil. Test-Manipulation blockieren und Strikte Durchsetzung hängen ausschließlich von der Kritikalität ab und lassen sich nicht überschreiben.

Akzeptanzpunktzahl und Runden aus dem Vertrag ersetzen die lokalen Einstellungen der Messphase.

Aufbau der Datei

{
  "schemaVersion": 1,
  "criticality": "business",
  "gates": { "minCoverage": 75, "maxCyclomatic": null },
  "changeLimits": { "maxFiles": 40, "maxLines": 1000 },
  "protectedPaths": ["db/migrations/**"],
  "waivers": []
}
Feld Was es festlegt
criticality low, business, regulated oder safety.
gates acceptanceScore, maxMeasureRounds, minCoverage, maxCognitive, maxCyclomatic, requireIndependentReview, minMutationScore. null übernimmt den Wert des Profils.
changeLimits maxFiles und maxLines pro Änderung.
protectedPaths Zusätzliche Globs, die zu den standardmäßig geschützten hinzukommen.
waivers Ausnahmen mit Ablaufdatum.
architecture Schichten (layers mit name, paths, mayDependOn) und forbidCycles.
slos Service-Ziele: latencyP95Ms, availability oder errorRate.
licensePolicy Erlaubte (allow) und verbotene (deny) Lizenzen, per SPDX oder nach Familie, etwa strong-copyleft.
reviewer Unabhängiger Reviewer: requireOtherFamily, provider, model.
dataClassification Datenmuster mit ihrer Stufe: public, internal, confidential oder restricted.
finops Monatliches Budget pro Service und dessen Verantwortliche.

Änderungslimits

Der Umfang einer Änderung wird mit git diff --numstat gemessen. Lock-Dateien (package-lock.json, yarn.lock, Cargo.lock, go.sum und ähnliche) zählen als Dateien, ihre Zeilen aber nicht.

Eine Überschreitung blockiert bei strikter Durchsetzung (Reguliert und Sicherheitskritisch). In den übrigen Profilen ist sie eine Warnung.

Geschützte Pfade

Ein Agent kann diese Dateien nicht bearbeiten, selbst wenn er dazu aufgefordert wird:

  • .ai/contract.json, .ai/quality.json und .ai/state/**
  • .claude/settings.json und .claude/settings.local.json
  • .githooks/**
  • .github/workflows/**, .gitlab-ci.yml und Jenkinsfile
  • CODEOWNERS und .github/CODEOWNERS

Der Vergleich ignoriert Groß- und Kleinschreibung. Eigene Pfade fügst du in protectedPaths hinzu. Eine aus Yuli gespeicherte Vertragsänderung landet im Audit und gilt als freigegeben.

Ausnahmen (Waivers)

Eine Ausnahme erlaubt es, eine Regel vorübergehend und begründet zu umgehen.

Feld Inhalt
id Kennung der Ausnahme.
rule Ausgenommene Regel: secrets, protectedPaths, testIntegrity, eine bestimmte Manipulationsart oder *.
path Glob, für den sie gilt. Leer bedeutet: jeder Pfad.
reason Begründung.
approvedBy Wer sie freigegeben hat.
expires Ablaufdatum, AAAA-MM-DD.
ticket Optionale Referenz.

Eine Ausnahme gilt bis einschließlich des Tages in expires. Ein fehlendes oder falsch geschriebenes Datum zählt als abgelaufen. Nach Ablauf gilt die Regel wieder, und das Gate weist darauf hin.

In der Oberfläche zeigt jede Ausnahme ihren Status: Aktiv, Läuft bald ab, Abgelaufen oder Ungültiges Datum.

testIntegrity nimmt alle Erkennungen von Test-Manipulationen auf einmal aus. Verwende sie nur mit einem eng gefassten Pfad und einem nahen Datum.

Audit

Jedes Speichern fügt .ai/state/contract-audit.jsonl eine Zeile mit Datum, Autor, SHA-256-Hash und einer Zusammenfassung hinzu (zum Beispiel „criticality business→regulated; waivers +1“).

Der Autor ist immer ein Mensch: der angegebene Name oder dein git config user.name. „Yuli“ und „Yuli Code“ werden als Autoren abgelehnt.

Nächster Schritt