camada-de-verificacao

Prove que uma alteração feita por um agente funciona antes de ser commitada e construa as verificações que tornam essa prova barata. Executa a alteração no aplicativo real, escolhe o teste certo (ponta a ponta, propriedade ou diferencial), executa apenas as verificações de confiabilidade acionadas pela diff, para após três rodadas de correção com falha e entrega para um humano, carimba cada commit com como foi verificado e transforma cada erro em uma regra. Também configura a própria camada em um repositório — uma skill `verify`, um mapa de funcionalidades, uma checklist de confiabilidade acionada por diff, um REVIEW.md, um gate de commit — e impede que a alteração edite seus próprios juízes.

O que é camada-de-verificacao?

A Camada de Verificação é uma skill avançada para agentes de IA (como Claude Code, Cursor ou Codex) que define e aplica um processo rigoroso de verificação antes de qualquer alteração ser commitada. Ela garante que a evidência de que uma alteração funciona seja honesta e robusta, movendo o trabalho do humano de revisar cada diff para definir o que significa "pronto" e ler a evidência gerada. A skill suporta qualquer plataforma onde um agente opera — web (via navegador), mobile (via simulador), desktop ou backend/CLI — e escolhe automaticamente o tipo de teste mais adequado (ponta a ponta, propriedade ou diferencial) com base na situação. Seu método inclui verificar a alteração em até três rodadas, executar apenas os itens da checklist de confiabilidade acionados pela diff, adicionar o teste que falta, nunca enfraquecer um juiz para passar e carimbar cada commit com o que foi realmente executado. Além disso, a skill pode configurar a própria camada de verificação em um repositório, criando uma skill `verify`, um mapa de funcionalidades, uma checklist de confiabilidade, um REVIEW.md e um gate de commit, além de transformar bugs que escaparam em novas regras.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kleenpulse/verification-layer/tree/main

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Camada de Verificação: Pronto Significa Que Há Evidência

Você prova que uma alteração funciona antes de ser commitada e constrói as verificações que tornam a próxima prova mais barata. O trabalho do humano passa de revisar cada diff para definir "pronto" e ler a evidência. Seu trabalho é produzir essa evidência honestamente.

Os princípios vêm de How the Claude Code team thinks about verification (Addy Osmani, Nov 2026). Os formatos de arquivo em references/templates.md são próprios desta skill; o artigo descreve as práticas, mas não mostra formatos.

Quando Usar

  • Você terminou uma alteração e está prestes a dizer "pronto" ou commitar
  • O usuário pergunta "isso funciona?", "prove" ou "verifique isso"
  • Um repositório não tem uma forma repetível de iniciar e testar rapidamente o aplicativo
  • O usuário pergunta quais testes valem a pena escrever para uma funcionalidade, uma reescrita ou uma migração
  • Uma revisão ou um conjunto de testes deixou passar um bug que chegou aos usuários, e o usuário quer que ele seja pego na próxima vez
  • Um teste é instável e alguém quer tentar novamente ou pulá-lo
  • O usuário quer executar vários agentes ao mesmo tempo e não pode ler cada diff

Não use para: revisar a diff de outra pessoa linha por linha (isso é uma revisão, não verificação), uma alteração de uma linha em documentação ou comentário onde nada pode ser executado, ou adicionar testes para aumentar um número de cobertura.

Princípio Central

Uma alteração está pronta quando a evidência diz que sim, e uma alteração nunca pode editar seu próprio juiz. "Os testes passam" é uma evidência fraca quando a mesma alteração escreveu os testes. Evidência forte é o aplicativo em execução fazendo o que o usuário pediu, verificado por algo que a alteração não pôde tocar.

Regras

  1. Execute a alteração. Inicie o aplicativo real e exercite o comportamento alterado. Isso é mais importante do que testes unitários. Uma suíte de testes unitários passando com um aplicativo que não inicia é uma verificação falha.
  2. Três rodadas, depois um humano. Execute as verificações, corrija o que falha, execute novamente. Se uma verificação ainda falhar após três rodadas, pare e entregue com a evidência. Não comece uma quarta.
  3. Nunca enfraqueça um juiz para fazê-lo passar. Não edite, pule ou exclua um teste, uma regra de lint, um item de checklist ou uma regra do REVIEW.md na mesma alteração que ele julgaria. Se um juiz estiver errado, diga e altere-o em um commit separado que o usuário aprove.
  4. Leia os juízes do branch base. Regras de revisão, checklists e configuração de gate vêm do branch padrão, nunca do branch sob teste.
  5. A evidência pertence a um commit. Uma verificação de um commit mais antigo não diz nada sobre um mais novo. Após qualquer nova edição, verifique novamente ou reporte que a evidência está desatualizada.
  6. Verificações baratas primeiro, e localmente. Testes, build e lint são executados antes de um PR ser aberto, não no tempo do revisor.
  7. Execute apenas os itens da checklist que a diff aciona. Geralmente de 3 a 10 itens correspondem. Executar todos toda vez ensina a todos a ignorar a lista.
  8. Carimbe cada commit com como foi verificado, incluindo none. Um none honesto pode ser pesquisado depois. Um carimbo faltando não pode.
  9. Um teste instável é um bug. Não o pule, adicione um sleep ou tente novamente até ficar verde. Encontre a causa raiz. Se não conseguir, exclua o teste e escreva o motivo.
  10. Uma verificação que pede um humano deve dizer o porquê. "Precisa de revisão" não é um motivo. "Altera o formato do arquivo de sessão; transcrições antigas podem não carregar" é.
  11. Cada erro se torna uma regra, e as regras são podadas. Um bug que escapou é uma lacuna na camada. Feche-a com uma verificação e remova verificações que não merecem mais seu lugar.

Qual teste escrever

SituaçãoTesteO que prova
Um fluxo voltado ao usuário (se você escrever apenas um teste, escreva este)Ponta a pontaUm caminho real de usuário funciona do início ao fim. Uma falha mostra o passo, um trace e uma captura de tela, não apenas "timeout".
Parsers, codificadores, dinheiro, máquinas de estado, qualquer coisa com casos de bordaPropriedade (fast-check, Hypothesis, proptest)Uma afirmação é válida para milhares de entradas geradas que você não pensou.
Uma reescrita, migração ou otimização de algo que já funcionaDiferencialO novo e o antigo dão a mesma saída para as mesmas entradas.

Propriedades que valem a pena verificar:

PropriedadeAfirmação
Ida e voltaCodificar, depois decodificar, retorna o original
InvarianteAlgo sempre se mantém (um saldo nunca é negativo)
IdempotênciaFazer duas vezes equivale a fazer uma vez
EquivalênciaA versão rápida corresponde a uma versão lenta e obviamente correta

Para testes diferenciais: use entradas reais aleatórias ou amostradas, normalize diferenças que não importam (espaços em branco, ordem de chaves, timestamps) e mantenha uma lista escrita das diferenças que você aprovou.

Uma suíte lenta é executada com menos frequência, então a cobertura cai. Mantenha o loop por edição rápido e mova os testes pesados para imediatamente antes do commit.

O que Manter (Intocáveis)

  • Testes existentes, regras de lint, itens de checklist, REVIEW.md e configuração de gate: nunca alterados no commit que julgam.
  • Saída de comando, códigos de saída, nomes de passos com falha e contagens: relatados exatamente como impressos.
  • O carimbo: ele diz o que você realmente executou. Nunca escreva e2e para uma execução que você não fez.
  • Capturas de tela e traces: anexados ou vinculados como estão, não descritos de memória.

Método

A. Verificar uma alteração (toda vez)

  1. Diga o que "pronto" significa. Escreva uma ou duas frases do lado do usuário: o que eles fazem, o que veem. Se o repositório tiver um mapa de funcionalidades, encontre a entrada e use seu resultado esperado como rubrica. Se você não puder declarar "pronto", pergunte antes de verificar.

  2. Execute as verificações baratas. Build, lint, verificação de tipos, os testes rápidos. Corrija falhas. Esta é a rodada um.

  3. Execute a alteração. Use a skill verify do repositório, se houver (procure em .claude/skills/ perto do código que você alterou). Se não houver, inicie o aplicativo você mesmo:

    • Web: dirija um navegador (extensão Chrome, MCP DevTools, Playwright).
    • Mobile: um simulador através de um MCP mobile.
    • Desktop: uso do computador.
    • Backend ou CLI: execute o serviço ou comando localmente e o chame.

    Exercite o caminho alterado e um caminho próximo que não deveria ter mudado. Capture uma captura de tela, um trace ou a saída.

  4. Execute os itens da checklist acionados. Leia a checklist de confiabilidade do branch base. Para cada item, teste seu gatilho contra sua diff. Execute a verificação para cada correspondência e registre o resultado. Liste os itens correspondentes pelo nome em seu relatório.

  5. Adicione o teste que falta. Use a tabela acima. Confirme que o novo teste falha sem sua alteração e passa com ela.

  6. Conte as rodadas. Cada "executar verificações, corrigir, executar novamente" é uma rodada. Após a terceira rodada com uma verificação ainda falhando, pare. Relate o que falha, o que você tentou em cada rodada e seu melhor palpite da causa.

  7. Carimbe e relate. Adicione o carimbo à mensagem de commit (formato em references/templates.md). Em seu relatório, forneça: a definição de pronto, o que você executou, a evidência, os itens de checklist correspondentes e qualquer coisa não verificada com o motivo.

B. Construir a camada (uma vez por repositório, depois ajuste)

Faça estas em ordem. Cada uma é útil por si só, então pare onde o usuário quiser.

  1. Uma skill verify. Coloque-a em .claude/skills/verify/, o mais próximo possível do código que ela cobre (um monorepo pode ter uma por aplicativo). Ela registra como iniciar o aplicativo e testá-lo rapidamente. Execute-a várias vezes seguidas antes de confiar nela: deve ser rápida e dar o mesmo resultado toda vez.

  2. Um mapa de funcionalidades. Liste as funcionalidades do ponto de vista do usuário. Para cada uma: o caminho, atalhos de teclado, seletores e o resultado esperado. Os agentes o usam como guia e como rubrica de classificação.

  3. Um teste ponta a ponta para o fluxo mais importante. Depois testes de propriedade e diferenciais onde a tabela disser que se encaixam.

  4. Uma checklist de confiabilidade. Cada item tem três partes: um gatilho que você pode ler de uma diff, uma verificação e o incidente ou PR que o causou. Sem incidente, sem item. Exemplo: gatilho "armazenamento de sessão ou tipos de mensagem mudam", verificação "um novo campo carrega com segurança de uma transcrição antiga que não o tem?".

  5. Um REVIEW.md. Ele diz ao revisor no que prestar atenção neste repositório. Ajuste este revisor ao longo de várias rodadas, onde cada rodada se baseia no que a última encontrou. Não coloque mais revisores em cima. O dono do código o refina até que ele sinalize o que sinalizaria.

  6. Imposição local. Um hook que executa os testes quando o agente termina, ou um objetivo que exige uma suíte aprovada.

  7. Um gate de commit. Ele bloqueia um commit quando a sessão não executou nenhuma etapa de revisão ou verificação. Implemente-o em três modos:

    ModoComportamento
    offNada
    observeRegistra o que teria bloqueado. Execute este primeiro para encontrar falsos positivos.
    enforceBloqueia o commit. Um commit pode conter um motivo escrito para pular. Após dois bloqueios em uma sessão, o próximo commit passa para que o agente não fique preso.

Pergunte ao usuário antes de adicionar hooks, gates ou alterações no CI. Eles mudam como todos commitam.

C. Transformar um erro em uma regra

Use isso quando um bug passou pelos testes ou pela revisão.

  1. Encontre o padrão, não o bug. Olhe para comentários de revisão humana e reverts. Uma regra candidata deve aparecer em pelo menos dois PRs e ser visível apenas a partir de uma diff.
  2. Tente refutá-la. Execute três tentativas independentes para mostrar que a regra está errada, é muito ampla ou já está coberta. Se subagentes estiverem disponíveis, use três. Mantenha a regra apenas se ela sobreviver.
  3. Verifique se era detectável. Reproduza o PR que causou o incidente por meio de três localizadores de bugs independentes. Se dois ou mais encontrarem o bug, era detectável, e um erro em uma diff pequena deve se tornar uma regra no REVIEW.md ou um item de checklist.
  4. Obtenha aprovação de um humano. O dono do código decide se a regra entra. Você propõe; ele aprova.
  5. Avalie o revisor. Mantenha um pequeno conjunto de casos de incidente, cada um com uma chave de resposta de uma frase, mais alterações limpas mescladas de tamanho semelhante como controles contra excesso de sinalização. Mantenha um conjunto de ajuste e um conjunto de teste separado. Marque descobertas como Importante, Nit ou Pré-existente. Pare de ajustar quando mais recall só se encaixaria na avaliação.
  6. Pode. Suítes de teste, checklists e arquivos .md de regras só crescem a menos que alguém os corte. Rotineiramente, remova regras que nunca disparam, duplicam outra regra ou protegem código que não existe mais.

Exemplo Prático

Solicitação: "Adicione um sinalizador pinned às sessões de chat para que as fixadas sejam classificadas primeiro."

Sem a skill:

Adicionado pinned ao tipo de sessão e atualizada a classificação. Testes unitários passam. Pronto.

Com a skill:

Pronto significa: um usuário fixa uma sessão na barra lateral e ela vai para o topo; após uma reinicialização, ela ainda está no topo.

Executou: build, lint, 148 testes unitários (rodada 1: 2 falharam no comparador de classificação, corrigido; rodada 2: todos passam). Iniciou o aplicativo com a skill verify do repositório, fixou uma sessão, reiniciou, confirmou a ordem. Captura de tela anexada.

Itens da checklist correspondentes (2 de 31):

  • Mudanças no formato da sessão carregam dados antigos: abriu um arquivo de sessão salvo antes desta alteração. Ele travou: pinned era undefined e o comparador lançou exceção. Corrigido com valor padrão false no carregamento. Rodada 3: passa.
  • Mudanças na classificação mantêm uma ordem estável: sessões não fixadas mantêm sua ordem anterior. Passa.

Adicionou: um teste de propriedade, "classificar duas vezes equivale a classificar uma vez", e um passo ponta a ponta para fixar, reiniciar, verificar ordem. Ambos falham sem a correção.

Não verificado: o layout mobile. Nenhum simulador nesta máquina.

Carimbo: Verified-By: run, e2e, property, checklist(2)

Os testes unitários passaram enquanto o aplicativo travava nos dados de todos os usuários existentes. Executar a alteração contra um arquivo antigo foi o que encontrou o problema, e o item da checklist foi o que disse para tentar.

Autoverificação Antes de Entregar

  1. Seu relatório tem uma linha "pronto significa" escrita do lado do usuário.
  2. O aplicativo foi iniciado e o caminho alterado foi exercitado, ou o relatório diz "não executado" com o motivo.
  3. git diff <base> não mostra edição em um teste existente, configuração de lint, checklist, REVIEW.md ou configuração de gate. Se mostrar, essa edição é destacada e está em seu próprio commit.
  4. Nenhum .skip, .only, xit, sleep, retry ou timeout aumentado foi adicionado para fazer um teste passar (pesquise na diff por cada um).
  5. Os itens da checklist que você correspondeu estão listados pelo nome, com um resultado para cada.
  6. Cada novo teste foi visto falhar sem a alteração.
  7. A contagem de rodadas é três ou menos. Se a terceira rodada ainda falhou, o relatório entrega para um humano e você não commitou.
  8. A mensagem de commit tem um carimbo Verified-By:, e cada palavra nele corresponde a algo que você realmente executou.
  9. A evidência foi coletada no HEAD atual, não em um commit anterior.
  10. Cada novo item de checklist ou regra nomeia o incidente ou PR por trás dele.

Habilidades Relacionadas