Spec-driven development na prática: como escrever sua primeira spec do zero

Fala aí, beleza? Tu pede uma funcionalidade pro agente, ele responde rápido, o código até roda… e não é aquilo que tu queria

Perto, mas errado

E quase nunca é o modelo que falhou, é a especificação que nunca existiu

O spec-driven development inverte a ordem: primeiro a spec, depois o código, que nasce dela

A ideia deste tutorial não é teoria, é artefato: no final você sai com uma spec escrita, as tarefas quebradas e o resultado validado, usando o Spec Kit, toolkit open source mantido pela GitHub sob licença MIT pra construir software com qualquer agente de IA de código

Bora ver na prática? 🙂

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O que você precisa antes de escrever a primeira spec

A lista é curta e vale conferir antes de sair digitando comando:

• uv instalado
• Python 3.11 ou superior
• Git
• um agente de código instalado

Sobre o agente: o Spec Kit funciona com mais de 30 integrações, entre CLIs e assistentes que moram dentro da IDE, e o Claude Code está entre elas

Então não precisa trocar de ferramenta pra experimentar o método, tu usa o que já usa hoje

Aviso de versão (esse aqui salva tua tarde):

A versão mais recente do Spec Kit é a v0.12.4, publicada em 6 de julho de 2026

E a antiga família de flags --ai foi removida na v0.10.0, substituída pelo sistema de --integration

Ou seja: tutorial anterior a junho de 2026 mostra comando que simplesmente não roda mais

Se tu copiar um passo de um post velho e vier erro de flag desconhecida, é isso, não é a tua máquina 😀

Passo a passo: da ideia à primeira spec escrita

A lógica do fluxo é sempre a mesma: Spec, Plan, Tasks, Implement

Cada comando gera um arquivo, e os arquivos ficam versionados na pasta da funcionalidade, em specs/###-nome-da-feature/

Escolhe uma funcionalidade PEQUENA pra fazer esse ciclo pela primeira vez, tipo um gerador de QR code numa página, não o app inteiro

1. Iniciar o projeto e escolher o agente

O uso pontual, sem instalação permanente, é feito com uvx apontando pro repositório:

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

Se tu já está dentro da pasta do projeto e não quer criar uma pasta nova, usa o ponto no lugar do nome:

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

E a escolha do agente é feita pela flag --integration:

specify init <project_name> --integration claude

O erro comum deste passo: copiar a flag --ai de tutorial antigo

Ela foi removida na v0.10.0, hoje é --integration

2. Gravar os princípios do projeto com /speckit.constitution

/speckit.constitution

Esse comando grava os princípios inegociáveis do projeto em um arquivo versionado: .specify/memory/constitution.md

Pensa nele como a regra da casa, aquilo que vale pra qualquer funcionalidade que entrar depois

Se você já conhece um arquivo de convenções do time, é bem parecido, só que o agente lê antes de propor qualquer coisa

3. Escrever a spec da funcionalidade com /speckit.specify

/speckit.specify

Ele cria a especificação da funcionalidade e faz perguntas dirigidas sobre o que ficou subespecificado, incorporando as tuas respostas na spec

Aqui é O QUE o software faz e por quê, no nível de quem vai usar

O erro comum deste passo: responder vago

Se tu escrever "tem que ser rápido" e "o usuário faz login", a ambiguidade entra no artefato e sai do outro lado como código chutado

Resposta específica agora custa 30 segundos, resposta vaga custa uma refatoração depois

4. Fechar as brechas com /speckit.clarify

/speckit.clarify

Esse é o passo que a galera pula e depois reclama do resultado

Ele faz uma varredura estruturada de ambiguidades e apresenta até 5 perguntas dirigidas, uma de cada vez

Uma de cada vez é bom: tu pensa em cada decisão em vez de despachar um bloco de respostas no automático

5. Só agora decidir stack e arquitetura, no /speckit.plan

/speckit.plan

O plano é onde entra o detalhe de implementação: stack e arquitetura

O resultado vira o plan.md dentro da pasta da feature

O erro comum deste passo: enfiar detalhe de implementação lá atrás, na spec

Quando a spec já chega dizendo "usa Postgres com uma tabela assim", você não especificou o problema, você especificou uma solução que ainda nem foi discutida

6. Quebrar em tarefas executáveis com /speckit.tasks

/speckit.tasks

Gera as tarefas executáveis a partir do plano, no tasks.md

Esse arquivo é o que impede o agente de tentar fazer tudo de uma vez: ele executa uma tarefa e continua

7. Conferir a consistência com /speckit.analyze

/speckit.analyze

Ele verifica inconsistências entre spec, plano e quebra de tarefas, e roda ANTES da implementação

É o momento de pegar aquela tarefa que ficou órfã, ou o requisito que não virou tarefa nenhuma

O erro comum deste passo: achar que é opcional e ir direto pro código

Sai mais barato descobrir o furo no texto do que no diff

8. Implementar com /speckit.implement e validar com /speckit.converge

/speckit.implement

/speckit.converge

O /speckit.converge roda depois da implementação: ele avalia o código contra os artefatos e acrescenta as tarefas que faltaram

Se ele adicionar tarefas, tu roda /speckit.implement de novo, e repete até convergir

Uma observação antes da lista: a sequência oficial tem ainda o /speckit.checklist, que fica entre o /speckit.plan e o /speckit.tasks

Eu não numerei ele no passo a passo de propósito, pra tua primeira volta seguir o caminho principal, mas ele faz parte da sequência e tu vai ver o comando disponível aí

A sequência completa de comandos de barra, pra tu guardar em algum canto:

/speckit.constitution
/speckit.specify
/speckit.clarify
/speckit.plan
/speckit.checklist
/speckit.tasks
/speckit.analyze
/speckit.implement
/speckit.converge

No fim desse ciclo, tu tem spec.md, plan.md e tasks.md versionados em specs/###-nome-da-feature/

Isso é o artefato que eu prometi lá na abertura, e ele é a parte mais valiosa: o código dá pra refazer, a decisão bem escrita não 😀

Como foi escrever a spec na prática (e onde o método brilha)

No vídeo abaixo eu mostro esse método na versão manual, com 3 documentos de planejamento: requirements (o que o app faz), design doc (como vai ser construído) e o escopo de tarefas, que limita o que o agente faz em cada parte do sistema

O fluxo do Spec Kit condensa exatamente essa mesma sequência em comando

O que eu senti ali é o principal argumento do método: depois do planejamento, os prompts ficam BOBOS de simples

Vira "executa a task 3 seguindo o design doc e me avisa quando terminar"

A autenticação da demonstração saiu em cerca de 2 minutos

E eu comparo com inícios de projeto sem spec, que passavam de 10 minutos, mas fica a ressalva honesta: isso é lembrança de experiências anteriores minhas, não medição controlada lado a lado

Sem planejamento, o que eu vejo é aquele projeto corpo sem cabeça: a ideia é boa, mas não tem condução, e ele trava na hora de escalar

E o consumo de token dispara, porque a regra de negócio precisa ser reescrita inteira toda vez que entra funcionalidade nova

O spec-driven development funciona como baliza, um guard rail: a mesma ideia, os mesmos prompts, só que sem sair da curva

No vídeo tu vê a demonstração completa do fluxo numa funcionalidade pequena, do planejamento até a task rodando

E se eu não quiser instalar nada ainda?

Dá pra sentir o gostinho do método dentro do próprio Claude Code, usando o plan mode

Nesse modo ele lê arquivos, explora e escreve um plano, sem editar o código-fonte

Tu entra nele com Shift+Tab, que cicla default, acceptEdits e plan, ou prefixando um único prompt com /plan

Tome cuidado! Os atalhos do modo interativo de terminal, como o Shift+Tab, não valem no aplicativo Desktop do Claude Code, que usa o seletor de modo na interface

Não é o mesmo que ter spec versionada na pasta do projeto, mas já quebra o vício de mandar o agente codar antes de pensar 🙂

Quando vale escrever spec (e quando é burocracia)

Respondendo a pergunta que todo mundo faz: não, tu não precisa de spec pra tudo

O fluxo tem custo de tempo lá na frente, e ele se paga quando existe decisão a ser tomada

A régua que eu uso é essa: se a funcionalidade tem mais de uma forma razoável de ser construída, escreve a spec

Se só tem um jeito óbvio, manda ver e segue o baile

Conclusão

Se tu fez o passo a passo, agora tem três arquivos versionados na pasta da tua feature: spec.md, plan.md e tasks.md

Não é teoria sobre spec-driven development, é o artefato pronto, com a decisão escrita e o rastro de como se chegou nela

O próximo passo é simples: repete o ciclo numa segunda funcionalidade pequena

Na segunda volta tu já sabe onde respondeu vago, e aí aperta a constitution com os princípios que doeram de verdade

E usa /speckit.analyze antes e /speckit.converge depois, como rede dos dois lados da implementação

Seja por toolkit ou na mão, com os documentos escritos por você, o importante é o mesmo: planejar antes, codar depois

É isso que separa um projeto que cresce daquele corpo sem cabeça que trava na primeira funcionalidade nova

Até o próximo post! =)