O jeito comum de começar um app React é rodar um scaffolder (npm create vite) e sair digitando. O problema começa logo 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.
Comece pelo spec.md#
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: monta o projeto, gera os componentes tipados, liga o roteamento e rascunha 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, em vez de um diff em branco que está vendo pela primeira vez.
Essa revisão vale o tempo. 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, em vez de 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 força o pensamento difícil logo no começo, numa linguagem que dá pra revisar, em vez de deixá-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
Esses vêm do que o specify init registrou pro seu agente, então o prefixo exato pode variar por agente e versão do Spec Kit. Confira a lista de comandos do seu agente em vez de supor.
Esperado: você aprova em cada portão, primeiro 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.
Escrito por Wilian Revejes, engenheiro front-end (OTT / Smart TV & vídeo). Mais em /pt/cv.