Documentație / Calitate și guvernanță

Măsurarea față de N−1

Cum măsoară Yuli calitatea, o compară mereu cu versiunea anterioară și obligă agentul să îmbunătățească înainte de testare.

Yuli măsoară continuu calitatea codului și o compară mereu cu versiunea anterioară, N−1. Regula este simplă: niciodată înapoi, mereu înainte.

Totul se măsoară automat: la deschiderea proiectului, după fiecare build, test sau verificare, la fiecare commit nou și în editor, în timp ce scrii.

Panoul Calitate

Se deschide din indicatorul din bara de stare (de exemplu, A · σ 4,5 ▲) sau din panoul inferior.

Filă La ce servește
Rezumat Nota globală, sigma, datoria tehnică, clean code, ultima măsurare a agentului, următoarele îmbunătățiri și comparația cu N−1.
Practici Cele 14 practici de clean code, beneficiile lor și unde să acționezi mai întâi.
Măsurare Faza de Măsurare a agentului: verdict, controale, înainte → după și runde.
Decizie Refactorizare sau evoluție? Criterii, matrice și criteriu economic.
Mentenabilitate Indicele de mentenabilitate, complexitatea cognitivă, duplicarea, cuplarea și datoria tehnică.
Prevenție Constatări de securitate, performanță, robustețe și accesibilitate.
Arhitectură Regulile de arhitectură ale proiectului.
Starea testelor Starea suitei de teste.
Calitate Complexitatea ciclomatică, Pareto al defectelor, acoperirea și testele.
Dimensiune Linii, limbaje, componente și puncte funcționale.
Performanță Costul pe metodă din ultimul profil și latența clientului REST.
Statistică Probabilități, distribuții și tendințe.
Six Sigma DMAIC, DPMO, nivel sigma, FPY/RTY, Cpk și diagramă de control.
Istoric Seriile fiecărei metrici și modificările față de N−1.
Ghid Totul explicat pe înțelesul tuturor, cu motor de căutare.

Fiecare secțiune are un buton „?” care o explică fără jargon. „Fără date” nu este niciodată un zero inventat: spune ce lipsește pentru a putea măsura.

Butoanele barei

  • Actualizează: măsoară din nou.
  • Înregistrează versiunea: salvează măsurarea ca versiune curentă. Cea anterioară devine N−1.
  • Deschide raportul: scrie docs/quality/reporte-calidad.md și îl deschide în editor.

Ce este N−1

Yuli păstrează doar două versiuni: cea curentă și cea anterioară. Cu Git, fiecare commit nou cu arborele curat este o versiune. O versiune nouă apare și când apeși Înregistrează versiunea și când agentul măsoară.

Fiecare metrică este afișată cu ▲ (s-a îmbunătățit), ▼ (s-a înrăutățit) sau = (la fel). O singură metrică mai slabă este suficientă pentru verdictul „S-a înrăutățit”.

Calificativul

Calificativul global merge de la A la E și combină zece atribute ISO/IEC 25010: funcționalitate, eficiență, fiabilitate, robustețe, securitate, mentenabilitate, ușurință de înțelegere, utilizabilitate, portabilitate și compatibilitate.

Notă Scor Interpretare
A ≥ 80 Excelent
B ≥ 65 Bun
C ≥ 50 Acceptabil
D ≥ 35 Deficitar
E < 35 Critic

O vulnerabilitate critică limitează securitatea la 59 (D), iar una ridicată la 79 (B). O problemă serioasă nu rămâne niciodată pe verde.

Cele 14 practici de clean code

Fiecare practică este un număr cu ținta lui, măsurat în orice limbaj.

Practică Cum se măsoară Țintă
Descriptiv Nume descriptive și numere magice la KLOC ≥ 95 %
Funcții mici Metode de 60 de linii sau mai puțin ≥ 95 %
Evită duplicarea Linii în blocuri repetate de 6 sau mai multe ≤ 3 %
Cod lizibil Metode cu complexitate cognitivă ≤ 15 ≥ 95 %
Tratarea erorilor Constatări de robustețe la KLOC 0
Structuri simple Ciclomatică ≤ 10 și imbricare ≤ 4 ≥ 95 %
Stil consecvent Indentare, lungimea liniei și convenția de denumire ≥ 90
Nume semnificative Variabile care nu sunt zgomot (tmp, aux, data2) ≥ 98 %
Puțini parametri Metode cu 5 parametri sau mai puțin 100 %
Compoziție în loc de moștenire Adâncimea moștenirii ≤ 3 100 %
Clase mici ≤ 300 de linii și ≤ 20 de metode 100 %
Fără cod mort Cod comentat, inaccesibil sau nefolosit 0
Scrie teste Fișiere cu logică și test propriu 100 %
Refactorizează continuu Regresii față de N−1 0

Nota de clean code este media practicilor care au date. 80 sau mai mult înseamnă că ținta este atinsă.

Six Sigma și densitatea defectelor

Metrică Ce este
Densitatea defectelor Defecte la mia de linii (KLOC), cu intervalul de încredere de 95 %.
DPMO Defecte la milionul de oportunități (fiecare linie este o oportunitate).
Nivel sigma (σ) DPMO pe scara clasică: 6σ = 3,4 DPMO; 4σ ≈ 6.210. Verde de la 4,5σ.
Cpk Capacitatea de a menține ciclomatica ≤ 10: ≥ 1,33 înseamnă capabil.
FPY / RTY Build-uri, teste și verificări care reușesc din prima încercare.

O constatare de severitate medie sau mai mare contează ca defect.

Faza de Măsurare a agentului

Este a cincea dintre cele 8 faze, între Implementare și Testare. Măsoară doar codul atins de sarcină față de versiunea de pornire.

Cele trei momente

Fază Când Ce face
baseline Înainte de modificarea codului Înregistrează versiunea de pornire (N−1) a sarcinii.
measure După implementare Compară codul atins cu N−1 și dă un verdict.
after Cu testele pe verde Compară cu N−1 și rescrie raportul.

Când aprobă

Toate aceste controale trebuie îndeplinite:

  1. Nimic nu s-a înrăutățit față de N−1.
  2. Cel puțin un defect corectat (sau niciunul). Faptul că densitatea rămâne la fel nu este suficient.
  3. Clean code-ul s-a îmbunătățit în fișierele care erau sub nivelul de acceptare.
  4. Codul nou este curat de la început.
  5. Logica are teste.

Un fișier este acceptat dacă are 0 defecte și un clean code de 90 sau mai mult. Unui fișier acceptat i se cere doar să nu se înrăutățească.

Verdictele

Verdict Ce se întâmplă
Trecut Misiunea trece singură la Testare.
Iterați Revine la Implementare cu lista exactă a ce trebuie corectat, cu fișier și linie.
Limita de runde Rundele s-au epuizat: continuă la Testare, iar ce a rămas nerezolvat este notat în misiune.
Nu există cod de măsurat Sarcina nu a atins cod.

Măsurarea nu poate fi sărită. Dacă agentul încearcă să treacă la Testare, Revizuire sau Livrare cu cod nemăsurat, Yuli refuză. Se aplică la fel pentru Claude Code, Kiro, Codex și Antigravity.

Îmbunătățirea nu schimbă niciodată ce face software-ul: aceleași cazuri de utilizare, aceleași intrări și ieșiri.

Unde vezi rezultatul

Niciodată în chat. Agentul dă o singură linie cu verdictul și cu înainte → după. Detaliile se află în fila Măsurare și în bara misiunii, cu butonul Vedeți în Calitate.

Setări

În fila Măsurare sau în .ai/quality.json:

Setare Implicit Interval
Măsurarea este obligatorie înainte de teste Da —
Număr maxim de runde implementare ↔ măsurare 3 1 – 10
Nivelul de acceptare (cod curat) 90 50 – 100

Dacă există un contract de calitate, valorile lui de acceptare și de runde au prioritate.

În editor

  • Deasupra fiecărei metode: CC · CoG · MI · líneas · cobertura · costo.
  • Pe prima linie: nota fișierului, clean code-ul lui și modificarea față de N−1.
  • Indicii: nume fără semnificație, numere magice sau cod mort, pe linia exactă.

Raportul

Un singur document, docs/quality/reporte-calidad.md, rescris la fiecare versiune înregistrată. Include secțiunea „Măsurarea agentului”. Datele de lucru se află în .ai/state/quality/ și nu sunt urcate niciodată în depozit.

Limite oneste

  • Complexitatea și regulile preventive se calculează cu tipare aplicate pe text. Pot avea fals pozitive. Java și JSP folosesc în plus arbori sintactici.
  • Estimările (Time-to-Market, costuri) folosesc modele recunoscute, cu ipoteze editabile. Servesc la luarea deciziilor, nu ca buget contractual.