Especificação mínima viável: o framework de 1 página que evita construir a Catedral antes da Cabana

Você recebe a demanda em três frases num Slack. Sai codando. Três semanas depois entrega uma feature que o cliente olha, franze a testa e diz "mas eu queria outra coisa". A culpa não é sua. Mas também não é só do cliente.

A culpa é da spec que ninguém escreveu. Ou pior — é da spec de 40 páginas que ninguém leu.

Tem um meio-termo. Ele cabe em uma página. E faz três coisas ao mesmo tempo: fecha escopo, vira combustível pra agente de IA, e protege o time de construir a Catedral antes de saber se a Cabana resolve.

TL;DR

• O que é: Especificação Mínima Viável (SMV) — template de 1 página com 5 campos que ancora qualquer entrega de software.
• Quando usar: sempre que o trabalho cabe em até uma sprint de 1 dev, ou quando você vai pedir pra um agente IA executar.
• Custo: zero. É processo, não ferramenta.
• Quando NÃO usar: decisão irreversível, múltiplos times no mesmo trecho, compliance pesado. Aí você precisa de PRD de verdade.

O problema é construir antes de decidir o que construir

Tem dois jeitos de matar um projeto antes do primeiro PR.

O primeiro é começar sem nada. Brief de WhatsApp, três bullets num e-mail, "faz um negócio que faz X". Dev abre o editor, começa pelo banco de dados, dois dias depois tem schema, controller, service, sete arquivos novos — e nenhuma das decisões foi conversada com quem pediu. Quando o cliente ver, vai mudar tudo. E aí você descobre que a Cabana que ele queria virou uma Catedral que ninguém pediu.

O segundo é o oposto. PRD de 40 páginas, BDD com 200 cenários, diagrama UML que envelhece antes do primeiro deploy. Aqui o problema não é falta de informação — é excesso. Ninguém lê. Ninguém atualiza. O documento vira teatro de processo.

A galera da Basecamp resolveu isso há anos com o conceito de appetite: você não estima quanto tempo um problema leva, você decide quanto tempo vale gastar nele e desenha a solução cabendo nessa caixa. O Shape Up formaliza isso em uma "pitch" com cinco partes — problema, apetite, solução, armadilhas e no-gos. Os no-gos são o que mais gente ignora e o que mais segura projeto.

A Amazon tem uma versão paralela: o PR/FAQ, um one-pager escrito como press release antes do produto existir. A regra interna é "horas, não dias" pra escrever a primeira versão. Se demora mais que isso, o problema não tá maduro o suficiente pra justificar código.

Hoje, com agente de IA no fluxo, o risco mudou de lugar. Antes, brief vago gerava semanas de trabalho perdido. Agora, brief vago gera vinte minutos de catedral pronta no Claude Code, com escolhas de arquitetura que ninguém validou e que vão custar mais pra desfazer do que pra reescrever do zero. A spec mínima virou requisito de sobrevivência.

O framework: 5 campos, 1 página

Esse é o template. Não tem versão longa. Se você precisa de mais, é outro documento.

# SMV: [nome do entregável]

## 1. Objetivo
Uma frase. Estado do mundo depois que isso entrar em produção.

## 2. Contexto
3–5 bullets do "porquê agora" e das restrições não óbvias do negócio.
Quem usa, quem paga, qual dor concreta isso fecha.

## 3. Restrições
Limites duros. Tempo, stack, dependências, custo, gente.
Se quebrar uma dessas, o projeto não cabe — renegocia escopo.

## 4. Critérios de aceite
Lista de comportamentos observáveis. Cada item é testável
manualmente em menos de 1 minuto, ou virou teste automatizado.

## 5. Anti-escopo
O que explicitamente NÃO entra nesta versão.
Inclui o que stakeholder vai assumir que entra. Seja específico.

Cinco campos. Um arquivo .md. Vai pra raiz do repo, ou pro topo do CLAUDE.md, ou cola no primeiro prompt do Claude Code. Vive ali e revisita a cada PR.

A pegada é cada campo ter um trabalho claro:

• Objetivo ancora o porquê. Quando alguém perguntar "por que estamos fazendo isso?", a resposta é uma frase. Se você não consegue resumir em uma frase, ainda não entendeu o pedido.
• Contexto é onde mora a informação que parece óbvia mas não é. "Esse fluxo é só pra cliente que já pagou" — isso é contexto. Se sai dali, vira bug em produção.
• Restrições transforma desejo em engenharia. "2 dias, 1 dev, stack Laravel, sem onboarding novo de fornecedor" é uma restrição. "Tem que ser performático" não é.
• Critérios de aceite é o contrato com quem pediu. Se o critério é vago, não é critério — é torcida.
• Anti-escopo é o campo que mais economiza tempo, e o que mais gente esquece. Você está dizendo "esse aqui eu vi, considerei, e decidi que NÃO faz parte". Isso fecha discussão antes dela acontecer.

Exemplo aplicado: comparador de preço por link

Pra não ficar abstrato, segue uma SMV real de um projeto que cabe em 2 dias:

# SMV: Comparador de preço por link de produto

## 1. Objetivo
Receber a URL de um produto em e-commerce, devolver até 5 alternativas
em outras lojas com preço, link e nota de confiança da correspondência.

## 2. Contexto
- Pessoa abre 6 abas pra comparar a mesma TV em Amazon, Magalu, Casas Bahia,
  Mercado Livre e Pichau. Quer ver tudo em uma tela.
- Caso real: time de compras corporativas faz isso na mão hoje, ~20min por item.
- App roda como ferramenta interna primeiro. Sem login, sem multi-tenant.

## 3. Restrições
- 1 dev, 2 dias úteis.
- Stack: Claude Code + Laravel + NativePHP (desktop app).
- Sem contratar API paga de scraping nesta versão. Usa o que dá pra fazer
  com requisição direta + parser HTML.

## 4. Critérios de aceite
- Dado link de TV em e-commerce conhecido, devolve 3 ou mais alternativas
  em até 30s.
- Cada alternativa exibe URL clicável, preço em BRL, nome do produto e
  score de match (0 a 100).
- Se um e-commerce falhar (timeout, bloqueio), o app devolve resultado parcial
  com aviso, não trava.
- Resultado é exibido em janela nativa (NativePHP), não no browser.

## 5. Anti-escopo
- Não rastreia histórico de preço.
- Não notifica queda de preço.
- Não compara especificações técnicas item-a-item (só preço + nome).
- Não suporta marketplaces internacionais (Amazon US, AliExpress).
- Não tem login, conta de usuário ou armazenamento de busca.
- Não é chatbot. Entrada é URL, saída é tabela.

Olha o que essa página faz: ela descarta umas seis features que iam aparecer em reunião ("e se a gente alertasse quando o preço cair?"), define o critério de "pronto" sem ambiguidade, e amarra a stack à restrição de tempo. Se aparecer pedido de marketplace internacional, a resposta é uma linha: "está no anti-escopo, vai pra v2".

Quando expandir — e quando NÃO expandir

A SMV não substitui PRD. Ela é o ponto de partida. Decisão simples:

Expanda quando:

• Múltiplos times tocam o mesmo trecho e precisam de contrato escrito.
• A decisão é irreversível (migração de banco grande, esquema de auth, mudança de billing).
• Tem dependência externa formal (compliance, integração paga, contrato com fornecedor).
• O custo de errar excede em muito o custo de especificar.

NÃO expanda quando:

• O escopo cabe em 1 sprint de 1 dev.
• A área é experimental — você ainda não sabe se vale a pena, e a aprendizagem vai mudar a spec.
• Você vai delegar a execução pra um agente IA. Spec curta + iteração rápida bate spec longa + execução tardia.
• Refazer custa menos que documentar.

A regra de bolso: se a SMV cabe em uma página e ninguém abre exceção, segue. Se três pessoas independentemente pedem mais detalhe no mesmo campo, é sinal de que esse campo precisa virar documento separado — mas mantém a SMV como índice.

A SMV como harness pra agente de IA

Aqui que a coisa fica interessante pra quem usa Claude Code, Cursor, Codex ou qualquer agente.

Agente sem spec é dev júnior com café demais: produtivo, criativo, e te entrega coisa que você não pediu. Spec curta resolve. Olha o mapeamento direto:

• Objetivo vira o "porquê" no system prompt. Reduz invenção de feature paralela.
• Restrições viram trilhos. "Não instale lib nova", "use só o que já tem no composer.json", "stack é Laravel + NativePHP" — o agente respeita se você falar.
• Critérios de aceite viram testes. O agente consegue escrever os próprios testes a partir desses critérios e rodar até passar.
• Anti-escopo é o campo que mais economiza token e mais evita rework. "Não escreva sistema de login", "não toque no schema de pagamento" — é instrução cara de descobrir depois e barata de declarar antes.

Esse é exatamente o tipo de harness que a gente vai destrinchar ao vivo no Harness Engineering com Claude Code, nos dias 16 e 17 de maio: dois dias, do zero, construindo o comparador de preço da SMV de cima — Claude Code + Laravel + NativePHP, com a stack rodando e a spec na mesa, não chatbot fofo de demo.

Limitações e pontos de atenção

A SMV não é mágica. Tem três jeitos de queimar com ela.

O primeiro é deixar critério de aceite vago. "Tem que ser rápido" não é critério, é desejo. "p95 de resposta abaixo de 800ms em payload de até 50KB" é critério. Se você não consegue medir, reescreve.

O segundo é tratar anti-escopo como letra morta. Anti-escopo só funciona se for revisitado a cada PR — quando o time encostar numa feature listada, alguém precisa lembrar que ela está fora. Coloque o arquivo no review automático ou no template de PR.

O terceiro é usar SMV em domínio errado. Sistema regulado (saúde, financeiro com auditoria, governamental) precisa de spec longa por exigência externa, não por capricho. Aí a SMV vira sumário executivo do PRD, não substituto.

FAQ rápido

SMV substitui PRD? Não. Substitui o vácuo. Em 80% das entregas de time pequeno, ela é suficiente. Nos 20% restantes, ela é o índice do PRD que vem depois.

E se faltar campo crítico? Adiciona uma linha. Não infla a página. Se você precisa de seção nova, é sinal de que o escopo cresceu além do que cabe em SMV — promova pra documento separado.

Como uso isso com Claude Code na prática? Cola a SMV no topo do CLAUDE.md do projeto, ou nos primeiros 30 linhas do prompt. Anti-escopo no topo. Critérios de aceite com pode/não pode. O agente respeita, e quando desviar, você cita a linha.

E se o cliente pedir mais durante a execução? Pra isso existe o anti-escopo. Pedido novo entra em "v2", não em "v1 inflada". Se for bloqueador real, renegocia o appetite primeiro — não enfia goela abaixo do mesmo prazo.

Conclusão

Spec longa não é sinal de senioridade. Spec curta que segura o projeto inteiro é.

A SMV é o documento mais caro de escrever no início — porque obriga você a tomar decisão antes de digitar código — e o mais barato de manter depois, porque cabe na cabeça do time. Se você ainda está despejando brief vago no Claude Code e rezando, troca por uma página com cinco campos. Vai descobrir que metade do que parecia "complicado" era só falta de fechar escopo.

A próxima Cabana sai mais rápida. E você só constrói a Catedral quando sabe que a Cabana já está cheia.