Spec driven development em time: como manter a especificação viva sem virar burocracia

Fala aí, beleza? Toda equipe já teve aquele documento lindo que alguém escreveu numa sexta e ninguém mais abriu

A spec só serve ao time enquanto alguém a mantém

E aqui mora o problema real de equipe, que quase nunca é sobre o método em si: onde esse documento vive, quem tem o dever de atualizar, e o que acontece quando o escopo muda no meio da feature

Quando a resposta é "tá num link do Drive lá", o documento vira papel morto

Quando a resposta é "tá no repositório, na branch da feature", o jogo muda

Neste post eu mostro um fluxo concreto de spec driven development em time, usando ferramentas que já versionam a especificação dentro do repo, com passo a passo, casos de time e o critério pra cortar burocracia

O que o time precisa ter antes de começar

Lista curta, e presta atenção porque parte disso é ferramenta e parte é combinado humano

Do lado da ferramenta:

• Repositório Git ativo, porque o fluxo do /speckit.specify cria uma branch numerada junto com a estrutura de diretórios da spec
• Um agente de codificação suportado: o Spec Kit, toolkit open source de spec driven development mantido pelo GitHub, tem 30+ integrações de agentes, incluindo GitHub Copilot, Claude Code, Cursor, Gemini CLI, Codex CLI, Qwen CLI, Goose e Windsurf
• uvx disponível na máquina, que é como o CLI specify é executado

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

Do lado humano (e esse é o que a galera pula):

• Acordo prévio de quem revisa spec

Se ninguém tem esse papel, o arquivo até nasce, mas envelhece calado

E antes de seguir, se o conceito ainda tá nebuloso pra alguém do time, vale alinhar o básico de desenvolvimento guiado por especificação antes de instalar qualquer coisa

A definição formal é bem direta: a especificação é o artefato autoritativo do qual saem implementação, testes e documentação

Ou seja, tu escreve e ACORDA a spec antes de desenvolver, tratando ela como fonte da verdade

Bora ver na prática? 🙂

Passo a passo: montando a especificação viva no repositório

1. Inicialize o projeto com o CLI specify

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

Se tu já tá dentro da pasta do projeto, roda assim:

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

O init instala os slash commands do fluxo dentro da pasta do agente no próprio projeto, e o agente lê esses arquivos direto

Por exemplo: .claude/ pro Claude Code e .github/prompts/ pro Copilot

Erro comum deste passo: rodar o init num projetinho de teste pessoal, fora do repositório do time

Spec que nasce fora do repo versionado já nasce morta, é só questão de tempo

2. Escreva a constituição do time com /speckit.constitution

Esse é o documento das regras inegociáveis, e ele mora em caminho fixo dentro do repositório: .specify/memory/constitution.md

Ali vão princípios centrais, restrições técnicas, convenções do time e regras de governança

Se tu conhece um arquivo de convenções de projeto, tipo aqueles guias de estilo que o time já mantém há anos, a ideia é bem semelhante

A diferença é que agora o agente lê ele também

Erro comum deste passo: escrever a constituição com as regras que o time GOSTARIA de seguir

Bota só o que já é praticado de fato, senão vira decoração

3. Gere a spec da feature com /speckit.specify

O fluxo vai de descrição da feature para criação de branch, geração do spec.md e checklist de validação

Cada feature vira uma pasta numerada dentro de specs/, com os artefatos separados por arquivo:

specs/001-nome-da-feature/
  spec.md
  plan.md
  tasks.md

A numeração é sequencial de 3 dígitos (001, 002, por aí vai), definida ao varrer as pastas já existentes em specs/

Erro comum deste passo: achar que isso é o documento único do projeto

Não é: são artefatos separados, e essa separação é justamente o que evita o calhamaço ilegível

4. Use os portões opcionais com critério (aqui é onde tu corta burocracia)

Nem todo comando do fluxo é obrigatório

Só /speckit.specify é estritamente exigido antes de /speckit.plan

Já /speckit.clarify, /speckit.checklist e /speckit.analyze são portões de qualidade que tu ACRESCENTA quando existe ambiguidade relevante

Esse é o ponto que separa rigor de burocracia num time pequeno: portão que roda por ritual, sem ambiguidade nenhuma pra resolver, é só custo

5. Separe plano e tarefas com /speckit.plan e /speckit.tasks

O plano fica no plan.md, as tarefas no tasks.md, arquivos distintos

Isso importa em equipe porque duas pessoas conseguem mexer em coisas diferentes sem brigar no mesmo arquivo gigante

6. Rode /speckit.analyze ANTES de gerar código

Esse comando aponta inconsistências entre spec, plan e tasks antes da implementação

E tem o /speckit.checklist, que gera critérios de validação revisáveis por humano

Erro comum deste passo: pular o analyze quando a feature mudou no meio do caminho

É EXATAMENTE aí que os três arquivos se desencontram, e o agente vai codar em cima do desencontro

7. Execute com /speckit.implement e feche com /speckit.converge

Com os três artefatos alinhados, a execução vira sequência, não adivinhação

E tem um detalhe pequeno que resolve uma dor bem chata de time: o Spec Kit registra qual é a feature ativa em .specify/feature.json, e dá pra sobrescrever pela variável de ambiente SPECIFY_FEATURE_DIRECTORY

Parece bobagem, mas é o que evita dois devs editando features diferentes achando que estão na mesma 😀

Quatro situações de time e o que fazer em cada uma

A spec começou a inchar:

Spec grande demais é spec que ninguém lê, e aí voltamos ao papel morto

A documentação do Kiro recomenda 5 a 8 requisitos por spec, e criar specs separadas por área da feature quando passa disso

É um número simples pra usar como régua de corte na revisão

O escopo mudou no meio da feature:

Aqui tá a maior vantagem de ter a spec versionada dentro do repositório

A alteração vira commit e revisão de código como qualquer outra mudança

O time discute a mudança de escopo no mesmo lugar onde discute código, com histórico, autor e diff

Depois roda /speckit.analyze pra reconciliar spec, plan e tasks antes de continuar

Acompanhar progresso sem marcar reunião:

O Kiro marca o estado das tarefas dentro do próprio tasks.md, com tarefas marcadas como em andamento ou concluídas durante a execução

Ou seja, o status mora no mesmo arquivo do plano

Se tu quiser ver a estrutura completa dessa abordagem, eu detalhei como o Kiro organiza spec, plano e tarefas em outro post

A spec de uma feature no Kiro fica em .kiro/specs/ com três documentos separados: requirements.md (histórias e critérios de aceite em notação EARS), design.md (arquitetura e diagramas) e tasks.md (plano de implementação rastreável)

Escolher o nível de ambição do time:

Essa parte é MUITO útil pra não prometer mais do que o time aguenta manter

Birgitta Böckeler, da Thoughtworks, analisou Spec Kit, Kiro e Tessl e separou o spec driven development em três níveis de ambição:

Time pequeno normalmente para no primeiro ou no segundo nível, e tá tudo certo

Tentar spec-as-source com três pessoas e prazo apertado é a receita clássica de virar burocracia e ser abandonado no mês seguinte

O que eu vi na prática rodando o fluxo

No vídeo eu rodo esse método ponta a ponta e comparo com o jeito solto de tocar projeto

A autenticação, com a especificação já escrita e acordada, saiu em cerca de 2 minutos

Começar um projeto sem SDD, pela minha estimativa ali, passa dos 10 minutos só pra sair do lugar

Mas se liga no detalhe que importa pro assunto deste post: esse ganho não vem do prompt

Ele vem da spec JÁ existir

Quando os documentos de requisitos, design e tarefas estão prontos, os prompts viram comandos curtos do tipo "executa a tarefa 3 seguindo o documento de design"

O planejamento consome mais tempo no começo, sem romance nenhum sobre isso

Depois a execução fica previsível e sequencial, e o ritmo acelera

E é por isso que manter a spec viva é o ponto central em time: o ganho dos 2 minutos não é da primeira feature, é da segunda, da terceira e da décima

Se o documento congela na feature 1, tu perde exatamente aquilo que te fez economizar

Eu gosto de pensar no SDD como um guard rail: tu continua usando tua ideia e teus prompts, só que guiado pra não sair muito da curva

Veja o fluxo completo em vídeo:

No vídeo abaixo eu mostro o fluxo rodando ponta a ponta, dos três documentos até a execução das tarefas, com a demonstração da autenticação

Por onde começar amanhã

Nada de reunião de duas horas pra apresentar metodologia nova pro time inteiro, isso mata a ideia antes dela nascer

O próximo passo é pequeno e cabe numa tarde:

1. Roda o specify init num projeto que JÁ existe, não num projeto novo de laboratório
2. Escreve a constituição em .specify/memory/constitution.md só com as regras que o time já segue de fato hoje
3. Aplica o fluxo completo em UMA única feature, do /speckit.specify ao /speckit.implement, e mede como foi

Depois disso tu tem argumento real pra propor ao time, e não slide

E o critério anti-burocracia é sempre o mesmo: portão opcional entra quando existe ambiguidade que custaria retrabalho, nunca por ritual

Spec viva é spec que alguém abre pra decidir alguma coisa

O resto é papel

Um abraço, e até o próximo post! 😀