Desenvolvimento guiado por especificação: a prática na qual a categoria convergiu

Todas as ferramentas sérias de programação com IA publicaram o mesmo recurso com menos de um ano de diferença entre si, algo que quase nunca acontece por acidente.

Em 2025 a pergunta interessante era quanto os modelos estavam melhorando. Em 2026 a pergunta interessante é o que você entrega a eles.

O GitHub publicou o Spec Kit. A AWS publicou o Kiro, um IDE construído em torno da ideia. BMAD-METHOD, OpenSpec e Tessl tentaram cada um por conta própria. O Cursor chegou lá através dos arquivos de regras. Martin Fowler publicou uma comparação das implementações. Quando seis times independentes convergem para a mesma resposta em doze meses, eles não estão se copiando. Todos estão batendo no mesmo muro.

O muro já tem nome. E a solução também.

O que é realmente o desenvolvimento guiado por especificação

Escreva os requisitos, as restrições e os critérios de sucesso antes de gerar qualquer código. Trate esse documento como a fonte da verdade. Deixe o agente construir contra ele.

É isso. Não é uma ideia nova: é engenharia de requisitos, algo que a indústria passou trinta anos fazendo mal e depois abandonou em boa medida por ser lento demais. O que mudou não é o conceito. É a economia.

Especificações eram caras de escrever e caras de manter atualizadas, o que significava que a maioria dos times escrevia as linhas gerais e descobria todo o resto na revisão de código. Essa era uma troca racional quando construir o recurso levava três semanas de qualquer forma. Deixou de ser racional quando a geração ficou rápida, porque agora a especificação é a parte lenta, e a parte lenta é onde vive todo o julgamento.

O modo de falha contra o qual foi inventado

As ferramentas que começam pelo prompt pulam a especificação completamente. Você descreve um resultado, a ferramenta produz algo parecido, e cada decisão que a descrição não cobriu é tomada pelo gerador em silêncio.

Quais decisões? As que acabam importando. Se um endereço de e-mail é único, e único em relação a quê. O que uma conta cancelada ainda pode ver. O que acontece quando duas pessoas editam o mesmo registro. Se aquela lista precisa de paginação antes de ter dez mil linhas.

Ninguém fez essas perguntas, então ninguém as respondeu, mas a aplicação tem uma resposta para cada uma, escolhida por inferência a partir de um contexto que nunca incluiu o seu negócio.

A mesma dinâmica aparece em toda ferramenta que pula a etapa de definição. É o mecanismo atrás do problema dos 70%: o progresso empaca não porque o trabalho restante seja difícil, mas porque está bloqueado por uma decisão arquitetônica tomada de forma implícita, centenas de gerações antes, que já não pode ser mudada sem desmontar o sistema.

Os dados do que acontece sem isso

O relatório State of AI-assisted Software Development da DORA de 2025 é a leitura mais clara disponível. 90% dos profissionais de tecnologia já usam IA no trabalho e mais de 80% acreditam que ela aumentou sua produtividade. E uma maior adoção de IA está associada a um aumento do desempenho de entrega de software e a um aumento da instabilidade dessa entrega, ao mesmo tempo.

Mais rápidos ao lançar. Piores ao manter as coisas funcionando. As duas coisas, juntas.

A análise da GitClear de 2026 sobre 623 milhões de mudanças de código mostra a forma do dano. Contra a linha de base de 2023: blocos de código duplicados 81% acima, o copiar e colar dentro de um mesmo commit subindo de 9,4% em 2022 para 15,7% no primeiro semestre de 2026, construções que mascaram erros 47% acima. Enquanto isso, chamadas de função entre arquivos (o melhor indicador disponível de reutilização de código) 35% abaixo, e a atividade de refatoração despencando de 21% das mudanças em 2022 para 3,8% em 2026.

Quem desenvolve tem agora cerca de cinco vezes mais probabilidade de copiar e colar do que de refatorar. Em 2022 essa proporção ia no sentido contrário.

Nada disso é um problema de qualidade do modelo. É o que acontece quando gerar é barato e a estrutura não é o trabalho explícito de ninguém.

Os três graus de compromisso

Não todo mundo quer dizer a mesma coisa com isso, e as diferenças importam na prática. O enquadramento de Martin Fowler é o mais limpo que já vi.

Especificação primeiro. Você escreve a especificação, gera a partir dela e depois mantém o código à mão. A especificação dirige a construção inicial e depois vira aos poucos documento histórico. O mais fácil de adotar, as garantias mais fracas: seis meses depois, o documento descreve um sistema que já não existe.

Especificação ancorada. A especificação e o código evoluem juntos. Você muda a especificação, regera as partes afetadas, mantém as duas atualizadas. Mais disciplina, e a recompensa é que o documento continua confiável.

Especificação como fonte. A especificação é o único artefato que você edita. O código é saída, assim como um binário compilado é saída: você não o remenda à mão. As garantias mais fortes, e o maior salto em como um time trabalha.

A maioria dos times que se chama guiado por especificação está fazendo especificação primeiro. Isso é uma melhoria real sobre lançar prompts no escuro, e é também a versão que se degrada em silêncio.

O que vai na especificação

O teste útil: se o gerador teria que adivinhar, vai no documento.

• O modelo de dados. Entidades, relações, cardinalidade, o que torna um registro único, o que acontece ao excluir. É a seção de maior valor e a que mais frequentemente é pulada.
• Tipos de usuário e permissões. Quem existe, o que cada um pode ver e fazer, o que acontece nas fronteiras.
• Os invariantes. Regras que nunca devem ser violadas, ditas sem rodeios. Não “tratar os erros com elegância”: isso é um desejo, não uma restrição.
• Critérios de sucesso. Como você vai saber que a coisa funciona, em termos concretos o suficiente para que uma discordância sobre se funciona seja resolvível.

O que não vai: detalhe de implementação que o gerador escolhe melhor que você. Uma especificação que nomeia variáveis não é uma especificação, é código com ferramentas piores.

A parte que todo mundo erra

Uma especificação só ajuda se puder ser aplicada em algum lugar que não seja a prosa.

Se uma restrição vive apenas no documento, é uma sugestão. O gerador leu uma vez e pode ter respeitado ou não no décimo quarto arquivo que tocou. As restrições precisam terminar em algum lugar que o sistema verifique: not-null e unique no banco de dados e não em um manipulador de formulário, tipos nas fronteiras e não em um comentário, autorização como uma política que o sistema avalia e não como uma condição que alguém lembrou de escrever.

Essa é a diferença entre desenvolvimento guiado por especificação como prática e desenvolvimento guiado por especificação como gênero literário. O documento é como você decide. A aplicação efetiva é como você mantém a decisão.

Como saber se você está realmente praticando

Quatro perguntas, e são incômodas de propósito.

1. Quando algo quebra, você conserta o código ou a especificação? Se a resposta é sempre o código, você está fazendo especificação primeiro na melhor das hipóteses e o documento já está obsoleto.
2. Alguém novo conseguiria ler a especificação e prever como o sistema se comporta? Se essa pessoa teria que ler o código para saber, a especificação é um resumo e não uma fonte.
3. Existe algo na especificação que o sistema não pode violar? Se todas as regras são prosa, nenhuma está garantida.
4. Você revisa a especificação ou o diff? Revisar milhares de linhas de código gerado é teatro. Discuta sobre o documento enquanto discutir ainda é barato.

Onde isso deixa as ferramentas

A maioria das implementações atuais é guiada por especificação para a geração de código especificamente. Elas produzem uma especificação e geram uma implementação contra ela, e o artefato sobre o qual operam é uma base de código.

A versão mais difícil estende a mesma lógica a toda a aplicação (o modelo de dados, a superfície de API, a fronteira de autenticação, a interface) de modo que a especificação cobre não só o que o código faz mas o que o sistema é. É isso que a fase de blueprint do Archie é, e é por isso que eu a descrevo como desenvolvimento guiado por especificação aplicado à stack completa em vez de a um repositório. Escopo diferente, mesmo princípio: definir antes de gerar.

Pessoas razoáveis discordam sobre até onde levar. Ninguém sério defende voltar atrás.

Quanto custa

Adiantar o julgamento é mais lento na primeira semana de um projeto e mais rápido em todas as semanas seguintes. Esse custo é real e é pago exatamente no momento em que o impulso parece mais valioso, enquanto um concorrente lança algo visível. Vão existir sprints em que o time que pulou isso parece estar ganhando.

A disciplina também se degrada. Escrever restrições é menos divertido que ver uma interface aparecer, e revisar um documento é menos satisfatório que revisar código. Esses hábitos se erodem sob pressão de prazo, que é a mesma pressão que os faz importar.

E genuinamente não se aplica a tudo. Se você está validando uma ideia neste fim de semana com intenção de jogar o resultado fora, jogue fora. Nada disso vale a pena para software com dois dias de vida.

A razão pela qual isso pegou

Toda tentativa anterior de fazer os times escreverem especificações primeiro fracassou, e fracassou por uma boa razão: a especificação era sobrecarga em cima do trabalho real. Você escrevia o documento e depois ainda tinha que construir a coisa.

Essa já não é a troca. Agora o documento é a maior parte do trabalho, e a construção é a parte barata. Seis times independentes perceberam isso em menos de um ano porque era a consequência óbvia de o modelo ter ficado bom.

A prática não ganhou uma discussão. A economia se moveu por baixo.

Leituras relacionadas

O diagnóstico original: o vibe coding quebrou sua promessa. Para onde a categoria foi depois: o que vem depois do vibe coding. O mesmo argumento aplicado a sistemas completos: design de software AI-first a partir de primeiros princípios. E o enquadramento mais antigo da mesma ideia: parar de escrever o software duas vezes.

Perguntas frequentes

O que é desenvolvimento guiado por especificação? Escrever os requisitos, as restrições e os critérios de sucesso antes de gerar qualquer código, e tratar essa especificação como a fonte da verdade contra a qual o agente de IA constrói. Surgiu em 2025 e 2026 como resposta direta aos fluxos de trabalho que começam pelo prompt e pulam a etapa de definição.

Em que se diferencia dos documentos de requisitos tradicionais? O conceito é o mesmo; a economia não. Especificações tradicionais eram caras o suficiente para que os times escrevessem as linhas gerais e descobrissem o resto durante a implementação. Quando redigir uma leva horas em vez de meses e pode ser revisada de forma barata, vale a pena terminá-la e vale a pena mantê-la atualizada.

Quais ferramentas suportam o desenvolvimento guiado por especificação? GitHub Spec Kit, AWS Kiro, BMAD-METHOD, OpenSpec e Tessl são as implementações com nome, e o Cursor suporta uma versão mais leve através de arquivos de regras. Diferem sobretudo em quão forte é a ligação entre a especificação e o código: se dirige a geração uma vez, se evolui junto com ele, ou se é o único artefato que você edita.

Quais são os três graus do desenvolvimento guiado por especificação? Especificação primeiro, onde a especificação dirige a construção inicial e você mantém o código à mão. Especificação ancorada, onde especificação e código evoluem juntos. Especificação como fonte, onde a especificação é a única coisa que você edita e o código é tratado como saída. A maioria dos times que pratica está fazendo especificação primeiro.

O desenvolvimento guiado por especificação freia os times? Ele realoca o trabalho em vez de adicioná-lo. As decisões de uma especificação são tomadas ou deliberadamente no início ou de forma implícita por um gerador que adivinha depois, e o segundo caminho é de onde vem o retrabalho. É mais lento na primeira semana e mais rápido depois.

O que deveria ir em uma especificação? Qualquer coisa que o gerador teria que adivinhar de outra forma: o modelo de dados com relações e regras de unicidade, os tipos de usuário e permissões, os invariantes que nunca devem ser violados, e critérios de sucesso concretos o suficiente para encerrar uma discordância. Deixe de fora o detalhe de implementação que o gerador escolhe melhor que você.

Desenvolvimento guiado por especificação é o mesmo que design AI-first? Desenvolvimento guiado por especificação é a prática de definir antes de gerar. Design AI-first é o conjunto mais amplo de consequências arquitetônicas, que cobre também onde as restrições são aplicadas, a ordem em que você toma as decisões e projetar para consumidores agênticos além dos humanos.