Que projeto usar para praticar spec driven development antes de pagar um curso?

Curso nenhum vai te ensinar spec driven development se você nunca escreveu uma spec na vida

É tipo aprender a dirigir lendo o manual do carro, sabe?

O método é simples de descrever: Spec, Plan, Tasks, Implement

Só que ele só faz sentido de verdade quando você aplica num projeto pequeno o bastante pra você mesmo julgar se o resultado saiu certo ou saiu torto

E a melhor parte: o custo de começar hoje é zero, o Spec Kit é o toolkit do GitHub pra Spec-Driven Development e tem código aberto sob licença MIT

Então aqui vão três tipos de projeto de treino e um roteiro de progressão do simples ao ambicioso, com os comandos reais e o erro comum de cada etapa 🙂

O que você precisa ter antes de começar

A lista é curtinha, se liga:

• Um agente de código: o Spec Kit funciona com mais de 30 agentes, tanto CLIs quanto assistentes de IDE, então provavelmente o que tu já usa serve
• O Spec Kit instalado via uvx
• Saber onde os arquivos moram, pra não ficar perdido depois do primeiro comando

A instalação e a criação do projeto saem no mesmo comando:

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

Se tu já está dentro da pasta do projeto, roda specify init . pra inicializar ali mesmo

Onde os arquivos do Spec Kit vivem:

O projeto passa a ser a pasta que contém .specify/

Dentro dela ficam memory/constitution.md, scripts/ e templates/

E as specs por funcionalidade ficam separadas, tipo specs/001-nome-da-feature/ com spec.md, plan.md e tasks.md

Olhar essa estrutura já ensina metade do método: o planejamento é um artefato do repositório, não um papo que morre no chat

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

E se eu não quiser instalar nada agora?

Dá pra treinar o músculo do planejamento sem instalar coisa nenhuma, usando o modo de plano do Claude Code

Tu pressiona Shift+Tab até a barra de status mostrar ⏸ plan mode on, ou já inicia a sessão com a flag:

claude --permission-mode plan

Nesse modo ele faz perguntas de esclarecimento antes e constrói um arquivo de plano que VOCÊ pode editar antes da execução

Não é o Spec Kit, mas é o mesmo princípio: separar o pensar do fazer

E repara numa coisa que confunde muita gente: escolher stack não é pré-requisito pra começar

A especificação trata do QUE o sistema faz e do PORQUÊ (comportamento visível ao usuário), a stack técnica pertence ao plano

Três tipos de projeto que forçam você a escrever spec de verdade

O problema de escolher projeto de treino é que quase todo tutorial sugere um to-do list

E to-do list não força spec nenhuma, porque não tem decisão difícil pra tomar

Os três abaixo têm 😀

1) CRUD com uma regra de negócio no meio:

Cadastrar, listar, editar e apagar não é o exercício

O exercício é a REGRA que mora no meio: desconto por faixa de valor, limite de agendamento por dia, status que não pode voltar pra trás

É ela que te obriga a escrever critério de aceite que não aceita duas interpretações

Habilidade treinada aqui: escrever critério de aceite não ambíguo

Um jeito bom de treinar isso é usar a notação EARS, que o Kiro usa nos critérios de aceite, no padrão QUANDO (condição/evento) O SISTEMA DEVE (comportamento esperado)

Na prática vira algo assim:

QUANDO o pedido tiver valor acima da faixa 2
O SISTEMA DEVE aplicar o desconto da faixa 2 uma única vez

QUANDO o status do pedido for "entregue"
O SISTEMA DEVE recusar qualquer mudança para "em separação"

Como saber que você acertou: entrega a spec pra outra pessoa (ou pra outro agente) e pergunta o que acontece num caso limite

Se as respostas baterem, a spec está de pé

2) Script de importação de dados sujos:

Esse é cruel de um jeito bom

CSV com linha duplicada, campo obrigatório vazio, encoding errado, data em três formatos diferentes na mesma coluna

Cada uma dessas situações é uma decisão que você VAI ter que tomar

A única pergunta é: você toma agora, na spec, ou toma às pressas no meio da geração de código?

Habilidade treinada aqui: enumerar caso de borda antes de existir código

Como saber que você acertou: rode o script com um arquivo propositalmente destruído

Se pra cada estrago o comportamento já estava escrito na spec, você mandou bem

Se você precisou improvisar, achou a lacuna, ótimo, é isso que o exercício serve pra revelar

3) Refatoração de um trecho que já existe:

Esse é o meu favorito pra quem acha que spec é burocracia

Aqui a spec descreve o comportamento que NÃO pode mudar

E o plano descreve a mudança interna, a troca de estrutura, a reorganização

Ou seja: é literalmente a separação entre especificação (o que e por quê) e stack técnica (o como), que é o coração do método

Habilidade treinada aqui: descrever comportamento sem descrever implementação

Como saber que você acertou: se a sua spec continua verdadeira DEPOIS da refatoração, sem editar uma linha, ela era mesmo uma spec

Se ela quebrou junto com o código, você escreveu documentação técnica disfarçada

Roteiro de progressão: do primeiro spec.md ao projeto ambicioso

Aqui vale um aviso pra não embolar: o ciclo de comandos é UM só, e você roda ele INTEIRO em cada um dos três projetos

O que muda do exercício 1 pro 3 não é o comando, é a dificuldade do que você tem pra escrever em cada passo

Então primeiro o ciclo completo, com o comando real e o erro comum de quem está começando:

1. Rode /speckit.constitution e fixe os princípios inegociáveis do projeto

Vale o esforço porque os outros comandos consultam esse arquivo pra seguir alinhados, ele não é enfeite

O erro comum deste passo: escrever princípio genérico tipo "código limpo"

Princípio inegociável é aquele que você usaria pra RECUSAR uma implementação

2. Rode /speckit.specify descrevendo em linguagem natural o que o sistema faz e por quê

Ele cria ou atualiza a especificação da funcionalidade a partir da sua descrição

O erro comum deste passo: enfiar a stack técnica na spec

Banco, framework e biblioteca pertencem ao /speckit.plan, não ao specify

3. Rode /speckit.clarify pra fechar as lacunas que você deixou

É aqui que aparecem as perguntas chatas sobre caso limite e campo vazio

O erro comum deste passo: responder "tanto faz"

Se tanto faz pra você, vai fazer muita diferença pro agente depois

4. Rode /speckit.checklist e trate o resultado como parte do exercício

Ele gera um checklist de qualidade da própria especificação, descrito como testes unitários para os seus requisitos: verifica se a spec está completa, clara, não ambígua e consistente

O erro comum deste passo: achar que o checklist valida o CÓDIGO

Ele valida a SPEC, e essa distinção é meio que a aula inteira em uma frase

5. Rode /speckit.plan e só agora decida a parte técnica

Aqui entra o que você segurou lá atrás: stack, estrutura, abordagem

6. Rode /speckit.tasks pra gerar o tasks.md a partir dos artefatos de design

Ele sai acionável e ordenado por dependência, o que já resolve aquela dúvida de "por onde eu começo?"

7. Rode /speckit.analyze antes de gerar código

O erro comum deste passo: pular ele porque "tá tudo certo"

Ninguém revisa o próprio plano com olhar de auditor, é pra isso que existe o comando

8. Só então rode /speckit.implement

O erro comum deste passo é o mais caro de todos: ir direto pro implement e descobrir tarde que resolveu o problema errado

Separar pesquisa e planejamento da implementação é justamente o que evita esse prejuízo

Ainda dá pra fechar o ciclo com /speckit.converge, que faz parte do conjunto de comandos que conduzem o processo

E onde entra a progressão, então:

A progressão está nos PROJETOS, não nos comandos

Rodada 1, o CRUD com regra de negócio: roda o ciclo inteiro, do constitution ao implement, e repara que o passo que mais aperta é o /speckit.specify, porque é ali que a regra de negócio vira critério de aceite

Rodada 2, o script de importação: mesmo ciclo do começo ao fim, só que agora quem dói é o /speckit.clarify, com as perguntas sobre linha duplicada, campo vazio e data em três formatos

Rodada 3, a refatoração: ciclo completo de novo, e a dificuldade migra pro /speckit.plan, porque a spec tem que sobreviver intacta enquanto o plano muda tudo por dentro

Três rodadas do mesmo ciclo, com o peso caindo em lugar diferente a cada vez, é isso que fixa o método

Quer repetir o mesmo exercício em outra ferramenta?

Recomendo, viu? Repetir o MESMO projeto em ferramenta diferente é o que separa "decorei os comandos" de "entendi o método"

No Kiro, uma spec de funcionalidade é composta por três arquivos: requirements.md (histórias de usuário e critérios de aceite em EARS), design.md (arquitetura e abordagem técnica) e tasks.md (tarefas de implementação rastreáveis)

E ele oferece dois fluxos de spec de funcionalidade, Requirements-First e Design-First, mais um modo direto, o Quick Plan, que responde perguntas de esclarecimento na frente e vai direto pra lista de tarefas

Tem também a análise de requisitos, que verifica se os requisitos têm nível de detalhe adequado, sinaliza critérios de aceite que aceitam múltiplas interpretações plausíveis e detecta contradições e lacunas

Rodar isso na sua spec do CRUD é humilhante na primeira vez, haha

E é exatamente aí que se aprende

Depois que o fluxo virar rotina, dá pra empacotar ele numa skill reutilizável entre projetos e parar de repetir setup

O que muda na prática quando você escreve a spec antes

No vídeo abaixo eu montei um SDD manual, sem framework nenhum, só pra mostrar a filosofia por trás

Peguei um gerador de QR Code como projeto de demonstração, justamente por ser simples o bastante pra ensinar o método sem o projeto roubar a cena

O escopo eu fechei assim: sem login a pessoa gera e baixa o QR Code (URL, texto, wi-fi, contato), e com login ela salva e gerencia os códigos numa dashboard

E olha, o que mais mudou o jogo ali não foi o que eu escrevi que o app FAZ

Foi a seção de "o que o app NÃO faz": sem analytics, sem QR Code dinâmico, sem upload de logo, sem API pública, sem plano pago

Essa lista de negativas é o que impede o agente de inventar recurso e é o que impede VOCÊ de aceitar

Usei três documentos de planejamento: requirements (o que o app faz), design doc (como será construído) e a lista de tarefas (a ordem de execução)

E reforço uma coisa que muita gente encolhe: design doc não é cor e estilo

Entra stack, esquema de banco, rotas, páginas, componentes e decisão técnica

Eu escolhi de propósito uma stack que as IAs dominam e que costuma não dar erro: Next.js, TypeScript, Prisma e SQLite (banco em arquivo, sem setup), assumindo que em produção eu trocaria por Postgres

A ordem das tarefas eu guiei pelo uso: setup inicial, depois autenticação (por ser complexa e vital), depois a função principal, depois as áreas logadas e por fim uma etapa de polimento

Onde o método pagou:

O ganho maior apareceu na condução

Projeto feito 100% no vibe coding sem planejamento trava quando precisa escalar, porque uma funcionalidade nova obriga a mexer na regra de negócio inteira, e aí o consumo de tokens dispara

É tipo construir um corpo sem cabeça: a ideia é boa, mas não tem condução, e as decisões ruins do começo travam o projeto em coisa simples lá na frente

O SDD funciona como uma baliza que mantém o projeto na curva, gerando código mais robusto, mais seguro e com menos tokens

Onde ele atrapalha:

Sendo honesto: pra projeto pessoal que ninguém vai usar, SDD pode ser queima de tokens desnecessária, porque a etapa de planejamento consome mais

Minha régua prática é essa: se o projeto passa de uns três prompts, ou se tem autenticação, pagamento, perfis de usuário e dashboard, vale planejar

Se é script de fim de semana, toca o vibe coding e segue a vida

Se essa fronteira ainda te confunde, vale ler sobre quando usar cada abordagem antes de escolher o exercício

Um aviso pra quem vai treinar sozinho:

Não deixa a IA redigir os documentos sozinha

Cocrie com ela

Quando ela escreve tudo, o texto fica mais rígido e menos natural, e a parte de funcionalidades e jornada do usuário quem sabe é VOCÊ

E se você não é técnico, calma: dá pra se apoiar na IA pra definir stack, e no esquema de banco basta listar quais dados precisam ser salvos, sem se preocupar com tipo de coluna

Outro detalhe: documento de planejamento PODE ser longo, ao contrário de arquivo de contexto do agente, que precisa ser sucinto

Eu rodei o projeto do vídeo com o Claude Code, que é o que mais uso no momento, mas a escolha do agente não muda o método em nada

No vídeo dá pra ver o método rodando de ponta a ponta, os documentos nascendo e o projeto sendo executado tarefa por tarefa, que é a parte que texto nenhum consegue mostrar direito

E o curso, vale a pena?

Meu veredito honesto: de graça você aprende o método inteiro

Os comandos estão documentados, o toolkit é aberto, o modo de plano já vem no agente

O que um curso adiciona é atalho e correção: alguém apontando que sua spec está ambígua antes de você descobrir isso por dor própria, e a ordem em que faz sentido aprender

Mas comprar curso antes de escrever a primeira spec é pagar pra assistir alguém fazer uma coisa que você ainda não sabe que é difícil

Por onde começar hoje

Escolha única, sem enrolar: pega o CRUD com UMA regra de negócio

Roda o specify init, escreve o spec.md e passa o /speckit.checklist ANTES de gerar uma linha de código

Se o checklist reclamar, ótimo, é ali que mora o aprendizado

Depois toca o ciclo até o /speckit.implement e vê o troço de pé

E aí repete o mesmo exercício num segundo agente

O projeto é o mesmo, o método é o mesmo, e a diferença que aparecer é ferramenta, não conceito… essa comparação ensina MUITO

E o critério pra pagar um curso é esse: quando os três exercícios já estiverem feitos (CRUD, importação e refatoração) e a sua dúvida for de ESCALA, não de método

Dúvida de método você resolve de graça esta semana

Bora praticar spec driven development de verdade? 😀

até o próximo post!