Disciplina de Verificação

1. Visão Geral da Conceção e o Problema Sistémico

Com a evolução das ferramentas de autogeração, surgiu um fosso crítico entre a simplicidade de criar código e as suas reais qualidades de fiabilidade. Um modelo pode gerar 400 linhas de código impecavelmente formatado com nomes de métodos plausíveis, que aparentam autoridade, mas falha no primeiro segundo de execução devido à chamada de um método inexistente ou a uma incompatibilidade de tipos.

Verification Discipline (Disciplina de Verificação) é a principal barreira demarcatória entre um engenheiro de software profissional e um amador. Trata-se de uma postura interna inabalável:

• Nenhuma palavra do modelo de linguagem é aceita como verdade absoluta.
• Qualquer código gerado é considerado potencialmente quebrado até que seja provado o contrário por uma ferramenta determinística independente (compilador, linter, test runner).
• O engenheiro assume responsabilidade profissional pessoal por cada símbolo integrado (merged) no repositório.

Sem a disciplina de verificação, o projeto degrada-se para um estado de "castelo de cartas frágil", onde cada nova funcionalidade quebra duas anteriores, e a equipa desperdiça todos os seus esforços a apagar incêndios súbitos em produção.

Abordagem amadora (Confiança cega):
[LLM: "Corrigi tudo, o código está pronto!"] ---> [Clique em "Aceitar Tudo"] ---> [Commit & Push] ---> [502 Bad Gateway em produção]

Disciplina de engenharia de verificação (Evidence-First):
[LLM: "Corrigi tudo!"]
          |
          v
[Passo 1: tsc --noEmit] -----------------> [Erro de tipo! Devolução ao agente para retrabalho]
          | (Verde)
          v
[Passo 2: vitest run] -------------------> [Falha no teste! Correção da lógica]
          | (Verde)
          v
[Passo 3: git diff --cached] ------------> [Detectado console.log desnecessário e biblioteca alucinada]
          | (Limpo)
          v
[Passo 4: Smoke Test no navegador] -------> [Clique físico no formulário]
          |
          v
[Commit consciente em Produção]

2. Taxonomia Arquitetural e Modelo Mental

Níveis de barreiras de proteção na verificação (The Swiss Cheese Model):

1. Nível 1: Análise Sintática e Semântica Estática (Compile-time):
   • Compiladores rigorosos (tsc --noEmit, rustc, cargo check).
   • Linters de estilo e segurança (ESLint, Biome, ShellCheck).
   • Eliminam 70% das alucinações relativas a campos ou métodos inexistentes.
2. Nível 2: Teste Dinâmico Automatizado (Dynamic Verification):
   • Unit tests: validação de funções puras e casos-limite.
   • Integration tests: validação da interação com bases de dados reais ou caches.
   • Protegem contra erros lógicos e regressões.
3. Nível 3: Auditoria de Alterações (Diff Hygiene):
   • Leitura humana das diferenças de linha através de git diff.
   • Objetivo: detetar "lixo", comentários removidos acidentalmente e violações de fronteiras arquiteturais.
4. Nível 4: Verificação em Runtime (End-to-End & Observability):
   • Execução de cenários reais de utilizador via Playwright ou manualmente no browser/terminal.
   • Monitorização de logs pós-release para identificar picos de erros 5xx.

3. Pipeline Técnico e Mecânica Interna

Hook Git Pre-Commit Automático de Verificação (Husky / Lefthook)

Os humanos podem esquecer-se de verificar o código devido ao cansaço. Para proteger o sistema do fator humano, o circuito de verificação bloqueia fisicamente o commit:

# lefthook.yml — надійний та швидкий валідатор
pre-commit:
  parallel: false
  commands:
    typecheck:
      run: npx tsc --noEmit
    lint:
      run: npx @biomejs/biome check --staged --apply
    test:
      run: npx vitest run --passWithNoTests

Se pelo menos um teste falhar ou se o compilador detectar divergências de tipos, a tentativa de commit resulta numa paragem abrupta.

Checklist de Auditoria Manual de Diff (Diff Inspection Protocol)

Antes de executar o comando git push, o engenheiro verifica:

- [ ] O agente não removeu código importante em partes não relacionadas do arquivo?
- [ ] Os casos extremos foram tratados (null, undefined, array vazio, 404)?
- [ ] Não há senhas, segredos e tokens de teste codificados diretamente no código?
- [ ] O diff não contém alterações aleatórias de formatação em 50 arquivos alheios?
- [ ] Os nomes das novas entidades estão em conformidade com os padrões adotados pelo projeto?

4. Cenários Práticos de Engenharia em Produção

01. Detecção de Alucinação Subtil num Módulo Financeiro

Um agente escreveu uma função de cálculo de taxas bancárias e afirmou confiantemente: "A lógica foi atualizada conforme as regras". O engenheiro aplicou a disciplina de verificação e criou um teste para uma quantia negativa (amount: -100). Descobriu-se que a função devolvia uma taxa negativa, o que permitiria a criminosos roubar dinheiro das contas da empresa. O bug foi corrigido antes do release.

02. Proteção Contra Remoção Silenciosa de Comentários num Sistema Legacy

Durante um refactor, um módulo continha um comentário crucial: // CRITICAL: do not reorder this call due to Safari bug #19284. O modelo considerou o comentário supérfluo e removeu-o, alterando a ordem das chamadas. Graças a uma revisão atenta do git diff, o arquiteto notou a remoção, preservou o workaround de proteção e adicionou um teste E2E de regressão.

03. Reprodução Completa de Bug via Teste Antes da Correção (Bug Repro First)

Ao receber um relatório de falha, um engenheiro disciplinado proíbe o agente de tocar no código de produção. Primeiro, escreve-se um teste que reproduz exatamente o bug e falha com erro vermelho (Red Phase). Apenas após garantir que o bug é capturado pelo teste, o agente aplica alterações até que o teste passe a verde (Green Phase).

5. Armadilhas, Erros Comuns e Segurança

1. "Diff Blindness" (Cegueira de Revisão): Quando um diff excede 800 linhas, os olhos cansam-se e, após 2 minutos de scroll, o engenheiro simplesmente clica em "Approve". Se o PR for demasiado grande — nunca o aprove na totalidade. Exija que a tarefa seja dividida em partes atómicas de até 200 linhas cada.
2. Mocks que Passam Sempre (Tautological Tests): Os agentes frequentemente geram testes que validam os seus próprios mocks: mockService.get.mockReturnValue(true); expect(mockService.get()).toBe(true). Este teste está sempre verde, mas não valida nenhuma linha de código real. Verifique sempre a semântica das assertions nos testes gerados.
3. Ignorar Avisos do Compilador (Compiler Warnings): A tendência de ignorar avisos amarelos do linter ou converter implicitamente tipos via as unknown as Type destrói completamente o sistema de segurança do TypeScript. Adote a regra: zero avisos na consola.