# Como aplicar Spec Driven Development no Claude Code hoje

> Published 2026-10-11T13:55:36.198Z on https://www.crazystack.com.br/pt/p/como-aplicar-spec-driven-development-no-claude-code-hoje/
> Source video: https://www.youtube.com/watch?v=vG5iAakF4sM

Spec Driven Development é uma técnica de desenvolvimento com IA em que você escreve especificações detalhadas antes de qualquer código, e o agente implementa a partir delas. No vídeo do Felipe Rocha, de junho de 2026, ela aparece como o método que ele mais usa, apoiado pelo GitHub Spec Kit no Claude Code.

## O que é Spec Driven Development?

Spec Driven Development é uma técnica de desenvolvimento com IA em que você escreve e refina especificações antes de implementar, e o agente de IA gera o código a partir delas. A sigla em inglês significa desenvolvimento orientado a especificações, e a ideia central é simples: documentar deixa de ser consequência e vira o ponto de partida do projeto.

No vídeo do Felipe Rocha, publicado em junho de 2026 no canal Full Stack Club, a técnica aparece como a que ele mais usa no dia a dia, aplicada em projetos pessoais e na empresa onde trabalha. Segundo o apresentador, empresas no exterior vêm adotando o método com frequência crescente, um relato de experiência dele e não uma métrica de mercado verificada.

A lógica por trás do spec driven development é a inversão da proporção clássica. Antes da IA, era comum gastar horas programando e minutos documentando; hoje, com agentes como o [Claude Code](https://claude.com/claude-code), da Anthropic, escrevendo código em poucos minutos, o esforço do dev migra para a arquitetura: entender o problema, estruturar a solução e guiar o agente.

## Por que a IA mudou o papel de quem programa?

A escrita de código ficou tão rápida com IA que o gargalo do desenvolvimento se deslocou para o desenho da solução. Esse é o argumento central do vídeo: quando implementar custa minutos, o trabalho valioso é decidir o que construir e por quê.

Antes do [Claude Code](https://claude.com/claude-code) e de editores como o [Cursor](https://cursor.com), muita regra de negócio ficava presa apenas no código. Times pequenos, com orçamento apertado, raramente documentavam o suficiente, e o conhecimento vivia na cabeça de quem escreveu aquela função três anos atrás.

Com agentes de IA, esse cenário inverte. O dev assume o papel de arquiteto de software: levanta requisitos, define restrições técnicas e delega a implementação. As especificações passam a ser o ativo principal do projeto, porque é delas que o código nasce. Quem pula essa etapa recebe código rápido, porém sem rastro de decisão.

## Quais documentos compõem uma especificação?

Três documentos formam a base do fluxo, normalmente em arquivos markdown porque agentes de IA lidam bem com esse formato. Cada um responde a uma pergunta diferente, e confundir os papéis deles compromete o resultado.

### PRD: requisitos funcionais

A PRD descreve o que a aplicação deve fazer, em nível de produto, sem citar tecnologia. Uma user story típica seria: eu como usuário devo conseguir adicionar um produto ao carrinho, com regras como impedir a adição de itens sem estoque. O formato de user stories com cenários de aceitação casa muito bem com essa etapa.

### Tech spec: decisões técnicas

A especificação técnica nasce a partir da PRD e registra as escolhas de implementação: qual banco usar, qual biblioteca gerencia formulários, qual tabela será criada e com quais campos. A regra é que nenhum detalhe técnico pode contrariar os requisitos funcionais; a spec existe para servi-los.

### Tarefas: o passo a passo de execução

A lista de tarefas é opcional, mas recomendada no vídeo. Ela decompõe a implementação em passos ordenados: criar o cart provider, montar o cart drawer, adicionar o botão de compra e assim por diante. Cada tarefa cumpre uma user story respeitando a tech spec.

## Como o GitHub Spec Kit organiza o fluxo?

O [GitHub Spec Kit](https://github.com/github/spec-kit), toolkit lançado pelo GitHub em 2025, padroniza esse processo dentro de agentes como Claude Code e [OpenCode](https://opencode.ai). No vídeo de junho de 2026, Felipe Rocha cita mais de 100 mil estrelas no repositório como sinal de adoção; esse número é do relato dele e muda com o tempo, então confira a página atual do projeto.

A instalação é um único comando no terminal do seu agente, apontando qual ferramenta você usa. A partir daí, o Spec Kit cria uma pasta `.specify` no projeto com scripts, templates e skills próprias para cada etapa.

Cada comando do toolkit corresponde a uma etapa do spec driven development, e a ordem importa: a saída de um alimenta o próximo. A tabela abaixo resume o ciclo completo.

| Comando | O que produz | Momento |
| --- | --- | --- |
| `constitution` | Regras permanentes que o agente sempre segue | Antes de tudo |
| `specify` | Spec da feature com user stories | Início de cada feature |
| `clarify` | Perguntas que refinam a PRD | Após a spec inicial |
| `plan` | Tech spec, research.md, data-model.md | Após revisar a PRD |
| `tasks` | tasks.md com fases e tarefas | Após o plano |
| `analyze` | Verificação de coerência com a constituição | Antes de implementar |
| `implement` | Código executado por fase | Por último |

## Como rodar o passo a passo no Claude Code?

O ciclo completo tem sete comandos, executados em sequência dentro do terminal do seu agente. O roteiro abaixo segue a ordem mostrada no vídeo, com as boas práticas que o autor recomenda em cada etapa.

1. Rode `specify init . --ai claude` na raiz do projeto para inicializar o Spec Kit. Ele cria a pasta `.specify` com scripts e templates, e a pasta de comandos com as skills de spec, plan, tasks, analyze, clarify e checklist.

2. Rode `/spekit.constitution` passando o seu arquivo Claude.md. Isso gera um conjunto de regras que o agente respeitará ao criar PRDs, specs, tarefas e ao executar código.

3. Rode o comando de specify descrevendo a feature em nível funcional: o que a plataforma deve permitir ao usuário, sem citar React, banco ou biblioteca. Uma spec por feature é a granularidade recomendada.

4. Rode `/clarify` para o agente interrogar pontos que você não especificou. Ele registra cada resposta na própria spec, refinando o documento antes do plano.

5. Rode `/plan` informando as escolhas técnicas: Postgres como banco, React Hook Form para formulários, TanStack Query para chamadas no frontend. O agente gera arquivos como data-model.md, research.md e quickstart.md.

6. Rode o comando de tasks para gerar tasks.md dividido em fases. Executar uma fase por agente evita inflar a janela de contexto e degradar o resultado.

7. Antes de codar, rode `/analyze` para conferir divergências entre tarefas e constituição. Depois, use o comando de implementação, delimitando as fases: implement from phase 1 to phase 3, limpe o contexto e siga para as demais.

## Vale a pena revisar documentos antes de codar?

Sim, e essa é a disciplina que separa bons resultados de resultados medíocres no spec driven development. Revisar uma PRD de trinta minutos evita horas de refatoração depois, porque o erro capturado no documento custa uma edição; capturado no código, custa implementação inteira.

O autor recomenda revisar a saída de cada comando: a spec após o specify, as respostas após o clarify, os arquivos técnicos após o plan e as fases após o tasks. O arquivo research.md merece atenção especial, pois registra as pesquisas que embasaram decisões, como escolher entre uma fila no próprio processo Node ou uma ferramenta dedicada.

Outra dica prática do vídeo: escrever especificações em português consome mais tokens do que em inglês. O autor promete tratar do tema em outro vídeo, então teste os dois caminhos no seu projeto e meça o impacto no custo.

Vale lembrar que criadores brasileiros como o Gustavo Dev Doido, do Bootcamp do Dev Doido, e materiais como o Crazystack Typescript (veja em [crazystack.com.br](https://crazystack.com.br)) também cobrem IA no fluxo de desenvolvimento, o que mostra o quanto o tema ganhou espaço no ecossistema nacional.

## Perguntas frequentes sobre Spec Driven Development

- **Spec Driven Development serve para projetos pequenos?** Sim, embora o ganho apareça mais claramente em features com várias regras de negócio. Em algo muito simples, criar três documentos pode pesar mais do que o próprio código, então use bom senso na granularidade das specs.

- **Preciso do Claude Code para usar o GitHub Spec Kit?** Não. O Spec Kit funciona com diferentes agentes, e o próprio comando de inicialização aceita indicar qual ferramenta você usa, como OpenCode ou Codex. A escolha do agente não muda a sequência de comandos.

- **A lista de tarefas é obrigatória?** Não, é opcional segundo o fluxo mostrado no vídeo. Ainda assim, o autor recomenda usar, porque as fases permitem executar a implementação em blocos, limpando o contexto entre elas para preservar a qualidade do resultado.

- **Escrever specs em português é um problema?** Funciona, mas o autor relata que consome mais tokens do que escrever em inglês. Se o custo importa no seu projeto, compare os dois idiomas antes de padronizar a documentação da equipe.

## Do vídeo bem gravado ao artigo bem escrito

Se a tese deste artigo faz sentido, documentar antes de produzir vale para conteúdo tanto quanto para código. Muita gente que grava vídeos sobre técnica, arquitetura ou experiência de desenvolvimento tem conhecimento valioso preso dentro de um arquivo de YouTube, sem versão escrita que um leitor possa buscar e citar.

O [Skala Blog](https://skalablog.com) resolve exatamente isso: você cola a URL do vídeo, a transcrição é gerada e vira um artigo estruturado, pronto para revisar e publicar. Do mesmo jeito que a especificação guia o agente de código, a sua fala guiada por um bom roteiro vira texto com a sua assinatura.

[Source video](https://www.youtube.com/watch?v=vG5iAakF4sM)