Anexo H - Heurísticas de qualidade de código e de usabilidade

Estado: APROVADO E EM PRODUÇÃO. Não fica nenhuma decisão aberta: a forma (D-043 e D-044), os interruptores (D-045 e D-046), o painel (D-047) e as severidades iniciais com o peso da acessibilidade (D-048, seção 10) estão decididas. O documento está publicado nos oito idiomas do método e os seus dois prompts fazem parte da API de prompts: a partir dali, build/prompts.mjs exige o texto ingles idêntico byte a byte nos oito ou a construção falha. Data: 2026-10-22.

Registro das decisões deste anexo: docs/DECISIONES.md, D-043 a D-048. O painel de cumprimento (seção 12) foi decidido com duas cifras em D-047. O trabalho de implementação vive em PND-002; a tradução e a indexação, em PND-003.

1. O que falta hoje, e por que

O passo 9 já mede o código, e o faz com uma comporta que não deixa passar nada: um único formatador, limites de tamanho (trezentas linhas por arquivo, quarenta por função), complexidade por função, código duplicado, código morto, dependências declaradas e usadas, cobertura com catraca e testes de mutação onde há usuários reais. O número fica escrito em docs/CODE_QUALITY.md. Isso está resolvido.

O que não está resolvido é a outra metade do produto. Revisei o corpus dos passos: não há uma única menção a usabilidade, a perfis/pessoas nem a agrupamento funcional. A interface se sustenta hoje em duas coisas: a captura que o dono olha por dez segundos e os casos de teste manuais. As duas são boas e as duas são humanas, caras e esquecidas. Um sistema pode passar na comporta de qualidade com honras e ser inutilizável: tudo verde, e a pessoa não acha onde cobrar.

E há um problema de segunda camada que é técnico mas aparece na interface: quando o mesmo produto é usado por vários perfis (administração, operação, consulta, cliente), as funcionalidades são habilitadas em três lugares diferentes - o banco, o menu e o guarda de rota - que se escrevem em momentos diferentes e se desincronizam sozinhos. O sintoma é sempre o mesmo: alguém vê um botão que não é seu, ou pior, alguém que sim tem a permissão não acha a tela.

As duas heurísticas que seguem atacam essas duas coisas com a mesma forma: um catálogo curto de afirmações verificáveis, alguns instrumentos que as medem sozinhos, e um caminho de exceção declarada para quando o projeto precisa sair da linha.

2. O modelo: três capas, uma única forma de regra

A tentação é fazer uma lista de regras e amarrá-la a stack do primeiro projeto. Isso envelhece mal: a regra de React não aplica em Angular, a de Angular não aplica em servidor com templates, e em dois anos metade da lista está morta. A proposta separa três capas.

Capa 1 - Núcleo agnóstico (não negociável). Afirmações sobre resultados, não sobre ferramentas. "Há um único formatador e ninguém discute com ele" aplica igual em TypeScript, em PHP ou em Go. O núcleo se enumera com identificadores estáveis e não muda de projeto em projeto.

Capa 2 - Adaptador por stack (configurável). Para cada regra do núcleo, cada família de frontend declara com o que se mede e com qual limiar. Um projeto React com Vite, um Next, um Angular, um servidor com templates, um mobile e um de linha de comando são seis adaptadores diferentes do mesmo núcleo. Tudo o que o usuário pediu como "configurável por frontend" vive aqui.

Capa 3 - Decisões do projeto (declaradas). Os limiares concretos e as exceções. Não se inventam: se perguntam ao dono e ficam escritos, igual ao dimensionamento do passo de arquitetura. Se um limiar não está declarado, aplica o do adaptador e fica registrado como tal.

Toda regra se escreve sempre com a mesma ficha de seis campos:

A exceção se declara, nunca se omite. Uma regra se apaga com ficha de quatro campos: identificador, motivo em uma linha, quem a autoriza (o dono, não o agente) e data de revisão. Uma regra apagada sem ficha é um fracasso da comporta, não uma decisão. É o mesmo critério que o método já usa para recusar um limite subido "para passar".

3. Os quatro instrumentos

Nenhuma heurística vale nada se a sua verificação é uma opinião. São quatro, e cada regra declara a qual pertence.

1. Comporta automática. Corre em cada push e no fechamento do bloco. Devolve verde ou vermelho. É barata, é repetível e não discute. Mede tudo o que pode ser contado.
2. Consulta a matriz. A matriz funcionalidade-por-perfil (ver B2) é um artefato declarativo; o menu, o roteamento e as permissões se derivam dela. Verificar a matriz e verificar a interface. É a peça que converte parte da usabilidade em algo que uma máquina pode verificar.
3. Teste ponta a ponta por perfil. Para cada perfil declarado, um script que entra como esse perfil e compara o conjunto de funcionalidades alcançáveis contra a linha da matriz: nem menos nem mais. É o teste que pega as duas desincronizações típicas (o botão que sobra e a tela que falta).
4. Caso manual. O que nenhuma máquina julga: se o agrupamento se entende, se a tarefa se completa sem ajuda, se o texto está no idioma do usuário. Se corre com pessoas e se registra, como o passo 10 já manda.

4. Parte A - Qualidade de código

O núcleo estende o passo 9: não o substitui e não o contradiz, da nome, severidade e adaptador a cada coisa que já se mede, e agrega o que hoje falta, que é a interface vista como código.

As regras CQ-12 a CQ-18 são as que fazem com que "qualidade de código" signifique algo no front. Sem elas, o projeto pode ter noventa por cento de mutação e uma tela que calcula o total com a sua própria aritmética dentro de um componente: o pior dos dois mundos, porque o cálculo duplicado passa todos os testes de backend.

Severidades iniciais (D-048). Desde o primeiro dia bloqueiam as catorze regras que têm verificador e que não dependem de um limiar que valha discutir: CQ-01 a CQ-06, CQ-08 e CQ-11 a CQ-17. CQ-09 bloqueia onde há usuários reais, que é onde se mede. Avisam três, e só três: CQ-07 (tipos), CQ-10 (dependências) e CQ-18 (acessibilidade), porque são as que precisam que o projeto calibre primeiro. O formatador, o linter, o tamanho e a complexidade não se afrouxam: o passo 9 já os bloqueia hoje, e esta extensão o estende, não o substitui; a dívida herdada se resolve com exceção declarada ou com a linha de base da catraca, nunca baixando a severidade. E CQ-12 e CQ-14 são as duas únicas regras desta tabela que bloqueiam com vermelho humano e não de máquina: se verificam no fechamento do pendente e com o caso manual na frente, igual a UX-22 e UX-27, não em cada commit. Se o projeto não consegue sustentar esse fechamento, a regra baixa a AVISA por decisão registrada, não por descuido.

Adaptador por família de frontend. Exemplo de como se instância a capa 2 (os nomes são ilustrativos; o projeto escolhe e escreve os seus):

O que muda entre colunas é a ferramenta e o limiar. O que não muda é o enunciado. Isso é o que torna a heurística agnóstica sem virar decorativa.

5. Parte B - Usabilidade

Cinco famílias. A primeira e a segunda são as que o dono pediu explicitamente; as outras três existem porque sem elas o agrupamento e os perfis se degradam igual, mais devagar.

B1 - Agrupamento por convergência funcional

A regra mãe: uma funcionalidade se agrupa por aquilo que a pessoa veio fazer, não pelo módulo do qual saiu. O código se organiza por entidades ("Fatura", "Cliente", "Pagamento"); as pessoas não. Ninguém entra no sistema para "gerenciar entidades": entra para cobrar, para despachar, para fechar o mês. Se o menu mostra as entidades, a pessoa faz a tradução. O menu é o trabalho.

B2 - Perfis e funcionalidades habilitadas por perfil

Aqui está a peça que mais paga, e o motivo é de engenharia, não de desenho: a habilitação se declara uma vez, em uma matriz, e tudo o resto se deriva dela. Hoje o erro clássico é escrever a permissão três vezes (no menu, no guarda de rota e no filtro de dados) e ter as três desincronizadas. Com a matriz como produtor único, o menu, o roteamento, as permissões do servidor e os scripts de teste são consumidores, e a simetria produtor/consumidor que o método já exige se torna verificável sozinha.

A matriz tem quatro colunas e uma linha por funcionalidade: funcionalidade, casa (o grupo de B1), perfis que a tem, rota de entrada. Nada mais.

B3 - Estados, e o que a pessoa vê quando algo não está

A maioria das reclamações de "não funciona" são telas que não souberam dizer "não há nada", "está carregando" ou "falhou". Quatro estados, sempre, em toda lista e em toda tela de detalhe.

B4 - Ações e erros

B5 - Linguagem e acessibilidade

6. Onde se engancha, e que artefatos produz

O anexo não inventa passos novos: pendura-se nos que existem. Isso evita duplicar comportas e evita o destino habitual das listas de usabilidade, que é serem lidas uma vez.

Onde vai (D-043). É transversal aos quatro trechos, com o peso principal no Loop de Construção (passos 5 a 12), que é onde se decide e se constrói. Não é um passo próprio: um passo numerado obrigaria a renumerar a escada, alteraria a contagem de passos e sujeitaria o anexo a tradução obrigatória dos contratos aos oito idiomas antes de que a construção pudesse passar em verde, sem agregar nenhuma comporta que o loop não tenha já.

Como se engancha (D-044). Uma fonte canônica, cinco âncoras e duas entradas prévias. O texto das regras vive só aqui e os prompts o citam; nunca o copiam. Repetir as quarenta e cinco regras dentro dos oito prompts do loop as dilui (competem com o trabalho de cada passo e o agente as obedece diferente em cada vez), as desalinha (duas cópias do mesmo texto se desincronizam sozinhas, que é o antipadrão que o passo 11 persegue) e não as torna mais transversais: o que torna uma regra transversal é que cada bloco passe pela mesma comporta, não que a regra esteja escrita em todas partes.

Estado (D-049). As cinco âncoras estão ligadas: o prompt inicial dos peldanos 5, 8, 9, 10 e 12 cita este anexo nos oito idiomas, com uma única redação inglesa idêntica em todos e a sua tradução local ao lado. O documento é publicado no site com o resto do método nos oito idiomas, e os seus dois prompts entraram em docs/html/api/prompts.json como contrato anexo-h: a partir dali build/prompts.mjs compara-os byte a byte nos oito ou a construção falha.

Os passos 6, 7 e 11 recebem no máximo uma linha: o 6 já registra limiares e exceções como decisões (e o lugar natural da exceção declarada), e o 11 é onde entra a golpes o caso da matriz escrita em quatro lugares. Não se lhes agrega texto próprio para não diluí-los.

Três artefatos, todos em docs/: CODE_QUALITY.md (estendido), USABILITY.md (novo, com o resultado por regra e as exceções declaradas) e PROFILE_MATRIX.md (a matriz, que é ao mesmo tempo documento e fonte do menu).

7. Configuração

Um único arquivo por projeto declara a capa 2 e a capa 3. Exemplo com a forma proposta, não com valores definitivos:

{
  "version": 1,
  "frontend": "react-vite",
  "measured_by": {
    "format": "prettier",
    "lint": "eslint",
    "types": "tsc",
    "complexity": "eslint-complexity",
    "duplication": "jscpd",
    "dead": "knip",
    "coverage": "vitest-coverage",
    "mutation": "stryker",
    "accessibility": "axe-core"
  },
  "thresholds": {
    "lines_per_file": 300,
    "lines_per_function": 40,
    "paths_per_function": 10,
    "minimum_coverage": 0,
    "mutation_target": 0
  },
  "exceptions": [
    {
      "rule": "CQ-17",
      "reason": "relatório imprimível herdado, sem tokens",
      "authorised_by": "dono",
      "review": "2027-01-31"
    }
  ]
}

Os dois zeros são deliberados e são a parte que importa: a cobertura mínima a fixa a catraca com o medido, e o objetivo de mutação o fixa o dono quando o projeto tem usuários. Se estão em zero e ninguém os declarou, a comporta o reporta como limiar não declarado em vez de inventá-lo.

8. As duas peças, na forma que o método usa

Qualidade de código.

Usabilidade.

9. O que esta proposta não faz

• Não agrega um passo. São quarenta e cinco regras transversais (18 de qualidade e 27 de usabilidade), não uma etapa nova. Penduram-se nos passos que já existem.
• Não inventa um escore. Um número de "usabilidade 78" não diz o que arrumar e se otimiza na direção errada. Se reporta por regra. A seção 12 propõe duas cifras derivadas, mas são uma contagem de regras com o seu assento - não uma nota de qualidade nem de usabilidade - e não autorizam fechar nada.
• Não substitui o dono. O teste do primeiro clique, a captura e o teste de tarefa continuam sendo humanos: são o único instrumento que distingue "funciona" de "serve".
• Não traz limiares de fabrica. Os do adaptador são um ponto de partida declarado; o projeto que não declare os seus os herda e fica registrado como tal.
• Não promete que a comporta detecte o mau agrupamento. Uma máquina pode verificar que não haja duplicação nem órfãs; se o grupo se chama "Gestão", tem que ver uma pessoa.

10. As decisões: o que ficou resolvido e o que falta

Resolvidas

Fechado em D-048, e as duas correções que arrasta

As duas perguntas que travavam a escrita dos prompts já estão respondidas: a 1 ficou na linha 5 e a 2 na linha 6. Mas a recomendação que se aprovou tinha dois erros de fato, e ficam escritos aqui para que não voltem:

1. O defeito da contagem. Onde este anexo dizia "vinte e sete regras" o número correto é quarenta e cinco: 18 de qualidade (CQ-01 a CQ-18) e 27 de usabilidade (UX-01 a UX-27). A cifra velha vinha de um rascunho que só contava a metade. Corrigido nas seções 6 e 9 e anotado em D-048; o texto de D-044 se conserva tal como se escreveu, porque uma decisão é um registro e não se reescreve.
2. O formatador, o linter, o tamanho e a complexidade não se afrouxam. Uma versão anterior desta recomendação os mandava a "avisa" para não travar projetos com dívida herdada. Não pode ser: o passo 9 já os bloqueia hoje, e esta extensão o estende, não o substitui. A dívida herdada se resolve com exceção declarada - com motivo e data de revisão - ou com a linha de base da catraca, não baixando a severidade da regra.

É uma limitação declarada, porque é a única de sua classe: CQ-12 e CQ-14 bloqueiam com vermelho humano. Nenhuma ferramenta prova que uma tela não decide regras de negocio. Se verificam no fechamento do pendente, com o caso manual na frente e o mesmo critério que UX-22 e UX-27; se o projeto não consegue sustentar esse fechamento, baixam a AVISA por decisão registrada. Uma regra que bloqueia e que ninguém verifica e pior que uma regra que avisa.

Calendário, não decisão

A tradução. Feita: o anexo existe nos oito idiomas e os seus dois prompts fazem parte da API de prompts, idênticos em ingles nas oito versões (D-043 o exige e build/prompts.mjs o faz cumprir). O texto em castelhano continua sendo o canônico: se alguma vez uma tradução e o castelhano discordarem, ganha o castelhano e a tradução se corrige na mesma mudança.

11. Como se comprova que a comporta vigia

Uma heurística que não muda nada quando se acende ou se apaga não é uma comporta, é decoração. A prova de aceitação da implementação (PND-002) é um projeto fixture com violações deliberadas de cada família:

O que se olha não é só a cor: se olha que as duas linhas de apagado existam no reporte. Um resultado verde sem essa linha é o único fracasso que esta prova não pode detectar sozinha por cor, e por isso se verifica lendo a saída.

12. O painel de cumprimento (DECIDIDO: duas cifras, D-047)

Estado. Decidido em 2026-10-22 em D-047: o painel vai com duas cifras, com a impressão digital do regulamento, com catraca, com o humano fora da porcentagem e com o assento obrigatório. Não autoriza fechar blocos. O que segue é a especificação que a implementação (PND-002) tem que cumprir.

O que é. Um derivado determinista do resultado por regra que a comporta já emitiu. Não mede nada novo nem julga nada novo: conta. Se o painel pudesse mudar o veredito de uma regra haveria duas fontes de verdade para o mesmo, que é exatamente o que o anexo combate em UX-10 (a navegação se deriva da matriz) e em CQ-14 (um único lugar para o estado).

O que não é. Não é um critério de aceitação. Nenhuma cifra autoriza fechar um bloco: o verde ou o vermelho o decide cada regra que bloqueia, uma por uma. O painel descreve a tendência e aponta o que olhar. Se começa a se usar como limiar de fechamento, deixou de servir, porque o caminho mais curto para subir um número é apagar regras.

Duas cifras, nunca uma.

A razão de que sejam duas: apagar uma regra sobe o cumprimento e baixa a cobertura. Com uma única cifra apagar é grátis e o painel premia a cegueira. Com duas cifras que se movem em direções opostas, o atalho desaparece: para mostrar um painel melhor tem que se arrumar código, não apagar regras. E a cobertura não se pode subir sem medir.

A impressão digital do regulamento. Cada registro guarda com que medida se calculou: versão do catálogo, regras ativas e apagadas, adaptador de frontend e versões das ferramentas. Sem isso, um 82 de ontem e um 91 de hoje não são a mesma medida ainda que se escrevam igual: são dois regulamentos distintos e a série é falsa. Duas cifras sem impressão digital produzem uma ilusão de progresso, que é pior que não ter painel. Se a impressão digital muda, o registro se marca como não comparável ou o histórico se recalcula com a medida vigente; nunca se grafa junto sem dizê-lo.

Catraca. O cumprimento não baixa de um bloco ao seguinte sem uma decisão registrada que o explique. É o mesmo mecanismo que a cobertura de testes já tem em CQ-08: o número de hoje é o piso de amanhã. Baixar não está proibido; baixar sem registro, sim.

O que não entra na conta. O que só pode julgar uma pessoa - o teste do primeiro clique (UX-07), o teste de tarefa (UX-06), a captura (UX-27) e todos os casos manuais - se registra como passado ou falhado, por bloco, com nome e data, e se reporta a parte como cobertura de verificação humana. Não entra na porcentagem de cumprimento. Se se misturam, o resultado é um número que é sessenta por cento medição e quarenta por cento opinião, e ninguém pode dizer qual é qual. Por isso a seção 9 segue valendo: o painel não inventa uma nota de usabilidade, conta regras.

Como se falsifica. Amplia a prova de aceitação da seção 11:

Onde aparece. No reporte honesto do passo 12 (âncora 5), e nesta ordem: primeiro o veredito binário da comporta, depois as duas cifras, depois o que está apagado e até quando, depois o movimento contra o bloco anterior com a sua causa nomeada. Sempre com o assento: baixou quatro pontos: CQ-15, três cadeias fora do catálogo na tela de cobrança. Uma cifra sem assento é ruído; o assento é o que a torna acionável para um dono que não lê código.

Risco declarado. O painel vai ser lido pelo dono, que não lê código, e por isso vai querer que suba. O número se converte no objetivo, e o objetivo desloca o propósito. As defesas são as de cima, e são cinco: duas cifras que se contradizem ao apagar, a impressão digital que impede comparar medidas distintas, a catraca que não deixa baixar sem registro, o humano fora da porcentagem e o assento obrigatório, com a comporta que não se negocia por média. Se alguma das cinco cai, o painel se apaga: um painel mal usado faz mais dano que não te-lo.

13. Registro

Toda decisão deste anexo fica em docs/DECISIONES.md com data, autor, citação textual e arquivos de impacto: D-043 (forma), D-044 (mecanismo), D-045 (interruptores), D-046 (disciplina do interruptor), D-047 (o painel com duas cifras) e D-048 (severidades iniciais e o peso da acessibilidade). A implementação e os seus critérios de aceitação vivem em PND-002; a tradução e a indexação, em PND-003.

Não fica nenhuma decisão aberta: a forma (D-043 e D-044), os interruptores (D-045 e D-046), o painel (D-047) e as severidades iniciais com o peso da acessibilidade (D-048) estão decididas. O texto viaja nos oito idiomas e faz parte da API de prompts, o que fecha o único item que ficava no calendário.