Dokumentation / Qualität und Governance

Messung gegen N−1

Wie Yuli die Qualität misst, sie immer mit der vorherigen Version vergleicht und den Agenten zwingt, sich vor den Tests zu verbessern.

Yuli misst die Codequalität kontinuierlich und vergleicht sie immer mit der vorherigen Version, N−1. Die Regel ist einfach: nie zurück, immer nach vorn.

Alles wird automatisch gemessen: beim Öffnen des Projekts, nach jedem Build, Test oder jeder Verifizierung, bei jedem neuen Commit und im Editor, während du schreibst.

Das Panel Qualität

Es öffnet sich über die Anzeige in der Statusleiste (zum Beispiel A · σ 4,5 ▲) oder über das untere Panel.

Tab Wofür
Übersicht Gesamtnote, Sigma, Schulden, Clean Code, die letzte Messung des Agenten, nächste Verbesserungen und Vergleich mit N−1.
Praktiken Die 14 Clean-Code-Praktiken, ihr Nutzen und wo du zuerst ansetzen solltest.
Messung Die Messphase des Agenten: Urteil, Prüfungen, vorher → nachher und Runden.
Entscheidung Refaktorieren oder weiterentwickeln? Kriterien, Matrix und wirtschaftliches Kriterium.
Wartbarkeit Wartbarkeitsindex, kognitive Komplexität, Duplizierung, Kopplung und Schulden.
Prävention Befunde zu Sicherheit, Performance, Robustheit und Barrierefreiheit.
Architektur Architekturregeln des Projekts.
Testgesundheit Zustand der Testsuite.
Qualität Zyklomatische Komplexität, Pareto der Defekte, Coverage und Tests.
Größe Zeilen, Sprachen, Komponenten und Function Points.
Leistung Kosten pro Methode aus dem letzten Profil und Latenz des REST-Clients.
Statistik Wahrscheinlichkeiten, Verteilungen und Trends.
Six Sigma DMAIC, DPMO, Sigma-Niveau, FPY/RTY, Cpk und Regelkarte.
Verlauf Zeitreihen jeder Metrik und Änderungen gegenüber N−1.
Leitfaden Alles in einfachen Worten erklärt, mit Suche.

Jeder Bereich hat eine Schaltfläche „?“, die ihn ohne Fachjargon erklärt. „Keine Daten“ ist nie eine erfundene Null: Es sagt, was zum Messen fehlt.

Schaltflächen der Leiste

  • Aktualisieren: misst erneut.
  • Version erfassen: speichert die Messung als aktuelle Version. Die vorherige wird zu N−1.
  • Bericht öffnen: schreibt docs/quality/reporte-calidad.md und öffnet die Datei im Editor.

Was N−1 ist

Yuli speichert nur zwei Versionen: die aktuelle und die vorherige. Mit Git ist jeder neue Commit mit sauberem Arbeitsbaum eine Version. Eine neue Version entsteht auch, wenn du auf Version erfassen klickst und wenn der Agent misst.

Jede Metrik wird mit ▲ (verbessert), ▼ (verschlechtert) oder = (gleich) angezeigt. Eine einzige schlechtere Metrik genügt für das Urteil „Verschlechtert“.

Die Bewertung

Die Gesamtbewertung reicht von A bis E und kombiniert zehn Attribute aus ISO/IEC 25010: Funktionalität, Effizienz, Zuverlässigkeit, Robustheit, Sicherheit, Wartbarkeit, Verständlichkeit, Benutzbarkeit, Portabilität und Kompatibilität.

Note Punktzahl Bedeutung
A ≥ 80 Ausgezeichnet
B ≥ 65 Gut
C ≥ 50 Akzeptabel
D ≥ 35 Mangelhaft
E < 35 Kritisch

Eine kritische Schwachstelle begrenzt die Sicherheit auf 59 (D), eine hohe auf 79 (B). Ein ernstes Problem bleibt nie grün.

Die 14 Clean-Code-Praktiken

Jede Praktik ist eine Zahl mit Zielwert, messbar in jeder Sprache.

Praktik Wie gemessen wird Ziel
Aussagekräftig Aussagekräftige Namen und magische Zahlen pro KLOC ≥ 95 %
Kleine Funktionen Methoden mit höchstens 60 Zeilen ≥ 95 %
Duplizierung vermeiden Zeilen in wiederholten Blöcken ab 6 Zeilen ≤ 3 %
Lesbarer Code Methoden mit kognitiver Komplexität ≤ 15 ≥ 95 %
Fehlerbehandlung Robustheitsbefunde pro KLOC 0
Einfache Strukturen Zyklomatische Komplexität ≤ 10 und Verschachtelung ≤ 4 ≥ 95 %
Einheitlicher Stil Einrückung, Zeilenlänge und Namenskonvention ≥ 90
Sinnvolle Namen Variablen, die kein Rauschen sind (tmp, aux, data2) ≥ 98 %
Wenige Parameter Methoden mit höchstens 5 Parametern 100 %
Komposition statt Vererbung Vererbungstiefe ≤ 3 100 %
Kleine Klassen ≤ 300 Zeilen und ≤ 20 Methoden 100 %
Kein toter Code Auskommentierter, unerreichbarer oder ungenutzter Code 0
Schreib Tests Dateien mit Logik und eigenem Test 100 %
Kontinuierlich refaktorieren Rückschritte gegenüber N−1 0

Die Clean-Code-Note ist der Durchschnitt der Praktiken mit Daten. Ab 80 ist das Ziel erreicht.

Six Sigma und Fehlerdichte

Metrik Was sie ist
Fehlerdichte Defekte pro tausend Zeilen (KLOC), mit 95-%-Konfidenzintervall.
DPMO Defekte pro Million Möglichkeiten (jede Zeile ist eine Möglichkeit).
Sigma-Niveau (σ) Der DPMO auf der klassischen Skala: 6σ = 3,4 DPMO; 4σ ≈ 6.210. Grün ab 4,5σ.
Cpk Fähigkeit, die zyklomatische Komplexität ≤ 10 zu halten: ≥ 1,33 gilt als fähig.
FPY / RTY Builds, Tests und Verifizierungen, die beim ersten Versuch gelingen.

Ein Befund mit mittlerem oder höherem Schweregrad zählt als Defekt.

Die Messphase des Agenten

Sie ist die fünfte der 8 Phasen, zwischen Umsetzung und Tests. Sie misst nur den Code, den die Aufgabe berührt hat, gegen die Ausgangsversion.

Die drei Zeitpunkte

Phase Wann Was sie tut
baseline Bevor Code geändert wird Erfasst die Ausgangsversion (N−1) der Aufgabe.
measure Nach der Umsetzung Vergleicht den berührten Code mit N−1 und fällt ein Urteil.
after Wenn die Tests grün sind Vergleicht mit N−1 und schreibt den Bericht neu.

Wann sie besteht

Alle diese Prüfungen müssen erfüllt sein:

  1. Nichts hat sich gegenüber N−1 verschlechtert.
  2. Mindestens ein Defekt behoben (oder keiner vorhanden). Dass die Dichte gleich bleibt, reicht nicht.
  3. Der Clean Code hat sich verbessert in den Dateien, die unter dem Akzeptanzniveau lagen.
  4. Neuer Code ist von Anfang an sauber.
  5. Die Logik hat Tests.

Eine Datei gilt als akzeptiert, wenn sie 0 Defekte und einen Clean-Code-Wert von 90 oder mehr hat. Von einer akzeptierten Datei wird nur verlangt, dass sie sich nicht verschlechtert.

Die Urteile

Urteil Was passiert
Bestanden Die Mission geht automatisch zu Tests über.
Nachbessern Zurück zur Umsetzung, mit der genauen Liste dessen, was zu korrigieren ist, mit Datei und Zeile.
Rundenlimit Die Runden sind aufgebraucht: weiter zu Tests, und das Offene bleibt in der Mission.
Kein Code zu messen Die Aufgabe hat keinen Code berührt.

Die Messung lässt sich nicht überspringen. Versucht der Agent, mit ungemessenem Code zu Tests, Review oder Übergabe zu wechseln, lehnt Yuli das ab. Das gilt genauso für Claude Code, Kiro, Codex und Antigravity.

Verbessern ändert nie, was die Software tut: dieselben Anwendungsfälle, dieselben Ein- und Ausgaben.

Wo du das Ergebnis siehst

Nie im Chat. Der Agent gibt eine einzige Zeile mit dem Urteil und dem Vorher → Nachher aus. Die Details findest du im Tab Messung und in der Missionsleiste, mit der Schaltfläche In Qualität ansehen.

Einstellungen

Im Tab „Messung“ oder in .ai/quality.json:

Einstellung Standard Bereich
Die Messung ist vor den Tests Pflicht Ja —
Maximale Runden Umsetzung ↔ Messung 3 1 bis 10
Akzeptanzniveau (sauberer Code) 90 50 bis 100

Gibt es einen Qualitätsvertrag, haben dessen Werte für Akzeptanz und Runden Vorrang.

Im Editor

  • Über jeder Methode: CC · CoG · MI · líneas · cobertura · costo.
  • In der ersten Zeile: die Note der Datei, ihr Clean-Code-Wert und ihre Veränderung gegenüber N−1.
  • Hinweise: nichtssagende Namen, magische Zahlen oder toter Code, direkt an der betreffenden Zeile.

Der Bericht

Ein einziges Dokument, docs/quality/reporte-calidad.md, das bei jeder erfassten Version neu geschrieben wird. Es enthält den Abschnitt „Messung des Agenten“. Die Arbeitsdaten liegen in .ai/state/quality/ und werden nie ins Repository hochgeladen.

Ehrliche Grenzen

  • Komplexität und präventive Regeln werden mit Mustern auf dem Text berechnet. Sie können False Positives liefern. Java und JSP verwenden zusätzlich Syntaxbäume.
  • Die Schätzungen (Time-to-Market, Kosten) nutzen anerkannte Modelle mit editierbaren Annahmen. Sie dienen der Entscheidungsfindung, nicht als vertragliches Budget.