Spec-Kit: Como usar especificações para gerar código com IA

Você prompta um assistente de IA. Ele gera código. Você testa. Algo quebra. Você prompta de novo. Mais código. Mais bugs. Três horas depois, você está depurando uma bagunça emaranhada que mal lembra o que você queria originalmente.

Já aconteceu com você?

O custo oculto do "Vibe Coding"

Os números: um estudo da Uplevel descobriu que usar o GitHub Copilot introduziu 41% mais bugs nas bases de código. A pesquisa de 2024 da Apiiro revelou que código gerado por IA introduziu 322% mais caminhos de escalação de privilégio e 153% mais falhas de design em comparação com código escrito por humanos.

E tem coisa pior: um estudo de Stanford publicado no ACM CCS '23 concluiu que desenvolvedores com acesso a assistentes de IA escreveram código significativamente menos seguro, e ao mesmo tempo ficaram mais confiantes na segurança do que produziam. A combinação perigosa de resultado pior com confiança inflada.

O pior de tudo? Desenvolvedores consistentemente superestimam o impacto da IA na sua produtividade em quase 40 pontos percentuais. A gente sente que está sendo mais produtivo enquanto, na prática, está entregando software pior.

Esse é o "problema dos 70%": a IA chega aos 70% do caminho com uma velocidade surpreendente, mas aqueles últimos 30%, a parte que deixa o software pronto pra produção e fácil de manter, viram um exercício de retornos decrescentes.

Cada nova iteração de código gerado por IA acaba menos consistente. Partes diferentes da base de código desenvolvidas com prompts diferentes começam a entrar em conflito. Depurar se torna tão custoso que muitas vezes é mais fácil reescrever tudo do zero do que tentar consertar.

Por que isso continua acontecendo

A causa raiz não é a IA — é a forma como estamos usando.

Quando você vai direto para os prompts sem especificações claras, está essencialmente pedindo para uma IA adivinhar o que está na sua cabeça. Ela não consegue. Então ela chuta. E cada chute se acumula em mais chutes, criando uma cascata de suposições que se afastam cada vez mais da sua intenção real.

O desenvolvimento tradicional reconheceu esse problema décadas atrás. Por isso temos PRDs, especificações técnicas e documentos de design. Mas esses artefatos viraram burocracia — criados uma vez e esquecidos enquanto o código seguia a vida própria.

E se houvesse uma forma de fazer as especificações realmente importarem? De torná-las tão precisas que a IA conseguisse traduzi-las de forma confiável em código funcional?

Conheça o Spec-Driven Development

Spec-Kit é um toolkit open-source do GitHub que implementa o Spec-Driven Development (SDD), uma abordagem que inverte a estrutura de poder tradicional entre especificações e código.

No desenvolvimento convencional, o código é o rei. As especificações apenas o orientam. No SDD, as especificações são soberanas, e o código as serve.

A transformação é fundamental: PRDs e planos técnicos fazem mais do que guiar a implementação: eles a geram. O que poderia levar dias de reuniões se torna horas de trabalho focado em especificação. E como as specs são precisas o suficiente para a IA executar, elas permanecem como a única fonte da verdade.

Não se trata de desacelerar para escrever mais documentação. Trata-se de antecipar o pensamento para que a IA consiga fazer a tradução mecânica com precisão.

Como o Spec-Kit funciona

O Spec-Kit estrutura o desenvolvimento em seis fases, cada uma com um slash command dedicado que funciona com o seu assistente de código com IA:

Fase 1: Constituição

Antes de escrever qualquer código, estabeleça os princípios fundamentais do seu projeto com /speckit.constitution.

Isso cria o seu "Gate Fase -1" — decisões arquiteturais que devem ser respeitadas durante todo o desenvolvimento:

• Padrões de qualidade de código
• Requisitos de testes
• Regras de consistência de UX
• Limites de performance

Pense nisso como programar o julgamento da IA antes que ela escreva uma única linha.

Fase 2: Especificar

Use /speckit.specify para descrever o que você quer construir e por que — sem mencionar tecnologia:

"Construa uma aplicação que me ajude a organizar fotos em álbuns separados. Os usuários devem conseguir criar álbuns, adicionar fotos e compartilhar álbuns com amigos."

Isso te força a pensar nas necessidades do usuário, não nos detalhes de implementação. A IA não vai otimizar prematuramente para um framework ou padrão específico.

Fase 3: Clarificar

Execute /speckit.clarify para eliminar ambiguidades. A IA faz perguntas investigativas sobre casos extremos, fluxos de usuário e requisitos que você pode ter deixado passar.

É aqui que a maioria dos projetos de "vibe coding" falha. Sem clarificação explícita, a IA preenche as lacunas com suposições. Com o Spec-Kit, cada suposição vira uma decisão explícita que você toma.

Fase 4: Planejar

Agora defina sua abordagem técnica com /speckit.plan:

"Use Vite com HTML, CSS e JavaScript vanilla. Minimize dependências. Armazene dados no IndexedDB para suporte offline."

Cada escolha técnica ganha uma justificativa documentada. Quando você revisitar o projeto daqui a seis meses, vai saber o porquê de cada decisão — não apenas o quê.

Fase 5: Tarefas

/speckit.tasks gera uma lista de tarefas acionável organizada por histórias de usuário, com:

• Dependências claras entre tarefas
• Marcadores de execução paralela [P] para tarefas que podem rodar simultaneamente
• Critérios de aceite para cada tarefa

Esse é o seu roteiro executável.

Fase 6: Implementar

Por fim, /speckit.implement executa todas as tarefas automaticamente, seguindo a ordem e as restrições que você definiu.

A IA não está mais chutando. Ela está traduzindo especificações precisas em código, o trabalho mecânico no qual ela realmente se destaca.

Impacto no mundo real

Imagine construir um sistema de chat em tempo real com histórico de mensagens e indicadores de presença.

Abordagem tradicional com IA:

1. Promptar para funcionalidade básica de chat (30 min)
2. Depurar problemas de WebSocket (1 hora)
3. Perceber que o histórico de mensagens não foi especificado (30 min)
4. Promptar para integração com banco de dados (1 hora)
5. Corrigir conflitos entre o código de chat e o de histórico (2 horas)
6. Adicionar indicadores de presença (1 hora)
7. Refatorar porque os componentes não se encaixam (3 horas)
8. Escrever testes para a bagunça (2 horas)

Total: ~11 horas de trabalho fragmentado com qualidade de código inconsistente.

Abordagem com Spec-Kit:

/speckit.specify Real-time chat with history and presence
/speckit.clarify
/speckit.plan WebSocket, PostgreSQL, Redis
/speckit.tasks
/speckit.implement

Total: ~45 minutos incluindo o tempo de especificação, com:

• Contratos de API completos antes da implementação
• Modelos de dados projetados para todas as funcionalidades
• Cenários de teste cobrindo casos extremos
• Arquitetura consistente do início ao fim

Mais do que velocidade, o ganho é coerência. Cada componente conhece todos os outros desde o início.

Os nove artigos constitucionais

A constituição padrão do Spec-Kit aplica princípios de engenharia testados em produção:

Você pode personalizar esses artigos para as necessidades específicas do seu projeto, mas os padrões representam sabedoria conquistada à duras penas em sistemas de produção.

Como começar

Pré-requisitos

• Linux, macOS ou Windows
• uv (gerenciador de pacotes Python rápido)
• Python 3.11+
• Git
• Qualquer assistente de código com IA compatível

Instalação

Instalação permanente (recomendada):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init my-project
specify check

Uso pontual:

uvx --from git+https://github.com/github/spec-kit.git specify init my-project

Assistentes de IA compatíveis

O Spec-Kit funciona com a maioria das principais ferramentas:

• Claude Code
• GitHub Copilot
• Gemini CLI
• Cursor
• Windsurf
• Qwen Code
• Roo Code
• Amp
• E muito mais

Quando usar o Spec-Driven Development

O SDD brilha para:

• Projetos greenfield onde você está definindo a arquitetura do zero
• Features complexas que exigem múltiplos componentes integrados
• Projetos em equipe onde alinhamento evita mal-entendidos custosos
• Prototipação rápida que precisa se tornar código de produção
• Modernização de sistemas legados onde documentar a intenção previne regressões

Pule o SDD para:

• Correções rápidas de bugs com soluções óbvias
• Ajustes menores de UI
• Código verdadeiramente exploratório onde você ainda está descobrindo os requisitos

A mudança fundamental

O Spec-Driven Development não substitui desenvolvedores nem automatiza criatividade. Ele amplifica a capacidade humana ao automatizar a tradução mecânica da intenção em implementação.

Assistentes de código com IA são como ter um desenvolvedor júnior muito animado no time. Eles escrevem código rápido, mas precisam de supervisão constante. Quanto mais claramente você especifica o que quer, melhor eles performam.

O Spec-Kit oferece uma forma estruturada de ser claro. Em vez de torcer para que a IA entenda seu prompt vago, você elimina sistematicamente a ambiguidade antes de a geração começar.

O resultado: código que realmente corresponde ao que você pretendia, produzido mais rápido do que o desenvolvimento tradicional, com menos bugs do que a assistência de IA desestruturada.

Pronto para parar de vibe coding e começar a construir software que corresponde às suas intenções? Confira o repositório do Spec-Kit e leia a metodologia completa do Spec-Driven Development.