Existe um gap crescente entre desenvolvedores que obtem resultados confiaveis do Claude Code e desenvolvedores que passam metade do dia desfazendo o que o agente acabou de construir. A diferenca nao e talento, experiencia ou algum truque secreto de prompt engineering. E uma questao de metodologia. Os desenvolvedores que entregam software de producao com agentes de IA convergiram em um padrao, chamem disso o que quiserem: definir o que voce quer antes do agente comecar a escrever codigo.
Este artigo da um nome a esse padrao. Desenvolvimento spec-first e uma metodologia para engenharia de software assistida por IA. Nao uma vaga "boa pratica." Um ciclo de vida estruturado e repetivel com fases definidas, checkpoints claros e artefatos concretos em cada passo. Se voce tem procurado uma forma de tornar a saida do Claude Code previsivel o suficiente para apostar seu cronograma de releases, este e o framework.
O teto do Vibe Coding
"Vibe coding" entrou no vocabulario no inicio de 2025. A proposta: descreva o que voce quer em linguagem natural, deixe a IA escrever, itere ate parecer certo. Para prototipos, projetos de fim de semana e scripts pontuais, vibe coding funciona. Voce obtem algo funcional rapido, e se quebrar depois, o risco e baixo.
Software de producao opera sob restricoes diferentes. O codigo precisa se integrar com uma codebase existente, satisfazer requisitos especificos e sobreviver ao contato com outras pessoas que vao mante-lo. Quando vibe coding encontra essas restricoes, os modos de falha sao previsiveis.
A primeira falha e o drift. Voce descreve uma funcionalidade vagamente, o agente implementa sua interpretacao, voce ajusta, o agente reimplementa sua interpretacao ajustada. Tres iteracoes depois, voce tem codigo funcionando que nao satisfaz nenhum dos seus requisitos originais porque cada iteracao deslocou o alvo. Voce esta convergindo para o que o agente acha que voce quer, nao para o que voce realmente precisa.
A segunda falha sao decisoes invisiveis. Cada lacuna na sua descricao e uma decisao que o agente toma silenciosamente. Schema do banco de dados, estrategia de tratamento de erros, formato da API, regras de validacao, escolha de bibliotecas. Voce descobre essas decisoes durante o code review, ou pior, em producao. O agente nao tomou decisoes ruins. Tomou decisoes nao instruidas, e voce nao tinha mecanismo para detecta-las antes de serem incorporadas na implementacao.
A terceira falha e a paralisia de review. Um diff de 600 linhas onde o agente escolheu a arquitetura, o modelo de dados, os codigos de erro e o tratamento de casos limite nao e revisavel no sentido tradicional. Voce nao esta revisando codigo contra uma spec. Esta reconstruindo a spec a partir do codigo, depois decidindo se concorda. Isso leva mais tempo do que escrever a spec levaria.
Vibe coding atinge um teto porque confunde duas atividades distintas: decidir o que construir e construir. Desenvolvimento spec-first as separa.
Spec-First como metodologia
Desenvolvimento spec-first e um ciclo de vida de quatro fases. Cada fase produz um artefato concreto. Cada transicao tem uma condicao de gate clara. A metodologia funciona com qualquer agente de codificacao IA, mas os exemplos neste artigo usam Claude Code porque e onde a comunidade esta iterando mais rapido.
Fase 1: Brainstorm
Voce e o agente (ou so voce) exploram o espaco do problema. Quais sao as restricoes? Que abordagens existem? Quais sao os tradeoffs? Isso e conversacional. Voce nao esta se comprometendo com nada. Esta mapeando o territorio.
A condicao de gate: voce tem uma abordagem preferida e pode articular por que esta abordagem e nao as alternativas.
Brainstorming com Claude Code e valioso porque o agente tem amplo conhecimento de padroes e bibliotecas. O erro e pular do brainstorm direto para o codigo. O brainstorm mostra opcoes. Nao escolhe entre elas. Voce escolhe.
Fase 2: Spec
Voce escreve a decisao. Este e o contrato contra o qual o agente vai implementar. Uma spec nao e uma user story, nao e um ticket do Jira, nao e um paragrafo de prosa. E um documento estruturado com:
- Declaracao do problema: o que esta quebrado ou faltando, em termos concretos
- Abordagem proposta: a solucao escolhida na fase de brainstorm
- Arquivos afetados: quais arquivos o agente deve tocar (e implicitamente, quais nao)
- Criterios de aceitacao: condicoes testaveis que definem "pronto"
- Fora do escopo: o que o agente deve explicitamente evitar
Os criterios de aceitacao sao o elemento mais importante. Cada um deve ser uma acao concreta com resultado observavel. "Autenticacao deveria funcionar" nao e um criterio. "Submeter credenciais validas retorna 200 com token de sessao; submeter credenciais invalidas retorna 401 sem token" e.
A secao fora do escopo previne gold-plating. Sem ela, agentes vao "melhorar" codigo adjacente, refatorar arquivos que notaram desarrumados, ou adicionar funcionalidades que parecem relacionadas. Cada minuto que o agente gasta em trabalho nao solicitado e um minuto que voce gasta revisando trabalho nao solicitado.
A condicao de gate: alguem que nao estava no brainstorm poderia ler esta spec e construir a coisa certa.
Fase 3: Implementacao
O agente executa contra a spec. Nao contra uma conversa. Nao contra uma memoria do que voces discutiram. Contra um documento concreto com criterios testaveis.
Antes de escrever codigo, o agente produz um plano: uma lista numerada de mudancas que pretende fazer, quais arquivos vai modificar e como vai verificar o resultado. Este plano e um checkpoint de dois minutos. Voce le, confirma que corresponde a sua intencao e da sinal verde para a implementacao. Ou detecta um mal-entendido e corrige. De qualquer forma, investiu dois minutos em vez de vinte.
O padrao plan-before-code nao e burocracia. E a intervencao individual de maior alavancagem em todo o workflow. A maioria dos erros de implementacao nao sao erros de codigo. Sao erros de compreensao: o agente entendeu mal a spec. Detectar um erro de compreensao em um plano custa dois minutos. Detecta-lo em um diff de 400 linhas custa vinte. Detecta-lo em producao custa um dia.
A condicao de gate: o agente publicou um relatorio de conclusao com afirmacoes especificas sobre o que foi construido e como foi verificado.
Fase 4: Verificacao
Voce ou um processo de QA confirma a implementacao contra a spec. Nao "parece certo?" mas "satisfaz cada criterio de aceitacao?"
Verificacao e mecanica. Voce pega cada criterio da spec, executa o teste (rodar um comando, abrir o navegador, disparar um evento) e registra o resultado: passou ou falhou. Criterios que falham voltam para a Fase 3. A verificacao e documentada junto com a implementacao para que qualquer pessoa que leia a tarefa daqui a seis meses possa ver exatamente o que foi testado.
A condicao de gate: todo criterio de aceitacao tem um resultado registrado de passou/falhou.
Este e o ciclo de vida completo. Quatro fases, quatro artefatos (justificativa da abordagem, spec, plano de implementacao, registro de verificacao), quatro condicoes de gate. As fases sao sequenciais mas leves. Para uma funcionalidade de tamanho medio, fases 1 e 2 levam 15-20 minutos. Fase 3 leva o tempo da implementacao. Fase 4 leva 5-10 minutos.
Todo argumento para escrever specs e anterior a IA. "Escreva requisitos antes do codigo" e conselho de antes da maioria de nos nascer. Entao por que enquadrar isso como algo especifico do desenvolvimento assistido por IA?
Porque agentes mudam a funcao de custo.
Um desenvolvedor humano que recebe um requisito vago vai parar e fazer perguntas. "Voce quis dizer auth por senha ou SSO?" "Precisa funcionar no celular?" "O que acontece quando o token expira?" Cada pergunta e um mini-checkpoint que empurra a implementacao na direcao do alvo correto. O custo de uma spec vaga com um desenvolvedor humano sao alguns threads no Slack e talvez uma tarde de retrabalho.
Um agente que recebe um requisito vago nao vai parar. Vai tomar cada decisao ambigua silenciosamente, se comprometer com uma abordagem e apresentar uma implementacao pronta. O custo de uma spec vaga com um agente e uma implementacao pronta que pode estar completamente errada, mais o tempo para descobrir que esta errada, mais o tempo para refaze-la.
A assimetria e gritante. Agentes sao mais rapidos em execucao e piores em julgamento que desenvolvedores humanos. Cada ambiguidade na spec e uma chamada de julgamento, e cada chamada de julgamento que o agente faz sem orientacao e um cara ou coroa sobre se o resultado corresponde a sua intencao. Uma spec elimina os caras ou coroas.
Ha uma segunda razao, mais sutil. Agentes nao contestam. Um engenheiro senior que recebe uma spec ruim vai dizer "isso nao faz sentido por causa de X." Um agente vai implementar fielmente uma spec ruim e produzir output fielmente errado. Desenvolvimento spec-first forca voce a testar seu proprio pensamento antes de entrega-lo a uma entidade que vai executa-lo sem questionamento. A spec nao e so para o agente. E para voce.
O checkpoint plan-before-code
Se voce levar uma unica pratica deste artigo e ignorar o resto, leve esta.
Antes do agente escrever codigo, exija que ele publique um plano de implementacao. Nao codigo. Nao um diff. Um esquema estruturado do que pretende fazer.
Um plano se parece com isso: passos numerados em ordem de execucao, arquivos a modificar, mudancas de logica em cada arquivo e a abordagem de verificacao. O agente produz isso em cerca de trinta segundos. Voce le em cerca de dois minutos. Nesses dois minutos, voce pode detectar:
- Violacoes de escopo: o agente planeja modificar arquivos nao listados na spec
- Desalinhamentos arquiteturais: o agente escolheu uma abordagem que conflita com padroes existentes
- Passos faltantes: o plano nao aborda um criterio de aceitacao
- Superengenharia: o agente planeja construir abstracoes nao justificadas
A revisao de plano de 2 minutos substitui a revisao de diff de 20 minutos onde voce descobre esses problemas depois de ja construidos. E o gate de qualidade mais barato na engenharia de software.
Escrevi um passo a passo detalhado do padrao plan-before-code em Desenvolvimento spec-driven com Claude Code, incluindo templates de spec e formatos de relatorios de conclusao. Este artigo foca em por que o padrao funciona; aquele foca em como implementa-lo.
Verificacao como step de primeira classe
A fase com menos investimento no workflow da maioria dos desenvolvedores e a verificacao. O agente diz "pronto." O desenvolvedor da uma olhada no diff. O merge acontece. O bug aparece dois dias depois quando um usuario encontra o caso limite numero tres dos criterios de aceitacao.
Desenvolvimento spec-first trata verificacao como um step formal com seus proprios artefatos. O relatorio de conclusao mapeia cada criterio de aceitacao a uma verificacao concreta:
- Criterio: "Trocar de workspace restaura o estado de filtros salvo."
- Verificacao: Abrir o app, definir filtros no workspace A, trocar para workspace B, voltar para workspace A, observar que os filtros estao restaurados.
- Resultado: Passou.
Isso nao e overhead. E o step que determina se a implementacao realmente satisfaz a spec. Sem ele, a spec e uma lista de desejos e os criterios de aceitacao sao aspiracionais.
O registro de verificacao tambem resolve um problema a jusante: code review. Quando um revisor abre o pull request, le a spec, le o registro de verificacao e revisa o diff com contexto completo. O tempo de revisao cai porque o revisor esta confirmando uma afirmacao verificada, nao conduzindo uma investigacao.
Quando voce roda multiplos agentes em paralelo, cada um implementando uma spec diferente, disciplina de verificacao e a diferenca entre um pipeline controlado e um monte de codigo que "provavelmente funciona." Cada spec tem criterios. Cada implementacao tem um relatorio de conclusao. Cada relatorio mapeia criterios a verificacoes. Nada e entregue sem verificacao registrada.
Objecoes e tradeoffs honestos
Desenvolvimento spec-first nao e gratis. As objecoes sao reais e merecem ser abordadas de frente.
"Escrever specs me deixa mais lento." Isoladamente, sim. Escrever uma spec para uma funcionalidade leva 15-20 minutos. Mas voce recupera esse tempo (e mais) nas fases de implementacao e revisao. Um agente com uma spec clara produz uma implementacao correta com mais frequencia que um agente com um prompt vago. Menos iteracoes, menos retrabalho, revisoes mais curtas. O efeito liquido para funcionalidades de qualquer substancia e entrega mais rapida, nao mais lenta.
Para mudancas triviais (renomear uma variavel, corrigir um typo, incrementar versao), specs sao overhead desnecessario. Spec-first e para trabalho onde a implementacao requer decisoes. Se a mudanca e mecanica e nao ambigua, pule a spec.
"Meu agente e bom o suficiente sem specs." Para algumas tarefas, provavelmente verdade. Claude Code e notavelmente capaz de inferir intencao a partir de descricoes breves. A questao nao e se o agente pode produzir boa saida a partir de instrucoes vagas. E se faz isso de forma confiavel. Se voce esta confortavel com retrabalho ocasional e tempos de revisao imprevisiveis, vibe coding pode ser suficiente para seu caso de uso. Spec-first compensa quando consistencia e previsibilidade importam: quando a funcionalidade e complexa, quando o codigo vai para producao, quando outra pessoa vai manter.
"Specs ficam desatualizadas." Preocupacao valida. Uma spec escrita durante o brainstorm pode nao sobreviver ao contato com a realidade. A solucao nao e pular specs. E atualizar a spec quando o plano revela novas informacoes. Se o plano do agente mostra que a abordagem na spec nao vai funcionar, revise a spec antes de prosseguir. A spec e um documento vivo durante a implementacao. Torna-se registro historico apos a verificacao.
"Isso e so waterfall." Nao. A falha do waterfall eram grandes specs para grandes projetos com longos ciclos de feedback. Desenvolvimento spec-first opera no nivel da tarefa: uma spec por funcionalidade ou fix, escrita em 15-20 minutos, implementada em horas, verificada no mesmo dia. O ciclo de feedback e curto. O investimento por spec e pequeno. Se a spec esta errada, voce descobre durante a revisao do plano, nao seis meses depois.
Ferramentas para o ciclo de vida Spec-First
A metodologia funciona com qualquer sistema de tarefas: GitHub Issues, Linear, Notion, arquivos de texto simples. O que importa e que spec, plano, notas de implementacao e resultados de verificacao vivam em um unico lugar, anexados a uma tarefa.
Se voce esta procurando um sistema projetado para este workflow, beads e um issue tracker open-source e Git-nativo que contem o ciclo de vida completo. Cada "bead" carrega uma descricao (sua spec), uma thread de comentarios (planos e relatorios de conclusao), um status (open, in_progress, ready_for_qa, done) e metadados como dependencias e prioridades. O CLI bd opera do terminal, o que significa que agentes podem ler specs, publicar planos e reportar conclusoes sem sair do ambiente de trabalho.
bd create --title "Persist filter state across workspaces" \
--description "## Problem ..." --type feature --priority p2
bd update bb-a1b2 --claim --actor eng1
bd comments add bb-a1b2 --author eng1 "PLAN: ..."
# After implementation:
bd comments add bb-a1b2 --author eng1 "DONE: ... Commit: a1b2c3d"
bd update bb-a1b2 --status ready_for_qa
O ciclo de vida inteiro acontece no CLI. Seis meses depois, bd show bb-a1b2 retorna o historico completo do que foi especificado, planejado, construido e verificado.
Quando voce roda um agente por este ciclo de vida, o CLI e suficiente. Quando roda cinco ou dez em paralelo, cada um em um estagio diferente do pipeline spec-implement-verify, voce precisa ver o estado do pipeline de relance. Beadbox e um dashboard em tempo real que mostra quais specs estao abertas, quais tem planos aguardando revisao, quais estao em andamento, quais estao bloqueadas e quais estao prontas para verificacao. Monitora o mesmo banco de dados beads em que os agentes escrevem, atualizando ao vivo conforme os status mudam.
Voce nao precisa do Beadbox para praticar desenvolvimento spec-first. A metodologia e agnostica a ferramentas. Mas quando fluxos de trabalho paralelos transformam seu pipeline em uma fila de tarefas que voce nao consegue rastrear so de cabeca, a camada visual muda a velocidade com que voce pode revisar, desbloquear e entregar.
A mudanca mais ampla
Desenvolvimento spec-first nao e uma reacao a agentes de codificacao IA serem ruins. E o reconhecimento de que sao bons nas coisas erradas sem orientacao. Agentes sao executores extraordinariamente capazes. Escrevem sintaxe correta, seguem padroes, lidam com boilerplate e produzem um volume que nenhum humano consegue igualar. O que lhes falta e o contexto para tomar boas decisoes sobre o que construir. Esse contexto vem de voce, e a spec e o veiculo.
Os desenvolvedores que vao prosperar na engenharia assistida por IA nao sao os que escrevem os melhores prompts. Sao os que escrevem as melhores specs. Prompts sao efemeros. Specs sao duraveis. Prompts otimizam para uma unica interacao. Specs otimizam para um ciclo de vida: brainstorm, definir, implementar, verificar.
Isto nao e um contorno temporario ate os agentes ficarem mais inteligentes. Mesmo que os modelos melhorem, a assimetria fundamental permanece: o humano sabe o que o negocio precisa; o agente sabe como escrever codigo. Uma spec conecta os dois. Modelos melhores vao executar specs mais rapido, mas a necessidade da spec nao desaparece. Fica mais importante conforme voce escala, porque mais agentes rodando contra instrucoes vagas produzem output mais divergente.
Se voce tem rodado agentes Claude Code e encontrado resultados inconsistentes, ou gasto tempo demais em revisao, ou com dificuldade de coordenar fluxos de trabalho paralelos, tente isso: antes da proxima funcionalidade, gaste 15 minutos escrevendo uma spec com criterios de aceitacao testaveis, exija que o agente publique um plano antes de codar, e verifique a saida criterio por criterio. Um ciclo vai mostrar a diferenca.
Se voce esta construindo workflows como esse, de uma estrela no Beadbox no GitHub.
