Como saber se a sua spec está boa antes de mandar a IA implementar?

Fala aí, beleza? Spec ruim não trava o modelo, e esse é exatamente o problema

Quando o requisito tem buraco, a IA não para pra perguntar

Ela preenche a lacuna com o palpite mais provável, escreve tudo bonitinho, e tu só descobre a besteira no code review

O ponto é que na maioria das vezes o culpado não é o modelo, é o documento que tu mandou pra ele. Um estudo acadêmico que mediu isso encontrou queda de desempenho superior a 30% na geração de código mesmo em modelos de ponta como o GPT-4 quando a especificação é ambígua

Então antes de gastar contexto mandando implementar, vale rodar uma régua no próprio texto

Bora ver como?

O que você precisa ter em mãos antes de revisar

Primeiro: o documento escrito, não a ideia na tua cabeça

Parece óbvio, mas é o erro número um. Spec que só existe na cabeça não pode ser auditada, porque tu vai ler o requisito e completar mentalmente o que faltou (o modelo não tem esse privilégio)

Segundo: a lista de requisitos separada do design técnico

Requisito é o QUE o sistema faz. Design é COMO. Quando os dois estão no mesmo parágrafo, tu não consegue testar nenhum dos dois, porque "salvar em Redis com TTL de 1h" esconde o requisito real (o que o usuário precisa que aconteça?)

Terceiro, e esse é o que mais gente pula: a revisão acontece ANTES do plano

O guia de Spec-Driven Development da Microsoft coloca revisão humana em cada fronteira de fase: a spec é revisada antes do plano, o plano antes das tarefas, e as tarefas antes da implementação

Ou seja, não é um portão só no fim, são quatro etapas com gente olhando no meio. Se tu quiser ver esse encadeamento aplicado na prática, dá uma olhada em como escrever a spec antes de implementar

Aqui a gente cuida da PRIMEIRA fronteira: a spec

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

A régua de revisão: 6 passos para auditar a própria spec

1. Reescreva cada requisito na estrutura EARS

EARS é a sigla de Easy Approach to Requirements Syntax, criado por Alistair Mavin e colegas na Rolls-Royce enquanto analisavam regulamentos de aeronavegabilidade de um sistema de controle de motor a jato, e publicado em 2009 na IEEE International Requirements Engineering Conference (a RE’09)

É gente escrevendo requisito pra coisa que voa, então o padrão é bem apertado 😀

A estrutura geral é essa:

WHILE <pré-condição opcional>, WHEN <gatilho opcional>, the <nome do sistema> SHALL <resposta do sistema>

E tem regra de composição pra conferir item por item: zero ou muitas pré-condições, zero ou um gatilho, exatamente um nome de sistema, e uma ou muitas respostas do sistema

É aqui que a spec começa a denunciar sozinha os defeitos. Se o teu requisito precisa de DOIS gatilhos, ele são dois requisitos disfarçados de um. Se ele não tem sistema nomeado, ninguém sabe quem responde

O erro comum deste passo: achar que reescrever em EARS valida o requisito. Não valida. EARS é disciplina de sintaxe de requisitos, padroniza COMO a frase é redigida, mas os critérios de aceite não rodam sozinhos

2. Classifique cada requisito no padrão básico correspondente

Os padrões básicos do EARS incluem o ubíquo (sem palavra-chave, o comportamento está sempre ativo), o dirigido a estado (palavra-chave While) e o dirigido a evento (palavra-chave When)

Exemplo de estado, tirado direto do material do EARS:

While there is no card in the ATM, the ATM shall display insert card to begin

E de evento:

When mute is selected, the laptop shall suppress all audio output

Agora o pulo do gato: passa a tua lista inteira e tenta encaixar cada linha em um dos três

O que não encaixa em nenhum é o teu requisito vago. Não é que ele seja "de outro tipo", é que ele ainda não é um requisito, é uma intenção

3. Teste a verificabilidade escrevendo a frase do teste

Pra cada requisito, escreve em uma linha o teste que o aprova

Se tu não consegue escrever essa frase, o requisito não existe ainda

"A tela deve carregar rápido" não gera frase de teste. "Quando o usuário abre o painel, o sistema deve renderizar a lista em até 2 segundos" gera

O erro comum deste passo: aceitar adjetivo no lugar de número. Intuitivo, robusto, performático, amigável: nenhum desses vira teste

4. Corte escopo exigindo rastreabilidade

Regra simples: toda tarefa tem que mapear de volta pra um requisito

Esse é o modelo que o Kiro usa nas specs dele: são três documentos por spec, um requirements.md com histórias de usuário e critérios de aceite em notação EARS, um design.md com a arquitetura técnica e um tasks.md com tarefas discretas sequenciadas por dependência, e cada tarefa é mapeada de volta a um requisito

Se uma tarefa não aponta pra lugar nenhum, ela é escopo inflado. Ela entrou porque pareceu boa ideia, não porque alguém pediu

O erro comum deste passo: inventar o requisito depois pra justificar a tarefa que tu já queria fazer haha (todo mundo já fez isso)

5. Rode uma rodada de perguntas nas áreas subespecificadas

O espírito aqui é o do comando /speckit.clarify, do Spec Kit: ele faz até cinco perguntas direcionadas sobre áreas subespecificadas da spec atual e grava as respostas de volta no spec.md

E o detalhe importante é que dá pra rodar várias vezes antes do planejamento, cada vez em uma área diferente

Mesmo sem usar a ferramenta, tu aplica o método: escolhe UMA área nebulosa, faz até cinco perguntas duras sobre ela, e escreve as respostas dentro do documento. Não no chat, no documento

6. Passe um checklist de qualidade por domínio

Última passada: UX, segurança, testes, performance, acessibilidade, um de cada vez, com critérios mensuráveis

O enquadramento que o /speckit.checklist usa pra isso é ótimo e vale roubar: checklists são "unit tests for English". Ele valida a qualidade, a clareza e a completude dos requisitos de um domínio, e NÃO se a implementação funciona

Sacou a diferença? Tu não está testando código aqui, tu está testando o texto

O erro comum deste passo: achar que listar todos os requisitos possíveis resolve. Uma pesquisa publicada no Findings of ACL 2026 observa justamente que especificar tudo não ajuda de forma consistente, porque os modelos têm capacidade limitada de seguir instruções e os requisitos podem conflitar entre si

E tem o dado que fecha o argumento: a mesma pesquisa mostra que prompts subespecificados têm o DOBRO de chance de regredir quando o modelo ou o prompt muda, com quedas de acurácia que passam de 20%

Então a régua não é sobre escrever MAIS, é sobre escrever verificável

Quatro sinais de que a spec vai falhar (e o que fazer com cada um)

Sinal 1: a mesma frase aceita duas implementações

Sintoma: tu lê o requisito, dois devs entendem coisas diferentes, e os dois estão "certos"

Causa: ambiguidade, e ela tem tipos catalogados. O benchmark Orchid, construído com requisitos ambíguos, tem 1.304 tarefas em nível de função cobrindo quatro tipos: léxica, sintática, semântica e vagueza

Correção: reescrever no padrão EARS, que força pré-condição, gatilho, sistema e resposta em posições fixas

Como prevenir: nunca aceitar requisito que não passa pelo passo 2 da régua

Sinal 2: requisito sem número

Sintoma: adjetivo fazendo o trabalho de métrica

Causa: o autor sabia o que queria e não traduziu pra critério mensurável

Correção: trocar o adjetivo pelo valor, pela unidade e pela condição em que ele vale

Como prevenir: o teste do passo 3, escrever a frase que aprova. Sem frase, sem requisito

Sinal 3: tarefa órfã

Sintoma: o tasks.md (ou a tua lista, tanto faz o nome) tem item que não rastreia pra requisito nenhum

Causa: escopo inflado, entrou pelo caminho do "já que estamos aqui"

Correção: ou nasce o requisito que justifica, ou a tarefa sai

Como prevenir: rastreabilidade obrigatória nos dois sentidos, requisito sem tarefa também é sinal (aí ele não vai ser implementado)

Sinal 4: nenhum critério de aceite

Sintoma: o modelo entrega algo plausível que ninguém pediu, porque ele inferiu o não dito

Causa: e olha que essa inferência funciona ÀS VEZES. A pesquisa do Findings of ACL 2026 mediu que os modelos conseguem inferir requisitos não declarados por padrão em 41,1% dos casos, mas descreve esse comportamento como frágil

Acertar em menos da metade das vezes não é base pra produção, né? É sorte com boa apresentação

E o efeito colateral já apareceu lá no passo 6: prompts subespecificados têm o DOBRO de chance de regredir quando o modelo ou o prompt muda, com quedas de acurácia que passam de 20%. Ou seja, funcionou hoje e quebra sozinho quando tu troca de versão

Correção: escrever o critério de aceite explícito, no formato do passo 1

Como prevenir: revisar na fronteira, antes de gastar contexto do modelo com implementação que vai voltar

Portões de qualidade: onde cada ferramenta entra na revisão

Cada ferramenta ataca uma parte diferente do problema, e misturar as três na cabeça é o que faz gente esperar de uma o que só a outra faz

O Spec Kit é um toolkit open source do GitHub para Spec-Driven Development, licenciado sob MIT, com uma CLI chamada specify (o repositório exibe 126 mil estrelas na própria página)

O fluxo dele é organizado em comandos de barra que produzem artefatos: /speckit.constitution gera o constitution.md, /speckit.specify gera o spec.md, /speckit.plan gera o plan.md e /speckit.tasks gera o tasks.md

E aqui tem uma distinção que vale ouro: clarify, checklist e analyze são quality gates OPCIONAIS. Apenas o /speckit.specify é estritamente obrigatório antes do /speckit.plan

O /speckit.analyze é o terceiro portão, o que ainda não tinha aparecido na régua: enquanto o checklist olha um domínio DENTRO de uma spec, ele faz a checagem de consistência ENTRE os artefatos, comparando spec, plano e tarefas entre si

No Claude Code, entra-se no plan mode pressionando Shift+Tab até a barra de status mostrar plan mode on, prefixando o prompt com /plan, ou iniciando a sessão com claude --permission-mode plan (o ciclo do Shift+Tab é default, acceptEdits, plan)

claude --permission-mode plan

E depois que o plano é proposto, dá pra pressionar Ctrl+G pra abrir o plano no editor de texto padrão e editar direto antes de o modelo seguir. Aprovar o plano sai do plan mode e muda a sessão pro modo de permissão da opção de aprovação que tu escolheu

Se a dúvida é se compensa esse passo extra, tem um post aqui sobre pedir um plano antes de implementar

Quando aplicar a régua inteira e quando a versão de cinco minutos

Rodar seis passos em toda mudança de uma linha seria masoquismo, então calibra assim:

Mudança pequena e reversível. Checa só dois passos: verificabilidade (o passo 3) e critério de aceite. Se tu consegue escrever a frase do teste e sabe o que aprova a entrega, manda ver

Feature nova com integração. Régua completa, sem pular o esclarecimento

E aqui a documentação de boas práticas do Claude Code é bem direta: ela recomenda usar plan mode em tarefas complexas justamente porque isso evita retrabalho caro quando a direção inicial está errada

Faz sentido, né? Errar a direção no parágrafo custa um parágrafo, errar a direção em 14 arquivos custa a tarde

Spec herdada de outra pessoa. Começa pela rodada de esclarecimento nas áreas subespecificadas, e repete em áreas DIFERENTES a cada rodada

Spec dos outros é traiçoeira porque o texto parece completo pra quem escreveu, o contexto que faltava estava na cabeça dele. Tome cuidado com o requisito que "parece claro": se tu não consegue escrever o teste dele no passo 3, ele não está claro, ele está familiar

O próximo passo

A ideia toda é essa: revisar a spec é mais barato que revisar o diff

No texto, o erro custa uma frase reescrita. No código, custa a implementação, o review, o retrabalho e o contexto queimado no meio

Então o próximo passo é bem concreto: pega a spec que tu tem aberta agora, roda os seis passos da régua nela (EARS, classificação, teste de verificabilidade, rastreabilidade, esclarecimento e checklist por domínio) e SÓ depois abre o planejamento

Se a spec passar, o modelo tem menos lacuna pra preencher por conta própria

E se não passar, melhor descobrir agora 🙂

até o próximo post!