Documentação / Qualidade e governança

Medição contra N−1

Como o Yuli mede a qualidade, sempre a compara com a versão anterior e obriga o agente a melhorar antes de testar.

O Yuli mede a qualidade do código de forma contínua e sempre a compara com a versão anterior, N−1. A regra é simples: nunca para trás, sempre para frente.

Tudo é medido automaticamente: ao abrir o projeto, depois de cada build, teste ou verificação, a cada novo commit e no editor enquanto você escreve.

O painel Qualidade

Ele é aberto pelo indicador da barra de status (por exemplo, A · σ 4,5 ▲) ou pelo painel inferior.

Aba Para que serve
Resumo Nota global, sigma, dívida, clean code, a última medição do agente, próximas melhorias e comparação com N−1.
Práticas As 14 práticas de clean code, seus benefícios e onde agir primeiro.
Medição A fase de Medição do agente: veredicto, controles, antes → depois e rodadas.
Decisão Refatorar ou evoluir? Critérios, matriz e critério econômico.
Manutenibilidade Índice de manutenibilidade, complexidade cognitiva, duplicação, acoplamento e dívida.
Prevenção Achados de segurança, desempenho, robustez e acessibilidade.
Arquitetura Regras de arquitetura do projeto.
Saúde dos testes Estado da suíte de testes.
Qualidade Complexidade ciclomática, Pareto de defeitos, cobertura e testes.
Tamanho Linhas, linguagens, componentes e pontos de função.
Desempenho Custo por método do último perfil e latência do cliente REST.
Estatística Probabilidades, distribuições e tendências.
Six Sigma DMAIC, DPMO, nível sigma, FPY/RTY, Cpk e gráfico de controle.
Histórico Séries de cada métrica e alterações contra N−1.
Guia Tudo explicado em palavras simples, com busca.

Cada seção tem um botão “?” que a explica sem jargão. “Sem dados” nunca é um zero inventado: indica o que falta para medir.

Botões da barra

  • Atualizar: mede novamente.
  • Registrar versão: salva a medição como versão atual. A anterior passa a ser N−1.
  • Abrir relatório: escreve docs/quality/reporte-calidad.md e o abre no editor.

O que é N−1

O Yuli guarda apenas duas versões: a atual e a anterior. Com Git, cada novo commit com a árvore limpa é uma versão. Também há uma versão nova ao clicar em Registrar versão e quando o agente mede.

Cada métrica é exibida com ▲ (melhorou), ▼ (piorou) ou = (igual). Uma única métrica pior basta para o veredicto “Piorou”.

A classificação

A classificação global vai de A a E e combina dez atributos da ISO/IEC 25010: funcionalidade, eficiência, confiabilidade, robustez, segurança, manutenibilidade, facilidade de entendimento, usabilidade, portabilidade e compatibilidade.

Nota Pontuação Leitura
A ≥ 80 Excelente
B ≥ 65 Boa
C ≥ 50 Aceitável
D ≥ 35 Deficiente
E < 35 Crítica

Uma vulnerabilidade crítica limita a segurança a 59 (D) e uma alta, a 79 (B). Um problema sério nunca fica verde.

As 14 práticas de clean code

Cada prática é um número com sua meta, medido em qualquer linguagem.

Prática Como é medida Meta
Descritivo Nomes descritivos e números mágicos por KLOC ≥ 95 %
Funções pequenas Métodos de 60 linhas ou menos ≥ 95 %
Evite a duplicação Linhas em blocos repetidos de 6 ou mais ≤ 3 %
Código legível Métodos com complexidade cognitiva ≤ 15 ≥ 95 %
Tratamento de erros Achados de robustez por KLOC 0
Estruturas simples Ciclomática ≤ 10 e aninhamento ≤ 4 ≥ 95 %
Estilo consistente Indentação, comprimento de linha e convenção de nomes ≥ 90
Nomes significativos Variáveis que não são ruído (tmp, aux, data2) ≥ 98 %
Poucos parâmetros Métodos com 5 parâmetros ou menos 100 %
Composição em vez de herança Profundidade de herança ≤ 3 100 %
Classes pequenas ≤ 300 linhas e ≤ 20 métodos 100 %
Sem código morto Código comentado, inalcançável ou sem uso 0
Escreva testes Arquivos com lógica e teste próprio 100 %
Refatore continuamente Retrocessos em relação a N−1 0

A nota de clean code é a média das práticas com dados. 80 ou mais está na meta.

Six Sigma e densidade de defeitos

Métrica O que é
Densidade de defeitos Defeitos a cada mil linhas (KLOC), com seu intervalo de confiança de 95 %.
DPMO Defeitos por milhão de oportunidades (cada linha é uma oportunidade).
Nível sigma (σ) O DPMO na escala clássica: 6σ = 3,4 DPMO; 4σ ≈ 6.210. Verde a partir de 4,5σ.
Cpk Capacidade de manter a ciclomática ≤ 10: ≥ 1,33 é capaz.
FPY / RTY Builds, testes e verificações que dão certo na primeira tentativa.

Um achado de severidade média ou maior conta como defeito.

A fase de Medição do agente

É a quinta das 8 fases, entre Implementação e Testes. Mede apenas o código que a tarefa tocou contra a versão de partida.

Os três momentos

Fase Quando O que faz
baseline Antes de alterar código Registra a versão de partida (N−1) da tarefa.
measure Depois de implementar Compara o código tocado contra N−1 e dá um veredicto.
after Com os testes no verde Compara com N−1 e reescreve o relatório.

Quando aprova

Todos estes controles devem ser cumpridos:

  1. Nada piorou em relação a N−1.
  2. Pelo menos um defeito corrigido (ou nenhum). A densidade continuar igual não basta.
  3. O clean code melhorou nos arquivos que estavam abaixo do nível de aceitação.
  4. Código novo limpo desde o início.
  5. A lógica tem testes.

Um arquivo está aceito se tiver 0 defeitos e um clean code de 90 ou mais. De um arquivo aceito, só se exige que não piore.

Os veredictos

Veredicto O que acontece
Aprovado A missão passa sozinha para Testes.
Iterar Volta para Implementação com a lista exata do que corrigir, com arquivo e linha.
Limite de rodadas As rodadas se esgotaram: segue para Testes e o que ficou pendente permanece na missão.
Sem código para medir A tarefa não tocou código.

A medição não pode ser pulada. Se o agente tentar passar para Testes, Revisão ou Entrega com código não medido, o Yuli rejeita. Vale igualmente para Claude Code, Kiro, Codex e Antigravity.

Melhorar nunca muda o que o software faz: mesmos casos de uso, mesmas entradas e saídas.

Onde você vê o resultado

Nunca no chat. O agente dá uma única linha com o veredicto e o antes → depois. O detalhe fica na aba Medição e na barra da missão, com o botão Ver em Qualidade.

Configurações

Na aba Medição ou em .ai/quality.json:

Configuração Padrão Intervalo
A medição é obrigatória antes dos testes Sim —
Rodadas máximas de implementação ↔ medição 3 1 a 10
Nível de aceitação (código limpo) 90 50 a 100

Se existir um contrato de qualidade, seus valores de aceitação e de rodadas têm prioridade.

No editor

  • Acima de cada método: CC · CoG · MI · líneas · cobertura · costo.
  • Na primeira linha: a nota do arquivo, seu clean code e sua variação em relação a N−1.
  • Dicas: nomes sem significado, números mágicos ou código morto, na linha exata.

O relatório

Um único documento, docs/quality/reporte-calidad.md, reescrito a cada versão registrada. Inclui a seção “Medição do agente”. Os dados de trabalho ficam em .ai/state/quality/ e nunca são enviados ao repositório.

Limites honestos

  • A complexidade e as regras preventivas são calculadas com padrões sobre o texto. Podem ter falsos positivos. Java e JSP usam também árvores sintáticas.
  • As estimativas (Time-to-Market, custos) usam modelos reconhecidos com premissas editáveis. Servem para decidir, não como orçamento contratual.