Spec-driven development no Claude Code: como escrever a spec antes de mandar implementar

Fala aí, beleza? Modelo de código não erra por ser lento, ele erra por ser rápido demais implementando a coisa errada

Você joga um pedido vago no terminal, o agente entende alguma coisa parecida com o que você quis dizer, e devolve um monte de código plausível que resolve um problema vizinho do seu

Aí começa o vai e volta: revisa, explica de novo, refaz, e o token vai embora sem entregar nada

Spec-driven development é o contrário disso: você escreve a especificação ANTES de mandar implementar, e o agente executa contra um documento em vez de executar contra um palpite

Neste post eu mostro o que vai dentro dessa spec (objetivo, escopo, critérios de aceite e o que fica de fora), como rodar isso no Claude Code usando só o que existe de verdade na ferramenta, e como conferir a entrega contra o que foi combinado

Sem prompt mágico, beleza? Aqui é documento e disciplina 🙂

O que você precisa antes de começar

Nada exótico:

• Claude Code funcionando no terminal, aberto na pasta do projeto
• o projeto versionado em git, porque a revisão que eu mostro no final é feita em cima do diff, e porque você precisa conseguir desfazer sem drama
• um lugar pra escrever a spec em Markdown, pode ser um arquivo solto dentro do próprio repo
• uvx instalado, mas SÓ se você for pro Spec Kit lá no fim do post, ele é totalmente opcional

Sobre a memória do projeto: o CLAUDE.md é lido no início de toda sessão, e ele pode ficar como CLAUDE.md ou como .claude/CLAUDE.md dentro do diretório de trabalho

Se a regra tem que valer em todos os seus projetos, o lugar dela é ~/.claude/CLAUDE.md

Não tem versão mínima nem configuração especial pra seguir o método: spec é texto, o resto é o Claude Code que você já usa

O que colocar dentro da spec: escopo, critérios de aceite e o que fica fora

Essa é a parte que decide se o método funciona ou se vira teatro

Antes de sair escrevendo, uma definição rápida: a spec não é a documentação do projeto inteiro, ela é o contrato de UMA tarefa

Anatomia que eu uso:

1. Objetivo em uma frase: o quê e por quê, sem citar stack, sem citar arquivo (erro comum aqui: começar pelo "usar a biblioteca X", que é solução, não objetivo)
2. Escopo: a lista do que entra, em frases curtas, uma funcionalidade por linha
3. Fora de escopo: a lista explícita do que NÃO deve ser tocado nem inventado nessa tarefa, e é a seção que mais salva a revisão depois
4. Critérios de aceite verificáveis: frases testáveis, no formato "dado X, quando Y, então Z" (erro comum aqui: escrever adjetivo, tipo "a tela precisa ficar rápida e bonita", que ninguém consegue conferir)
5. Restrições e arquivos que podem ser tocados: quais pastas estão liberadas e o que não pode mudar de contrato, tipo rota, schema ou retorno de função

Um exemplo enxuto de spec de tarefa:

# Spec: exportar relatório em CSV

## Objetivo
Permitir que o usuário baixe o relatório que já vê na tela,
para trabalhar os dados fora do sistema.

## Escopo
- botão "Exportar CSV" no topo da tela de relatório
- exporta exatamente as linhas do filtro ativo
- nome do arquivo com a data do filtro

## Fora de escopo
- exportar em Excel ou PDF
- mudar as colunas do relatório
- qualquer alteração no schema do banco

## Critérios de aceite
- dado um filtro aplicado, quando eu clico em Exportar CSV,
  então o arquivo baixado tem a mesma contagem de linhas da tabela
- dado um relatório vazio, quando eu abro a tela,
  então o botão fica desabilitado
- o cabeçalho do CSV usa os mesmos rótulos das colunas da tela

## Restrições
- só mexer em src/reports/
- não alterar a assinatura de getReportRows()

Repara que dá pra ler cada critério e responder sim ou não olhando a tela, sem discussão

Spec da tarefa e CLAUDE.md são coisas diferentes:

Isso aqui confunde bastante gente

A spec é da tarefa, tem começo, meio e fim, e depois que a feature entrou ela vira histórico

O CLAUDE.md é a memória do projeto: comandos de build, convenções, layout do projeto e regras do tipo "sempre faça X", que valem pra qualquer tarefa

Pra criar essa base o Claude Code tem o comando embutido /init

E o /memory lista e abre os arquivos de memória (o CLAUDE.md, o CLAUDE.local.md e a pasta de memória automática) de dentro da própria sessão, sem você sair pro editor

A memória automática, aliás, fica em uma pasta por projeto, em ~/.claude/projects/<projeto>/memory/, e dá pra mudar esse local pela chave autoMemoryDirectory no settings.json

Tome cuidado com o tamanho! Arquivo de memória com mais de 200 linhas consome mais contexto e pode REDUZIR a aderência às instruções

Ou seja: empurrar a spec inteira pra dentro do CLAUDE.md é o jeito mais rápido de fazer o agente seguir menos, não mais

Do plano ao código: rodando a spec no modo plano do Claude Code

A Anthropic recomenda pro Claude Code um ciclo de quatro fases: explorar (em modo plano), planejar, codar e commitar, o famoso Explore > Plan > Code > Commit

O porquê é bem direto: deixar o Claude ir direto ao código tende a resolver o problema errado, e pesquisar e planejar antes melhora o resultado

Com uma spec na mão esse ciclo fica ainda mais confortável, porque a exploração já tem alvo. Se você nunca usou esse modo, eu destrinchei ele no post sobre planejar antes de executar mudanças

1. Entre no modo plano: o atalho Shift+Tab cicla entre os modos na ordem default > acceptEdits > plan, e a barra de status mostra ⏸ plan mode on quando ele está ativo
2. Aponte a spec e mande explorar: peça pro Claude ler o arquivo da spec e os arquivos citados nas restrições, mais nada, porque no modo plano ele só lê e propõe um plano, sem nenhuma edição em disco antes da sua aprovação
3. Responda as perguntas de esclarecimento: o modo plano faz perguntas antes de planejar, e é aqui que buraco de spec aparece (se ele perguntou, é porque faltou escrever)
4. Edite o plan.md: o modo plano gera um arquivo plan.md editável por você antes da execução, então corta o que fugiu do escopo e ajusta a ordem ali mesmo
5. Calibre o raciocínio quando a tarefa for cabeluda: as palavras de gatilho aumentam o orçamento de raciocínio estendido em ordem crescente, "think" < "think hard" < "think harder" < "ultrathink"
6. Só então libere o código: execute uma etapa por vez e confira antes de seguir pra próxima, em vez de soltar o plano inteiro de uma vez
7. Feche o ciclo commitando: com o diff limpo, dá pra criar commits e PRs pelo Claude Code sem sair do terminal

O erro comum deste ciclo: aprovar o plano no automático, sem cruzar item por item com os critérios de aceite e sem editar o plan.md

Se o plano já saiu fora do escopo, o código vai sair fora do escopo também, e aí não adianta culpar o modelo

Guardando o ritual da spec como skill:

Lá pelo terceiro projeto você percebe que digita sempre as mesmas instruções: leia a spec, respeite o fora de escopo, uma tarefa por vez

Dá pra guardar isso dentro do próprio Claude Code em vez de viver no copia e cola

O formato recomendado hoje é a skill: uma pasta com um arquivo SKILL.md dentro, em .claude/skills/<nome>/ quando é do projeto, ou em ~/.claude/skills/<nome>/ quando você quer ela valendo em todos

O SKILL.md é frontmatter YAML mais conteúdo Markdown, e você chama ela por /nome na sessão

"E os comandos de barra personalizados, que ficam em .claude/commands/ no projeto e em ~/.claude/commands/ pra todos os projetos?"

Eles funcionam e são invocados igualzinho, só que esse formato de pasta está marcado como legado, então pra coisa nova eu iria de skill

Detalhe massa: em sessão normal só a DESCRIÇÃO da skill entra no contexto, o corpo dela carrega quando você invoca

Ou seja: dá pra escrever o ritual com calma e detalhe sem pagar contexto por ele o tempo todo, diferente do CLAUDE.md, que é lido no início de toda sessão

E se você for separar papéis (um pra revisar, outro pra escrever spec), os subagentes personalizados moram em outra pasta: ./.claude/agents/ no projeto e ~/.claude/agents/ pra todos os projetos

Como revisar a saída contra a spec

Escrever a spec é metade. A outra metade é conferir a entrega contra ela, e essa parte quase ninguém faz direito

1. Releia os critérios de aceite um a um contra o diff: abra o git diff e vá marcando critério por critério, sem tratar o resumo do agente como laudo
2. Cheque a lista de fora de escopo: olhe os arquivos alterados e pergunte se algum deles estava marcado como intocável (erro comum aqui: aceitar a melhoria não pedida "já que ela veio junto", que é justamente o que a spec existe pra evitar)
3. Rode a camada extra: o Claude Code traz /review e /security-review embutidos, use como mais um par de olhos, nunca como veredito final
4. Teste na mão o que dá pra testar: critério bem escrito você confere sem discussão, critério vago você "acha" que passou

E aqui vai o limite que quase ninguém fala: as instruções do CLAUDE.md são orientativas e seguidas de forma probabilística, sem garantia de cumprimento estrito, ainda mais quando estão vagas ou brigando entre si

Fora isso, o Claude Code não traz detecção de drift nem verificação automática contra a spec

Quem confere se a entrega bate com o combinado é você, e é por isso que critério de aceite verificável vale mais que parágrafo bonito de contexto

O erro comum deste passo: perguntar pro próprio agente se ele cumpriu a spec e engolir o "sim, tudo implementado conforme especificado" como prova, sem ter critério objetivo na mão pra checar

O que muda na prática quando a spec vem antes

Eu montei um projeto inteiro com esse método pra gravar sobre SDD, e algumas coisas ficaram bem claras no caminho

A imagem que eu uso é a de um corpo sem cabeça: vibe coding sem especificação é isso, a ideia é boa, mas sem condução o projeto trava, não escala, e o consumo de token dispara na hora que uma funcionalidade nova obriga a mexer na regra de negócio

O SDD é uma baliza, um guard rail: você continua usando a sua ideia e os seus prompts, só que guiado pra não sair da curva

Sem spec, quem decide é a IA: ela escolhe a stack, planeja as features pela própria base de conhecimento e define o design do jeito dela, e aí sai aquele resultado colorido demais quando você queria uma coisa sóbria e premium

E quando NÃO vale a pena?

Pra aplicação simples e projeto pessoal, vibe coding solto ainda funciona, isso eu falo tranquilamente

A régua que eu uso é essa: se o projeto passa de uns três prompts, ou se envolve autenticação, pagamento, perfis de usuário (admin e comum) e dashboard, provavelmente vale parar e escrever

Os três documentos que eu monto:

O meu SDD é artesanal, feito na mão, não veio de framework nenhum, e ele se divide em requisitos, design e tarefas

No de requisitos eu escrevo a visão geral, detalho cada funcionalidade, listo as regras de negócio e os requisitos não funcionais e, importante, listo também o que o app NÃO faz (é essa lista que impede a IA de inventar)

No de design eu defino a stack, o que cada página faz e o esquema de banco de dados, e quanto mais descrito, melhor. Apesar do nome, design aqui não é só cor e estilo!

Se você não sabe tipar o banco, relaxa: mesmo sem saber se o campo é string ou datetime, o importante é definir quais dados vão ser salvos

No de tarefas eu defino a ordem de execução que faz sentido pela jornada do usuário: setup inicial, depois autenticação (que é complexa e vital), depois a funcionalidade central, depois o que depende de login (salvar, dashboard) e por fim um polimento

Uma recomendação: cocrie os documentos com a IA em vez de largar tudo na mão dela. O texto dela fica mais rígido que o de uma pessoa, então eu entro pelo menos na parte que eu conheço, ou seja, o que o app faz, as funcionalidades e a jornada do usuário

Como fica a execução:

Na demonstração eu escolhi de propósito uma stack padrão, dessas que as IAs dominam, pra reduzir erro, e aviso lá que o banco em arquivo que eu uso precisaria virar Postgres num projeto de verdade

Com os documentos prontos eu abro o agente de programação (serve qualquer um, eu fui de Claude Code por ser o que eu mais uso no momento) e a primeira coisa que eu peço é: leia os três documentos e gere um arquivo de contexto do projeto condensando tudo

Sem esse arquivo o conhecimento se perde quando você fecha a sessão, e o gasto de token sobe de novo

O prompt inicial vai com restrição explícita: ler os documentos antes de qualquer tarefa, seguir exatamente o que está escrito, não adicionar funcionalidade fora dos requisitos, não trocar a stack definida no design e executar uma tarefa por vez

Depois vira rotina: eu chamo a tarefa pelo número e peço pro agente PARAR ao terminar. Alguns modelos param sozinhos, mas eu prefiro ser explícito a implícito, aí garante

E a parte que mais me chamou atenção: os prompts ficam mais simples depois do planejamento. Você gasta mais tempo no começo, e a execução vira uma coisa previsível e sequencial, sem precisar caprichar em cada prompt como se fosse obra de arte

No vídeo abaixo eu mostro tudo isso em movimento: monto os três documentos e construo um gerador de QR code (sem login ele gera e baixa o código de texto, wi-fi e contato, e com login salva e gerencia os códigos criados), tarefa por tarefa, do setup até o gerador funcionando

Spec Kit: o fluxo formal de spec-driven development com o Claude Code

Se você prefere artefato padronizado no lugar do documento artesanal, existe caminho pronto

O Spec Kit é um toolkit open source do GitHub para spec-driven development, licença MIT, com uma CLI chamada specify, e ele lista o Claude Code entre os agentes suportados, junto do GitHub Copilot e do Gemini CLI

Ou seja: dá pra experimentar o fluxo formal sem trocar de ferramenta

A instalação e a inicialização saem em um comando só:

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

E dá pra já apontar o agente na criação do projeto:

specify init meu-projeto --ai claude

Com o projeto inicializado, a sequência do fluxo roda dentro do próprio agente:

1. /speckit.constitution: guarda os princípios e diretrizes que guiam todo o desenvolvimento seguinte
2. /speckit.specify: descreve o quê e o porquê do que você quer, e não a stack técnica (erro comum aqui: já sair escrevendo framework e biblioteca nesse passo)
3. /speckit.clarify
4. /speckit.plan
5. /speckit.checklist
6. /speckit.tasks: é o passo que produz o tasks.md completo
7. /speckit.analyze: aponta inconsistências, duplicações, ambiguidades e itens subespecificados entre os artefatos, e só roda depois que o tasks.md está completo (erro comum aqui: chamar o analyze antes de existir tasks.md, e ficar sem auditoria nenhuma)
8. /speckit.implement
9. /speckit.converge

Os três artefatos centrais são spec.md, plan.md e tasks.md, e é sobre eles que a auditoria cruzada acontece

Repara que a lógica é a mesma da spec artesanal: o quê e o porquê primeiro, quebra em tarefas depois, e uma checagem de coerência antes de mandar implementar

Muda o nível de formalidade, não muda a ideia

Quando escrever spec compensa (e quando é só burocracia)

Na feature nova, o ganho está no critério de aceite: você para de discutir se ficou bom e passa a conferir se bate

Na refatoração, o herói é o fora de escopo, porque o risco ali não é o agente fazer de menos, é ele fazer de mais e encostar em código que estava de pé

No ajuste de uma linha, escrever spec é burocracia pura, abre o modo plano, lê a proposta e segue a vida

Já no trabalho em equipe, a spec deixa de ser só instrução pro agente e vira documento de acordo entre pessoas, e é justamente aí que o formato padronizado do Spec Kit compensa o esforço extra

Conclusão

Spec-driven development não é um recurso do Claude Code, é uma disciplina

O que a ferramenta te dá são apoios: o modo plano pra ler e propor antes de editar qualquer coisa, o CLAUDE.md pra segurar as regras que valem sempre, a skill pra guardar o ritual da spec, e o Spec Kit se você quiser o fluxo formal com artefato padronizado

O que ela não te dá é garantia: não existe verificação automática contra a spec, então a conferência final continua sendo sua

Próximo passo, bem concreto: pega a próxima tarefa da tua fila, escreve a spec com objetivo, escopo, fora de escopo e critérios de aceite verificáveis, e roda o primeiro ciclo em modo plano antes de deixar qualquer edição acontecer

Depois compara com o teu jeito antigo de pedir e vê a diferença 😀

até o próximo post!