O jeito comum de começar um app React é rodar um scaffolder — npm create vite — e sair digitando. O problema não é o scaffolder; é o que vem depois. A intenção vive na sua cabeça ou num ticket, o código vira o único artefato durável, e três semanas depois ninguém sabe dizer o que a coisa deveria fazer.
Spec-driven development (SDD) inverte isso. Você escreve a spec primeiro — a intenção, os requisitos, os critérios de aceite — e a trata como a fonte da verdade. O código é gerado a partir dela e mantido em sincronia. A ideia não é nova, mas os agentes de código a tornaram prática: uma boa spec agora é algo que um agente consegue de fato transformar num scaffold funcionando.
O que você escreve é a spec, não o App.tsx
Em vez de abrir um App.tsx em branco, você abre um spec.md:
# Feature: Buscas salvas ## Intenção Deixar um usuário logado salvar uma busca e re-executá-la depois. ## Requisitos - Um botão "Salvar busca" na página de resultados, desabilitado quando a query está vazia. - Buscas salvas ficam em /buscas, mais recentes primeiro. - Re-executar uma busca salva restaura a query e os filtros exatos. ## Aceite - Salvar uma query vazia é impossível (botão desabilitado e guardado). - Uma busca salva sobrevive a um reload completo da página. - Apagar uma pede confirmação.
Esse é o código que você revisa. É curto, em linguagem simples, e é a parte que de fato decide se a feature está certa.
O loop: specify → plan → tasks → implement
Ferramentas como o Spec Kit do GitHub formalizam isso em quatro passos. Você especifica a intenção (acima); o agente planeja a abordagem técnica (Vite + React Router, um modelo SavedSearch tipado, persistência local); quebra em tarefas; e então implementa — montando o projeto, gerando os componentes tipados, ligando o roteamento e rascunhando testes a partir dos critérios de aceite.
Você fica no loop em cada portão: revisa o plano antes de qualquer código existir, e revisa o código contra uma spec que você já concordou — não contra um diff em branco que está vendo pela primeira vez.
Essa revisão não é cosmética. Quando rodei isto, o plano assumiu localStorage por padrão — ok pra uma demo, errado pra um usuário logado cujas buscas salvas deviam segui-lo entre dispositivos. Peguei no portão do plano, não num code review três dias depois: uma linha adicionada à spec — as buscas são por conta, persistidas no servidor — um re-run, e a versão errada nunca chegou a ser escrita.
Por que combina tão bem com scaffolding de React
A maior parte do trabalho de subir uma feature React é mecânica: boilerplate, roteamento, tipos de prop, estados de loading e erro, setup de teste. É exatamente o trabalho que agentes fazem bem e humanos fazem com tédio. SDD move sua atenção pra parte em que máquinas são ruins — decidir o que construir e o que significa "pronto".
A pegadinha, e a parte sênior: a spec é o novo gargalo. Uma spec vaga gera código vago, com confiança — o Spec Kit até tem um passo de clarify que interroga uma spec magra antes de planejar, um bom indício de onde o trabalho real está. SDD não tira o pensamento difícil — ele força você a fazê-lo antes, numa linguagem que dá pra revisar, em vez de fazê-lo aflorar no meio da implementação. Ficar bom nisso é, na maior parte, ficar bom em saber o que especificar.
Experimente
O Spec Kit roda com uv. Três passos levam do zero a um scaffold que você conduziu a partir de uma spec.
1. Instale a CLI. Isto puxa o build atual direto do repositório — adicione @vX.Y.Z (uma tag da página de Releases) pra fixar uma versão específica:
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git specify --version
Esperado: specify no seu PATH, imprimindo a versão.
2. Crie um projeto ligado ao seu agente de código:
specify init buscas-salvas
Esperado: um novo diretório buscas-salvas/, e os comandos /speckit.* registrados para o agente que você escolher quando ele perguntar.
3. Conduza o loop dentro do seu agente — cole o spec.md acima como o primeiro passo:
/speckit.specify # transforma a spec num doc de spec formal /speckit.clarify # ele pergunta sobre o que estiver subespecificado /speckit.plan # abordagem técnica — revise antes de qualquer código /speckit.tasks # uma quebra em tarefas /speckit.implement # ele constrói o scaffold, tarefa por tarefa
O prefixo exato depende do agente que você escolheu: Copilot e Cursor usam o /speckit.specify com ponto; o Claude Code registra eles como skills /speckit-specify com hífen.
Esperado: você aprova em cada portão — o plano antes de existir uma linha de código, depois o código contra a spec que você já aprovou. Esse é o ponto inteiro.