Como escrever critérios de aceite na spec para saber quando a implementação terminou

Fala aí, beleza? A implementação "terminou" quando alguém ACHOU que terminou

Esse é o estado normal de muita spec por aí, e com agente de IA no meio a coisa fica mais engraçada ainda: ele devolve o código, escreve "tudo pronto!" no final e você não tem nenhum jeito objetivo de discordar

Critério de aceite verificável é exatamente o que fecha esse buraco: um procedimento sem ambiguidade que devolve passou ou falhou, de um jeito que o agente não consiga produzir um "passou" sem que o comportamento seja real

No Spec-Driven Development a divisão de trabalho é bem clara: a spec define o que construir, os critérios de aceite definem o "pronto" e verificações automatizadas conferem a implementação

Bora ver como escrever esses critérios sem cair no "o sistema deve ser rápido"? 🙂

O que você precisa ter antes de escrever os critérios

Critério de aceite não é o primeiro artefato da fila, ele vem depois de você já ter o "o quê" escrito em algum lugar

O mínimo pra começar:

• Uma spec ou história já escrita, mesmo curtinha: uma especificação leve já serve, desde que traga critérios verificáveis com propósito operacional, ou seja, orientar as mudanças, expor as decisões e oferecer algo contra o que testes e revisões comparem a implementação
• Clareza sobre escopo: critério de aceite vale pra UMA história ou funcionalidade específica, enquanto os itens da Definition of Done se aplicam a todos os itens do Product Backlog. No Scrum Guide 2020 a Definition of Done é o compromisso do Incremento, descrevendo formalmente o estado em que ele atende às medidas de qualidade exigidas pelo produto
• A decisão de qual notação usar: Gherkin ou EARS

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 118 aulas
• 4 projetos
• 9h 33min

Conhecer formação

As duas notações que você vai escolher:

Gherkin é a linguagem estruturada usada pra escrever critérios legíveis por pessoas e executáveis por frameworks de teste, no formato Dado/Quando/Então

A ideia é simples: Given é o contexto inicial, When é a ação e Then é a consequência observável

O vocabulário completo tá na referência do Gherkin: Feature, Background, Scenario, Given, When, Then, And, But e Scenario Outline

EARS (Easy Approach to Requirements Syntax) é o outro caminho, mais próximo de requisito de engenharia

Ele diferencia cinco padrões de requisito: ubíquo, dirigido a evento, comportamento indesejado, dirigido a estado e funcionalidade opcional

O padrão de frase que aparece em critério de aceite é a forma condição/evento mais comportamento esperado do sistema:

WHEN <condição/evento> THE SYSTEM SHALL <comportamento esperado>

Qual escolher? Se o time já tem framework de teste que lê cenário, Gherkin te dá execução direta

Se o que você quer é requisito curto e sem gordura pra alimentar um agente, EARS costuma ser mais seco

Os dois funcionam, o que NÃO funciona é frase solta em português livre sem forma nenhuma

Como escrever critérios de aceite verificáveis passo a passo

1. Separe intenção de comportamento observável

Intenção é o que você quer que aconteça no mundo ("o usuário precisa conseguir recuperar a senha sem sofrer")

Comportamento observável é o que dá pra ver acontecendo na tela, no log, na resposta da API

Critério de aceite mora só no segundo grupo, porque ele precisa ser uma afirmação que pode ser marcada como verdadeira ou falsa depois da implementação

O erro comum deste passo: adjetivo sem medida. "Rápido", "intuitivo", "robusto", "amigável". Nenhum desses vira verdadeiro/falso sozinho

2. Escreva o cenário na notação escolhida

Em Gherkin, o esqueleto fica assim:

Feature: Recuperação de senha

  Background:
    Given que existe uma conta cadastrada com o e-mail "[email protected]"

  Scenario: Solicitação com e-mail cadastrado
    Given que estou na tela de recuperação de senha
    When eu informo o e-mail "[email protected]"
    And confirmo o envio
    Then o sistema exibe a mensagem de e-mail enviado
    And um link de redefinição é registrado para essa conta

Quando o mesmo cenário roda com valores diferentes, o Scenario Outline evita você copiar e colar cinco vezes a mesma coisa

Em EARS, o mesmo comportamento vira uma linha:

WHEN o usuário confirma o envio com um e-mail cadastrado
THE SYSTEM SHALL exibir a mensagem de e-mail enviado e registrar um link de redefinição para a conta

O erro comum deste passo: critério que descreve implementação em vez de comportamento. "O sistema deve gravar na tabela password_resets" não é critério de aceite, é decisão de design, e ela mora na spec técnica, não aqui

3. Cubra as três frentes

O papel do critério é informar o comportamento esperado da história exercitando cenários positivos, negativos e de usabilidade

Então pra cada história tu precisa de pelo menos:

• o caminho positivo (deu tudo certo)
• o caminho negativo (e-mail não cadastrado, campo vazio, permissão faltando)
• a frente de usabilidade (a mensagem aparece? o botão fica desabilitado durante o envio? o foco vai pro campo com erro?)

É aqui que o And e o But do Gherkin ganham utilidade, e em EARS é onde entram os padrões de comportamento indesejado e dirigido a estado

O erro comum deste passo: cenário único só do caminho feliz. É o clássico. A funcionalidade "passa" e quebra no primeiro input torto que um usuário real digitar

4. Reescreva cada critério vago até ele virar verdadeiro/falso

Pega a lista pronta e faz a pergunta seca em cada linha: depois de entregue, eu consigo marcar isso como verdadeiro ou falso sem discussão?

Se a resposta for "depende de quem olhar", o critério ainda não existe, é só uma intenção com cara de requisito

O erro comum deste passo: aceitar "quase". Frase tipo "o carregamento não pode demorar muito" parece específica, mas "muito" não tem procedimento de checagem

5. Aponte cada critério para uma verificação que devolve passou ou falhou

Este é o passo que a maioria pula

Não basta o critério ser checável em teoria, alguém (ou alguma coisa) precisa checar de verdade: um teste automatizado, um passo de revisão, um comando que roda e responde

Se você escreveu Gherkin, a vantagem é direta, porque o formato já é legível por pessoas e executável por frameworks de teste

Se escreveu EARS, amarre cada frase a um teste nomeado ou a um item de checklist que alguém marca com o olho no comportamento, não na intenção

O erro comum deste passo: critério lindo que ninguém sabe como checar. Ele passa a ser decoração da spec

Critério bom, critério inútil e como transformar um no outro

Se liga nos pares lado a lado

A coluna da esquerda é o que costuma aparecer na história, a do meio é a reescrita e a da direita é o que fecha o critério:

Repara no padrão da reescrita: toda linha da coluna do meio tem condição, ação e consequência observável

É isso que separa critério de opinião

E repara também que a coluna da direita nunca é "o time avalia": ou tem procedimento, ou não tem critério

Onde os critérios de aceite entram nas ferramentas de spec

Agora a parte prática, porque isso tudo já vive dentro das ferramentas que a galera usa pra escrever spec com IA

Kiro: os critérios moram no requirements.md

O Kiro gera três arquivos por especificação: requirements.md, design.md e tasks.md

O requirements.md é o que guarda as histórias de usuário com critérios de aceite em notação EARS

O design.md fica com a arquitetura técnica e o tasks.md com o plano de implementação em tarefas rastreáveis

Ou seja: a separação que eu falei lá no passo 2 (comportamento aqui, implementação ali) vem embutida na estrutura de pastas

Spec Kit: checklist como portão antes de implementar

O Spec Kit é o toolkit open source do GitHub pra Spec-Driven Development

Dá pra rodar sem instalação permanente via uvx:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Pra usar no diretório atual, é specify init .

Os comandos de barra usam o prefixo speckit e cobrem o processo de ponta a ponta: /speckit.constitution, /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.checklist, /speckit.tasks, /speckit.analyze, /speckit.implement e /speckit.converge

Dois deles interessam demais pra quem tá escrevendo critério

O /speckit.checklist gera listas de validação de qualidade por domínio (UX, segurança, testes, performance) que funcionam como "testes unitários para o inglês", com critérios objetivos e mensuráveis pra avaliar a qualidade da spec ANTES de gerar código

E o /speckit.implement executa as tarefas do tasks.md em ordem de dependência, mas antes de implementar ele lê o estado das caixas do checklist como portão: se tiver item não marcado, ele pergunta antes de seguir

Sacou o efeito? O checklist não marcado interrompe a implementação. É a spec virando portão de verdade, não sugestão

Tem mais dois gates úteis: o /speckit.clarify faz até cinco perguntas dirigidas sobre áreas mal especificadas e grava as respostas de volta no spec.md (dá pra rodar quantas vezes precisar antes do plano), e o /speckit.analyze detecta inconsistências entre spec, plano e tarefas antes de a implementação começar

Tome cuidado pra não achar que tudo é obrigatório: só o /speckit.specify é estritamente obrigatório antes do /speckit.plan, os outros três são portões de qualidade opcionais pra casos com ambiguidade relevante

Claude Code: plano editável antes de mexer no código

No Claude Code o caminho é o modo de planejamento

Tu aciona apertando Shift+Tab até a barra de status mostrar "plan mode on", ou já inicia a sessão com a flag:

claude --permission-mode plan

Nesse modo o Claude lê arquivos e responde perguntas sem fazer alterações

Ele faz perguntas de esclarecimento antes e monta um plan.md que você pode editar: Ctrl+G abre o plano no editor de texto pra edição direta

E é aí que teus critérios entram, escritos com a tua mão dentro do plano

Pra sair, tu aprova o plano ou aperta Shift+Tab, e a partir daí a execução é verificada contra o plano

A lógica é a mesma de escrever a spec antes de pedir o código: o artefato existe antes da primeira linha e serve de referência pra conferir o resultado

E de onde veio esse tal de EARS?

Já que a gente usou a notação o post inteiro, vale saber a origem

O EARS foi criado por Alistair Mavin e colegas na Rolls-Royce plc, durante a análise de regulamentos de aeronavegabilidade de um sistema de controle de motor a jato, e publicado na conferência IEEE RE’09 em 2009

Ou seja: nasceu num contexto onde requisito ambíguo tem consequência bem pior que sprint atrasada

E foi adotado por organizações como Airbus, Bosch, Dyson, Honeywell, Intel, NASA, Rolls-Royce e Siemens

Engraçado pensar que a mesma notação que passou por regulamento de motor a jato hoje tá dentro de um requirements.md gerado por IA, né? 😀

Conclusão

O que muda quando os critérios ficam verificáveis não é a quantidade de documento, é o STATUS dele

O SDD trata artefatos como spec, critérios de aceite e Definition of Done como autoritativos em vez de consultivos, e força o alinhamento por automação em vez de depender só de disciplina humana

Disciplina humana falha na sexta à tarde. Verificação automatizada não

O próximo passo é bem concreto: pega a próxima spec que tu for escrever, passa o olho em cada critério e faz o teste do verdadeiro/falso em cada linha

O que não passar, reescreve em Gherkin ou em EARS até virar condição, ação e consequência observável

Depois amarra cada critério a uma verificação que devolve passou ou falhou, e só então libera a implementação

A spec para de ser intenção e vira portão

até o próximo post!