Documentación / Calidad y gobierno

Medición contra N−1

Cómo Yuli mide la calidad, la compara siempre con la versión anterior y obliga al agente a mejorar antes de probar.

Yuli mide la calidad del código de forma continua y la compara siempre con la versión anterior, N−1. La regla es simple: nunca para atrás, siempre para adelante.

Todo se mide solo: al abrir el proyecto, después de cada build, prueba o verificación, con cada commit nuevo y en el editor mientras escribes.

El panel Calidad

Se abre desde el indicador de la barra de estado (por ejemplo, A · σ 4,5 ▲) o desde el panel inferior.

Pestaña Para qué sirve
Resumen Nota global, sigma, deuda, clean code, la última medición del agente, próximas mejoras y comparativa con N−1.
Prácticas Las 14 prácticas de clean code, sus beneficios y dónde actuar primero.
Medición La fase de Medición del agente: veredicto, controles, antes → después y rondas.
Decisión ¿Refactorizar o evolucionar? Criterios, matriz y criterio económico.
Mantenibilidad Índice de mantenibilidad, complejidad cognitiva, duplicación, acoplamiento y deuda.
Prevención Hallazgos de seguridad, rendimiento, robustez y accesibilidad.
Arquitectura Reglas de arquitectura del proyecto.
Salud de pruebas Estado de la suite de pruebas.
Calidad Complejidad ciclomática, Pareto de defectos, cobertura y tests.
Tamaño Líneas, lenguajes, componentes y puntos de función.
Rendimiento Costo por método del último perfil y latencia del cliente REST.
Estadística Probabilidades, distribuciones y tendencias.
Six Sigma DMAIC, DPMO, nivel sigma, FPY/RTY, Cpk y gráfico de control.
Historial Series de cada métrica y cambios contra N−1.
Guía Todo explicado en palabras simples, con buscador.

Cada sección tiene un botón «?» que la explica sin jerga. «Sin datos» nunca es un cero inventado: dice qué falta para medir.

Botones de la barra

  • Actualizar: vuelve a medir.
  • Registrar versión: guarda la medición como versión actual. La anterior pasa a ser N−1.
  • Abrir reporte: escribe docs/quality/reporte-calidad.md y lo abre en el editor.

Qué es N−1

Yuli guarda solo dos versiones: la actual y la anterior. Con Git, cada commit nuevo con el árbol limpio es una versión. También hay versión nueva al pulsar Registrar versión y cuando el agente mide.

Cada métrica se muestra con ▲ (mejoró), ▼ (empeoró) o = (igual). Una sola métrica peor basta para el veredicto «Empeoró».

La calificación

La calificación global va de A a E y combina diez atributos de ISO/IEC 25010: funcionalidad, eficiencia, confiabilidad, robustez, seguridad, mantenibilidad, facilidad de entendimiento, usabilidad, portabilidad y compatibilidad.

Nota Puntaje Lectura
A ≥ 80 Excelente
B ≥ 65 Buena
C ≥ 50 Aceptable
D ≥ 35 Deficiente
E < 35 Crítica

Una vulnerabilidad crítica limita la seguridad a 59 (D) y una alta a 79 (B). Un problema serio nunca queda en verde.

Las 14 prácticas de clean code

Cada práctica es un número con su meta, medido en cualquier lenguaje.

Práctica Cómo se mide Meta
Descriptivo Nombres descriptivos y números mágicos por KLOC ≥ 95 %
Funciones pequeñas Métodos de 60 líneas o menos ≥ 95 %
Evita la duplicación Líneas en bloques repetidos de 6 o más ≤ 3 %
Código legible Métodos con complejidad cognitiva ≤ 15 ≥ 95 %
Manejo de errores Hallazgos de robustez por KLOC 0
Estructuras simples Ciclomática ≤ 10 y anidamiento ≤ 4 ≥ 95 %
Estilo consistente Sangría, largo de línea y convención de nombres ≥ 90
Nombres significativos Variables que no son ruido (tmp, aux, data2) ≥ 98 %
Pocos parámetros Métodos con 5 parámetros o menos 100 %
Composición sobre herencia Profundidad de herencia ≤ 3 100 %
Clases pequeñas ≤ 300 líneas y ≤ 20 métodos 100 %
Sin código muerto Código comentado, inalcanzable o sin uso 0
Escribe pruebas Archivos con lógica y prueba propia 100 %
Refactoriza continuamente Retrocesos frente a N−1 0

La nota de clean code es el promedio de las prácticas con datos. 80 o más está en meta.

Six Sigma y densidad de defectos

Métrica Qué es
Densidad de defectos Defectos por cada mil líneas (KLOC), con su intervalo de confianza del 95 %.
DPMO Defectos por millón de oportunidades (cada línea es una oportunidad).
Nivel sigma (σ) El DPMO en la escala clásica: 6σ = 3,4 DPMO; 4σ ≈ 6.210. Verde desde 4,5σ.
Cpk Capacidad de mantener la ciclomática ≤ 10: ≥ 1,33 capaz.
FPY / RTY Builds, pruebas y verificaciones que salen bien al primer intento.

Un hallazgo de severidad media o mayor cuenta como defecto.

La fase de Medición del agente

Es la quinta de las 8 fases, entre Implementación y Pruebas. Mide solo el código que la tarea tocó contra la versión de partida.

Los tres momentos

Fase Cuándo Qué hace
baseline Antes de cambiar código Registra la versión de partida (N−1) de la tarea.
measure Después de implementar Compara el código tocado contra N−1 y da un veredicto.
after Con las pruebas en verde Compara con N−1 y reescribe el reporte.

Cuándo aprueba

Todos estos controles deben cumplirse:

  1. Nada empeoró frente a N−1.
  2. Al menos un defecto corregido (o ninguno). Que la densidad siga igual no alcanza.
  3. El clean code mejoró en los archivos que estaban por debajo del nivel de aceptación.
  4. Código nuevo limpio desde el inicio.
  5. La lógica tiene pruebas.

Un archivo está aceptado si tiene 0 defectos y un clean code de 90 o más. A un archivo aceptado solo se le exige no empeorar.

Los veredictos

Veredicto Qué pasa
Aprobada La misión pasa sola a Pruebas.
Iterar Vuelve a Implementación con la lista exacta de qué corregir, con archivo y línea.
Límite de rondas Se agotaron las rondas: sigue a Pruebas y lo pendiente queda en la misión.
Sin código que medir La tarea no tocó código.

La medición no se puede saltar. Si el agente intenta pasar a Pruebas, Revisión o Entrega con código sin medir, Yuli lo rechaza. Vale igual para Claude Code, Kiro, Codex y Antigravity.

Mejorar nunca cambia lo que el software hace: mismos casos de uso, mismas entradas y salidas.

Dónde ves el resultado

Nunca en el chat. El agente da una sola línea con el veredicto y el antes → después. El detalle está en la pestaña Medición y en la barra de la misión, con el botón Ver en Calidad.

Ajustes

En la pestaña Medición o en .ai/quality.json:

Ajuste Por defecto Rango
La medición es obligatoria antes de las pruebas Sí —
Rondas máximas de implementación ↔ medición 3 1 a 10
Nivel de aceptación (código limpio) 90 50 a 100

Si existe un contrato de calidad, sus valores de aceptación y rondas tienen prioridad.

En el editor

  • Encima de cada método: CC · CoG · MI · líneas · cobertura · costo.
  • En la primera línea: la nota del archivo, su clean code y su cambio frente a N−1.
  • Pistas: nombres sin significado, números mágicos o código muerto, en la línea exacta.

El reporte

Un único documento, docs/quality/reporte-calidad.md, reescrito en cada versión registrada. Incluye la sección «Medición del agente». Los datos de trabajo viven en .ai/state/quality/ y nunca se suben al repositorio.

Límites honestos

  • La complejidad y las reglas preventivas se calculan con patrones sobre el texto. Pueden tener falsos positivos. Java y JSP usan además árboles sintácticos.
  • Las estimaciones (Time-to-Market, costos) usan modelos reconocidos con supuestos editables. Sirven para decidir, no como presupuesto contractual.