Desenvolvimento guiado por especificação com Claude Code: um tutorial prático

O que é desenvolvimento guiado por especificação?

Desenvolvimento guiado por especificação é um fluxo baseado em três documentos, nessa ordem: um que diz o que a mudança deve fazer, um plano que define os passos e o código escrito seguindo o plano, com revisão humana entre cada par.

Os três pontos de revisão que um recurso percorre no desenvolvimento guiado por especificação.

Uma especificação é um documento curto, em linguagem simples e escrito antes de qualquer código, que diz o que a mudança deve fazer. Pense em um recurso como “permitir que os usuários exportem seus dados”. Uma especificação fixa as respostas que um agente, do contrário, teria que adivinhar. Ela lista 

• Formatos de arquivo compatíveis
• O modo de entrega
• O comportamento durante uma exportação pela metade
• As partes do recurso que ficam propositalmente de fora

Aqui está a abertura real de uma especificação que o Claude Code escreveu para uma mudança de workout-shape-verification em um app de accountability via Telegram meu. A mudança troca um limite frágil de frequência cardíaca por uma checagem do formato da curva de batimentos ao longo do tempo:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

O plano é o próximo documento. Ele quebra a especificação em tarefas numeradas que o agente pode executar uma a uma, cada tarefa nomeando um arquivo, uma mudança, uma ordem e um teste. Se a especificação responde ao “o quê”, o plano responde “em quais passos”. 

O código vem por último, escrito seguindo o plano, uma tarefa por vez.

Três documentos. Uma revisão humana entre cada par. Você revisa a especificação antes de virar plano. Revisa o plano antes de virar código. Revisa o código antes de fazer merge.

Como o desenvolvimento guiado por especificação difere do modo de plano

Você talvez já tenha usado o modo de plano do Claude Code (pressione Shift+Tab duas vezes para entrar) e ficou na dúvida do que muda aqui. O modo de plano gera um plano em um único turno de chat. O plano vive na memória, sem especificação persistida e sem etapa de revisão entre as fases.

O desenvolvimento guiado por especificação persiste a especificação e o plano como arquivos em disco. Cada um passa por revisão humana antes da fase seguinte começar, e os artefatos sobrevivem entre sessões. O modo de plano comprime duas fases do desenvolvimento em um único turno. Isso funciona em tarefas pequenas e falha assim que a base de código cresce e começa a atender usuários reais.

Por que o vibe-coding bate no limite

Vibe-coding funciona em protótipos, arquivos únicos e scripts descartáveis. Fica pior em apps reais, com usuários para responder, e em bases de código grandes e existentes. A linha de corte fica em cerca de 4 arquivos. Qualquer mudança que toque essa quantidade precisa de uma especificação — assim como qualquer refatoração com um estado final coerente, ou qualquer tarefa em que “o que exatamente isso deve fazer?” é a parte difícil.

O motivo da falha é claro. Um prompt vago como “adicione compartilhamento de fotos ao meu app” faz o modelo chutar milhares de requisitos não ditos.

Pegue um único requisito: preferências de notificação. O PM imagina toggles por canal. O backend constrói um liga/desliga. O frontend assume integração no nível do sistema operacional. Quatro leituras razoáveis de três palavras, quatro produtos diferentes.

Cada revisão no desenvolvimento guiado por especificação pega uma classe diferente de erro antes que fique caro. A revisão da especificação pega escopo inflado e diagnósticos errados de causa raiz. A revisão do plano pega implementações pela metade e padrões conflitantes. A revisão de código pega planos que parecem bons, mas quebram no primeiro teste que falha.

O retorno é real e cresce aos poucos. A fase da especificação custa horas de escrita antes de rodar qualquer código, e os primeiros recursos parecem mais lentos que vibe-coding. O meu ponto de equilíbrio veio por volta do quarto ou quinto recurso. A essa altura, as especificações já pegavam erros de design que eu de outra forma teria entregado e reescrito uma semana depois.

As três próximas seções apresentam três abordagens open source que rodam esse fluxo dentro do Claude Code. Elas estão ordenadas da mais leve à mais rígida na estrutura que impõem.

Superpowers

Superpowers é a mais leve das três. É a que eu uso no dia a dia e a que vamos detalhar mais.

O que é o Superpowers?

Superpowers é um plugin do Claude Code criado por Jesse Vincent (obra/superpowers, licença MIT), com cerca de 194k estrelas no GitHub. 

Ele vem com um conjunto de skills. Uma Claude skill, no Claude Code, é um arquivo de instruções nomeado que o agente carrega sob demanda para seguir um fluxo específico. O Superpowers inclui skills que mantêm o Claude Code no ciclo guiado por especificação, em vez de deixá-lo pular direto para o código.

A página do projeto Superpowers no GitHub.

Como instalar o Superpowers

Instale pelo marketplace oficial de plugins do Claude Code:

/plugin install superpowers@claude-plugins-official

Um hook SessionStart carrega automaticamente a skill using-superpowers, então o fluxo já fica ativo assim que você começa a digitar. (Claude code hooks são scripts que o agente roda em um evento específico do ciclo de vida.) Não há nada para configurar por projeto.

O fluxo do Superpowers

Depois disso, quatro skills organizam seu trabalho diário:

Um subagente é uma instância separada do Claude Code à qual o agente pai delega um trabalho focado, com a própria janela de contexto. Os subagentes revisores da tabela acima rodam como subagentes, então leem o código “frio”, sem o enquadramento do agente pai.

Como usar o Superpowers

Você invoca as quatro skills descrevendo o que quer em linguagem natural. A skill de brainstorming entende “vamos discutir este novo recurso” e inicia sozinha a conversa de especificação. As outras disparam do mesmo jeito.

As quatro skills do Superpowers em ordem, com os dois pontos de revisão humana entre brainstorming e writing-plans.

O passo a passo abaixo usa o mesmo recurso workout-shape-verification do trecho de especificação acima.

Etapa 1: do brainstorm à especificação

Eu abro o Claude Code e digito:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

A skill brainstorming assume e faz umas dez perguntas de volta, entre elas:

• O que conta como o “formato” certo
• Quais streams de dados combinar
• O que fazer com sessões que têm o formato certo, mas falham um limite antigo
• Se a mudança deve valer também para Run e Ride

Dois pontos de revisão humana entram aqui. O primeiro é a revisão de design, em que eu confirmo que as respostas batem com o que eu quero. O segundo é a revisão da especificação. Eu leio o arquivo que o Claude escreveu e aprovo antes de começar qualquer trabalho de plano.

Etapa 2: da especificação ao plano

Eu rodo a skill writing-plans. Ela lê a especificação aprovada e escreve um arquivo de plano com quatro partes:

• Uma definição do que significa “Concluído”
• Um mapa de arquivos que serão alterados
• Uma jornada do usuário pelo caminho de demo
• Uma lista numerada de tarefas com subetapas em checkboxes. 

Eu reviso o plano, questiono tarefas fora de ordem ou muito amplas e aprovo.

Etapa 3: do plano ao código

Eu rodo subagent-driven-development. Daqui em diante o loop segue sem mim. Para cada tarefa do plano, a skill:

1. Escreve um teste que falha
2. Escreve o código para passar o teste
3. Refatora
4. Aciona um subagente de code review que lê o diff “frio”

Se o revisor aponta um problema, o loop corrige antes de ir para a próxima tarefa. Não há revisão humana dentro desta etapa. As revisões que importam para esta fase são as duas anteriores.

Etapa 4: revisão do diff completo

Quando o plano termina, eu rodo requesting-code-review. Um subagente novo lê todo o diff em relação à especificação e ao plano e publica uma revisão. Eu aplico as sugestões antes do merge.

Quando uma tarefa do plano revela uma contradição com a especificação, o loop para e pergunta. Posso editar a especificação (ou deixar o Claude fazer) e regenerar as tarefas afetadas. A outra opção é um acerto pontual na própria tarefa. O Superpowers não contorna erros de especificação silenciosamente.

Especificações e planos reais em disco

Aqui está a especificação do recurso workout-shape-verification aberta no editor:

O arquivo de especificação como cai no disco após a skill de brainstorming escrevê-lo.

O cabeçalho traz os campos Created, Status e Supersedes que a skill de brainstorming escreve por padrão. Em seguida vem a seção Problem. Nada disso é código. O arquivo segue além do print com seções sobre a solução proposta e as restrições do que a mudança deve ou não tocar.

O plano correspondente abre com sua User Journey:

O arquivo de plano que a skill writing-plans produz a partir da especificação aprovada.

A jornada percorre o caminho de demo em cinco passos por vez, nomeando os comandos, arquivos e argumentos exatos a cada passo. As tarefas numeradas seguintes traduzem cada passo em subetapas com checkboxes que a skill subagent-driven-development consegue executar.

Os dois documentos se encaixam assim:

Especificação e plano lado a lado. A especificação responde o que muda e por quê. O plano responde em quais passos.

Para especificações e planos maiores, adiciono uma etapa que o loop oficial não tem: uma passada de red team. Antes de aprovar, peço para um ou vários subagentes Opus lerem a especificação “fria”, procurando brechas sob ângulos diferentes. É um hábito pessoal, não um recurso do Superpowers. Já pegou suposições ruins o bastante para eu manter.

Quando o Superpowers não é a escolha certa

Superpowers se encaixa em trabalho solo em um único repositório. Funciona melhor quando toda a base de código cabe em uma sessão do Claude Code e você de fato vai ler uma especificação de 2 páginas. A comparação detalhada está em Como escolher entre eles mais abaixo. A versão curta: Superpowers sofre com recursos que envolvem múltiplos repositórios e com trabalhos que exigem separação clara de papéis.

Um desenvolvedor apontou um quarto modo de falha em uma reclamação pública sobre o plugin: “Até a menor das tarefas leva uma eternidade, com o Claude abrindo subagentes e escrevendo planos totalmente exagerados. Mudar um CSS agora leva uma vida.”

O conserto é pular o Superpowers em mudanças minúsculas. As skills só ativam com o gatilho de brainstorming. Um ajuste de uma linha em CSS pode passar pelo Claude Code sem acionar o loop de especificação. O erro real aí é aplicar demais o fluxo a trabalhos que não precisam de especificação.

GitHub Spec Kit

O Spec Kit é a escolha quando a especificação precisa sobreviver além de uma única sessão do Claude Code. Também é a opção certa quando pessoas que nunca abrem o Claude Code precisam ler a especificação.

O que é o GitHub spec-kit?

Spec Kit é um projeto do GitHub (github/spec-kit, licença MIT), mantido pelo próprio GitHub, com mais de 100k estrelas. Ele traz um CLI e um fluxo que roda do mesmo jeito em todos os principais agentes de código com IA. Claude Code, Cursor, Aider, Cline e Roo Code são suportados. O design neutro em relação ao agente é o que permite que a especificação viva fora do Claude Code.

A página do projeto Spec Kit no GitHub.

Como instalar o GitHub spec-kit

Ainda não há pacote oficial no PyPI, então instale o CLI a partir da tag do Git com uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Substitua vX.Y.Z pela tag da versão atual. O pacote é specify-cli, e o comando registrado é specify.

O fluxo do GitHub spec-kit

O fluxo roda por nove comandos de barra que o CLI instala na lista de comandos do seu agente. Seis são o núcleo do loop, três são opcionais para casos que o núcleo não cobre.

O separador entre o grupo e o verbo é um ponto, não dois-pontos: /speckit.specify, não /speckit:specify. 

Os nove comandos de barra do Spec Kit: seis comandos centrais no pipeline e três opcionais conectados a ele.

Os artefatos produzidos por esses comandos são a mesma especificação e o mesmo plano que você viu na seção de Superpowers, também escritos em disco e rastreados pelo Git. A diferença é a portabilidade: os artefatos do Spec Kit são desenhados para funcionar com qualquer agente de código com IA, não só o Claude Code, e o fluxo é feito para revisão de stakeholders via pull requests no GitHub, e não como subproduto do loop de uma única ferramenta.

Quando usar o GitHub spec-kit

Em um projeto solo, você provavelmente não vai precisar do Spec Kit. Use quando:

• O projeto cresce além de uma pessoa
• Sua especificação precisa ser lida por pessoas que nunca abrem o Claude Code
• Você roda um agente que não é o Claude Code em parte do trabalho
• Você quer um formato de especificação que viva fora de qualquer ferramenta e ainda faça sentido meses depois

O método BMAD

Enquanto o Spec Kit organiza artefatos, o BMAD organiza pessoas. Ele divide o fluxo de especificação a código em quatro fases, cada uma tocada por um agente de papel específico.

O que é o BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, licença MIT, cerca de 47k estrelas) está na versão 6. A sigla, na documentação do projeto, significa “Breakthrough Method for Agile AI-Driven Development”. Ele roda sobre o Claude Code e outros agentes, e instala-se como um ecossistema de módulos. A instalação padrão entrega um módulo core com seis agentes de papel, quatro fases de fluxo e 34 ou mais workflows nomeados.

A página do projeto BMAD-METHOD no GitHub.

Como instalar o BMAD

Instale o BMAD com Node:

npx bmad-method install

Os seis agentes de papel são personas de prompt que o usuário ativa pelo nome dentro do host do agente. No Claude Code, isso significa digitar o comando de ativação que o BMAD instala. Confira o README para a sintaxe exata, que pode mudar entre versões. 

Apresentando os agentes e artefatos do BMAD

Uma vez ativado, o agente assume as instruções, a voz e as saídas daquele papel até você trocar de persona. Os seis são:

• Mary, a Analyst
• Paige, a Technical Writer
• John, o Product Manager
• Sally, a UX Designer
• Winston, o Architect
• Amelia, a Developer

Dois papéis que você poderia esperar não aparecem na v6: não há agente Scrum Master nem um agente de QA separado. Planejamento de sprint e preparação de histórias ficam com o agente Developer, e a geração de testes de QA é um workflow que o Developer dispara.

O conjunto de artefatos é mais pesado que uma única especificação. Você recebe:

• um product brief
• um PRD (Product Requirements Document)
• uma especificação de UX
• um documento de arquitetura
• épicos quebrados em user stories (o que os usuários podem fazer quando o trabalho for entregue)

O PRD e o documento de arquitetura juntos cumprem o mesmo papel da especificação do Superpowers. A divisão coloca-os em dois agentes de papel e em um formato mais formal. O conjunto como um todo cobre um ciclo completo de desenvolvimento de software, com cada recurso herdando contexto da camada acima.

O fluxo do BMAD

O fluxo da v6 roda em quatro fases.

As quatro fases do BMAD e o agente de papel que conduz cada uma. A trilha Quick Flow pula as três primeiras fases para trabalhos pequenos.

Fase 1, análise, é opcional. Mary (Analyst) e Paige (Tech Writer) fazem a pesquisa e produzem um product brief. Pule se você já sabe o que vai construir.

Fase 2, planejamento, é obrigatória. John (PM) escreve o PRD. Sally (UX Designer) adiciona uma especificação de UX quando o recurso tem interface.

Fase 3, solução, é a fase do Winston. O Architect rascunha a arquitetura primeiro, depois John quebra requisitos em épicos e histórias. Colocar as histórias depois da arquitetura é uma escolha da v6 que dimensiona contra limites reais de implementação. Winston então roda um check de prontidão para implementação que termina com PASS, CONCERNS ou FAIL.

Fase 4, implementação, é onde Amelia (Developer) trabalha história por história: cria, constrói e faz code review. Quando um épico inteiro termina, ela aciona um workflow de geração de testes de QA para o épico todo. É a fase em que o Claude Code faz a codificação, atuando como Amelia.

Para trabalhos pequenos e bem delimitados, o BMAD traz uma trilha “Quick Flow” que ativa diretamente a Amelia e pula as três primeiras fases. O comando de ativação está no README do BMAD (a sintaxe exata pode mudar entre versões). O Quick Flow não produz PRD nem documento de arquitetura, apenas uma história curta e o código que a satisfaz. É a resposta à objeção “isso é exagero para trocar um botão”.

Quando a especificação se mostra errada no meio da implementação, o BMAD volta pelo veredito da Fase 3 do Winston. Um FAIL leva você de volta à Fase 2 para reescrever o PRD. Um CONCERNS segue adiante com os riscos anotados pelo Winston anexados à história. A divisão permite seguir em frente em inconsistências pequenas e parar firme em grandes.

Quando a complexidade compensa

BMAD compensa em projetos de longa duração, com usuários reais para atender. Também serve para times com vários devs, passando trabalho entre pessoas. A separação por fases e papéis precisa economizar mais tempo do que custa.

É um encaixe ruim para um projeto solo. Em trabalho de uma pessoa, a divisão em quatro fases e seis agentes é, em grande parte, overhead. Não há uma segunda pessoa no time para a separação de papéis fazer diferença.

Como escolher entre os frameworks

Três regras orientam a escolha.

• Use o Spec Kit se a especificação tiver que ser lida por pessoas que nunca abrem o Claude Code, ou tiver que viver no Git como artefato de longo prazo.
• Se várias pessoas trabalham em papéis distintos, ou há um stakeholder estilo PM no loop, use BMAD.
• Caso contrário, use Superpowers.

Três perguntas sobre seu projeto, quatro escolhas de framework do outro lado.

Há uma quarta opção que a árvore de decisão sugere: combinar Spec Kit com Superpowers. Use o Spec Kit na fase de especificação para que os artefatos vivam no Git para revisão entre equipes. Depois, aponte a skill subagent-driven-development do Superpowers para o arquivo de plano do Spec Kit com uma linha de configuração. Você ganha a especificação durável do Spec Kit junto com o loop de implementação enxuto do Superpowers.

Conclusão

Desenvolvimento guiado por especificação são três documentos em ordem. A especificação diz o que construir, o plano define em quais passos e o código segue o plano. Uma revisão humana fica entre cada par.

Use a árvore de decisão acima para escolher um framework que, para a maioria, vai apontar para o Superpowers. Instale e escolha um recurso que você faria por vibe-coding, algo que toque de 3 a 5 arquivos. Rode de ponta a ponta: brainstorm, especificação, plano e execução. Uma execução real ensina o fluxo melhor do que qualquer descrição.

Se você quiser revisar os fundamentos do Claude Code antes, a DataCamp tem um tutorial prático de Claude Code, um guia de boas práticas cobrindo modo de plano, CLAUDE.md e TDD, e um mergulho profundo no modo de plano.