O que é spec-driven development e como isso muda o uso do Claude Code?

Fala aí, beleza? Existe uma diferença gigante entre a sessão de terminal que começa com "faz isso pra mim" e a sessão que começa com uma spec escrita

A primeira é rápida e às vezes resolve

A segunda é chata nos primeiros dez minutos e depois te devolve o tempo com juros

Spec-driven development é a sigla que apareceu justamente pra dar nome a esse segundo jeito de trabalhar, como resposta a um modo de falha que todo mundo que usa agente já viu de perto

Neste post eu te mostro de onde ela veio, o que ela muda na prática e onde exatamente ela encaixa numa sessão de Claude Code

De onde veio o SDD e por que ele apareceu agora

SDD emergiu em 2025 como reação ao modo de falha do vibe coding com LLM

E o modo de falha é bem conhecido: código plausível que desvia da intenção, API alucinada que não existe em lugar nenhum e uma saída que vai degradando conforme o projeto cresce

Repara que o problema não é o modelo escrever código ruim linha a linha

O problema é o modelo escrever código lindo pro pedido errado 😅

Em 2026 a ideia virou mainstream, e as principais ferramentas de coding com IA lançaram sua própria versão de SDD, incluindo GitHub Spec Kit, AWS Kiro, Claude Code, Cursor e OpenSpec

O que "spec versionada como fonte da verdade" significa na prática:

A definição da metodologia é essa: uma especificação executável e versionada, não o código, é a fonte única da verdade

A ordem de trabalho fica spec, plano, tarefas e só então código

Na prática isso quer dizer que a spec vive dentro do repositório, entra no commit e é revisada igual código é revisado

Se você conhece o hábito de revisar um PR antes do merge, é o mesmo hábito puxado uma casa pra trás: em vez de revisar o que foi feito, tu revisa o que vai ser feito

Pedido avulso x spec-driven development: qual é a diferença na prática

Repara que não é uma tabela de "bom x ruim"

É uma tabela de onde tu paga o preço

No pedido avulso o preço aparece no fim, quando o diff não é o que tu queria e não existe nenhum artefato pra apontar e dizer "olha, era isso aqui"

No SDD o preço aparece no começo, e o começo é bem mais barato de refazer

O que muda no Claude Code quando você trabalha por spec

Agora o que interessa: o que tu faz de diferente no terminal?

A boa notícia é que boa parte da mecânica já está lá dentro, tu só precisa parar de pular ela

Plan mode: separar o pensar do editar

O Claude Code tem um plan mode acionado por Shift+Tab até a barra de status mostrar o indicador ⏸ plan mode on, ou já iniciando a sessão com claude --permission-mode plan

Nesse modo o Claude explora o código e produz um plano sem editar arquivo

E aqui está o detalhe que faz o modo valer: ferramentas de leitura rodam normalmente, mas edições de arquivo nunca são auto-aprovadas, mesmo quando existe uma regra de permissão que daria match

Ou seja, é somente leitura pro código do projeto de verdade, não é promessa

Dentro do plan mode ele ainda pode usar o AskUserQuestion pra esclarecer requisito antes de fechar o plano

Isso é MUITO massa, porque é exatamente o momento em que a ambiguidade deveria morrer: antes do código, não depois

Com o plano na tela, o Ctrl+G abre ele no editor de texto pra tu editar direto

Aí é só aprovar o plano ou dar Shift+Tab pra sair, e o Claude codifica verificando contra o próprio plano

Se tu quiser ver esse hábito aplicado no detalhe, eu destrinchei em outro post como escrever a spec antes de implementar numa tarefa real

CLAUDE.md: o contexto que não some quando a sessão acaba

O CLAUDE.md é um arquivo markdown que dá instruções persistentes de projeto ao Claude Code, e ele é lido no início de toda sessão

E a leitura é recursiva: partindo do diretório atual, ele sobe até a raiz do sistema e lê todo CLAUDE.md ou CLAUDE.local.md que encontrar pelo caminho

Pra criar o primeiro, o comando é esse:

/init

O /init gera um CLAUDE.md inicial servindo de guia do projeto

É o pedaço mais barato do SDD: cinco minutos e tu para de repetir as mesmas três regras em toda sessão

O fluxo que a Anthropic recomenda

A Anthropic recomenda o fluxo explore, plan, code, commit

E afirma que os passos de pesquisa e planejamento antes do código melhoram significativamente o desempenho em problemas que exigem raciocínio mais profundo

Sem eles, o Claude tende a pular direto pra codificar

Sacou o encaixe? SDD não é um recurso novo que tu precisa instalar pra começar

É o nome da disciplina que faz esses passos deixarem de ser opcionais

Como montar um fluxo spec-driven com o Spec Kit e o Claude Code

Quando o hábito pega e tu quer artefato de verdade no repositório, entra o Spec Kit, um toolkit de spec-driven development mantido no repositório github/spec-kit, da própria GitHub

Ele é distribuído por dois canais oficiais: o repositório (instalação a partir do fonte) e o pacote specify-cli no PyPI

1. Instale a CLI

uv tool install specify-cli

Tem alternativa com pipx ou pip, e dá pra usar de forma pontual sem instalar nada:

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

O erro comum deste passo: instalar global sem precisar

Se tu só quer experimentar num projeto, o uvx resolve e não deixa sujeira

2. Inicialize o projeto apontando pro Claude Code

specify init meu-projeto --ai claude

A flag --ai claude é o que faz o toolkit se montar pro agente certo

O erro comum: inicializar sem a flag e depois ficar procurando os comandos que nunca foram gerados pro teu agente

3. Saiba onde os arquivos foram parar

A partir da versão 0.4.5 do Spec Kit, o specify init --ai claude instala os comandos speckit como skills nativas dentro de .claude/skills/

O erro comum: achar que não instalou nada porque tu procurou o arquivo no lugar errado

Abre a pasta e confere antes de xingar a ferramenta 😀

4. Comece pela constitution

O comando constitution define os princípios do projeto

É o pedaço que responde "como a gente escreve código aqui" antes de qualquer feature existir

O erro comum: pular direto pra feature e depois brigar com o agente sobre padrão de código em todo review

5. Escreva a spec com o specify

O specify é o o quê e o porquê, sem stack

Leia de novo: sem stack

O erro comum deste passo é justamente esse, cravar framework, banco e biblioteca já na spec

Quando tu faz isso, a decisão técnica entra sem discussão e a spec deixa de ser sobre a intenção

6. Passe pelo clarify

O clarify existe pra fechar as ambiguidades que sobraram

O erro comum: tratar como formalidade e sair batendo enter

Toda ambiguidade que sobrevive aqui vira retrabalho lá na frente, é quase uma lei

7. Gere o plano com o plan e o checklist

Agora sim é hora da decisão técnica: o plan é onde o como aparece, e o checklist amarra o que precisa estar coberto

O erro comum: aceitar o primeiro plano sem ler

Plano é texto, texto é barato de corrigir, código não

8. Quebre em tarefas com o tasks

O tasks transforma o plano em unidades de trabalho

O erro comum: tarefa gigante que não dá pra revisar sozinha

Se tu não consegue dizer se a tarefa terminou, ela está grande demais

9. Rode o analyze antes de implementar

O analyze checa a consistência entre os artefatos e roda depois do tasks e antes do implement

O erro comum é o mais caro de todos: pular o analyze e mandar implementar em cima de spec, plano e tarefas que discordam entre si

Aí tu não tem mais um agente confuso, tu tem três documentos brigando e um agente obedecendo o errado

10. Implemente e convirja

O implement executa as tarefas e o converge fecha o ciclo

O erro comum: sumir da frente do terminal achando que acabou o teu trabalho

Não acabou, e a próxima seção explica por quê

Quando o SDD compensa (e quando o pedido avulso continua sendo melhor)

A spec paga o custo dela em situações bem específicas

Feature que atravessa vários arquivos é a mais óbvia: quando a mudança encosta em cinco lugares, o plano vale mais que a pressa

Trabalho em equipe é a segunda: se a intenção precisa ser revisada por outra pessoa antes do código existir, tu precisa de um artefato, e chat não é artefato

Projeto que já cresceu é a terceira, porque é exatamente ali que a saída do agente começa a degradar, que é o modo de falha que deu origem ao SDD

E tem o contexto corporativo, onde isso já roda em produção

A Flowsource, plataforma de engenharia full-stack da Cognizant, usa o Claude Code no seu módulo de Spec-Driven Development, direcionando o agente pelas especificações, padrões de código e blueprints de arquitetura definidos pelo projeto e avaliando a saída antes da produção

Repara na última parte: avaliando a saída antes da produção

Nem lá a spec dispensa a avaliação

Agora o contraponto honesto, porque senão vira papo de vendedor

Ajuste pontual não pede cerimônia

Script curto de uma vez só também não

Exploração então muito menos: quando tu ainda não sabe o que quer, escrever spec é escrever ficção

O meio termo é bom de conhecer: até bug isolado às vezes ganha uma spec curta da correção quando a causa não é óbvia e a reprodução precisa ficar registrada

O limite que ninguém conta: spec não é garantia de obediência

E aqui vai o veredito honesto, porque essa parte quase nunca aparece nos posts empolgados

A documentação da Anthropic é clara: CLAUDE.md e a memória automática são tratados como contexto, não como configuração imposta

O conteúdo entra como mensagem de usuário depois do system prompt

O Claude lê e tenta seguir, mas não existe garantia de conformidade estrita, principalmente com instrução vaga ou conflitante

Ou seja, escrever "nunca faça X" no arquivo não é o mesmo que impedir X

Pra garantir bloqueio ou obrigação de ação, a própria documentação indica outro caminho: hook PreToolUse

Então o resumo sincero é esse

SDD reduz a deriva, dá ordem ao trabalho e deixa artefato revisável no repositório, que já é muita coisa

Mas o controle continua sendo humano

A spec melhora a chance, a revisão é que garante

Conclusão

Spec-driven development não é ferramenta, é mudança de hábito: a spec antes do código, e a spec versionada valendo mais que o histórico do chat

O próximo passo é barato e cabe hoje

Roda /init pra ter um CLAUDE.md no projeto

Na próxima tarefa de verdade, entra no plan mode com Shift+Tab antes de pedir qualquer edição e lê o plano inteiro

Só depois de sentir a diferença tu avalia se vale trazer o Spec Kit pro projeto

Se tu já tentou trabalhar assim e travou em algum ponto do fluxo, bora trocar uma ideia

até o próximo post!