Em fevereiro de 2025, Andrej Karpathy publicou um tweet com uma frase que pegou: “Existe um novo tipo de programação que eu chamo de vibe coding, em que você se entrega totalmente às vibes, abraça as exponenciais e esquece que o código sequer existe.” Ele estava sendo meio sério. O tweet tem 4,5 milhões de visualizações, e Karpathy depois chamou aquilo de “um devaneio de banho para jogar fora”. A frase não foi jogada fora: virou o termo que resume um modo de falha inteiro.
A falha é mais ou menos assim. Um engenheiro sênior manda um prompt para o agente: “Construa um fluxo de checkout com Stripe, autenticação e confirmação por e-mail.” O agente roda por 35 minutos, altera quarenta e sete arquivos e produz 3.200 linhas de código.
O engenheiro abre o diff e descobre que parte funciona, parte não compila, a integração com o Stripe usa uma API depreciada, a lógica de confirmação por e-mail aponta para um serviço que não existe e o fluxo de autenticação parece correto, mas ignora o rate limiter silenciosamente. Nada disso é pego no code review, porque simplesmente há coisa demais para ler.
A reação da maioria dos times é frear o agente: prompts menores, supervisão mais próxima, uma volta ao pair programming da segunda era com passos extras. Não é esse o caminho. O caminho é escrever a spec antes de o agente rodar, não na conversa, mas no repositório, em um arquivo markdown, com detalhe suficiente para que o agente, o próximo engenheiro, o gate de QA e o revisor trabalhem todos a partir da mesma fonte de verdade.
Isso é Spec-Driven Development (SDD), a disciplina mais útil que adotei na Cheesecake Labs e que já vi cortar pela metade o cycle time de features no tipo certo de trabalho.
There's a new kind of coding I call "vibe coding", where you fully give in to the vibes, embrace exponentials, and forget that the code even exists. It's possible because the LLMs (e.g. Cursor Composer w Sonnet) are getting too good. Also I just talk to Composer with SuperWhisper…
— Andrej Karpathy (@karpathy) February 2, 2025
As seis formas como os agentes falham em escala
Antes de falar do que o Spec-Driven Development resolve, quero ser específico sobre os modos de falha que ele tenta endereçar. A maioria dos times fala de “agentes pouco confiáveis” como se fosse um problema só. São seis.
O primeiro é o herói de uma tacada só: o agente tenta construir a feature inteira em uma única janela, estoura o orçamento de contexto, começa a perder coerência depois de 200K tokens e entrega algo que parece pronto, mas quebra na integração. É assim que o vibe coding se parece de perto.
O segundo é a vitória prematura. O agente declara a tarefa concluída com pedaços importantes faltando: entregou o happy path, pulou o tratamento de erro e se deu por completo. Você descobre as lacunas no QA ou, pior, em produção.
O terceiro é a amnésia entre sessões. Uma janela nova não tem nenhuma memória do que veio antes, então decisões tomadas ontem precisam ser redescobertas hoje, restrições que levaram trinta minutos para serem articuladas somem no prompt seguinte e você paga duas vezes pelo mesmo raciocínio.
O quarto é o falso pronto. O agente rodou um comando curl, recebeu uma resposta 200 e considera a integração funcionando. Ele não testa os caminhos infelizes, não valida o contrato e segue em frente depois de ver um código HTTP de sucesso. O bug vai para produção.
O quinto é a autoavaliação: o mesmo agente que implementou a feature também decide se ela está completa. O executor aprova a si mesmo, estruturalmente o mesmo conflito de interesse de um desenvolvedor revisando o próprio pull request, com o agravante de que o agente não tem reputação profissional a proteger.
O sexto é o acúmulo de slop. Cada feature isolada compila, passa nos testes e vai para produção, mas a arquitetura se desvia e as convenções se degradam. Depois de 100 features construídas assim, a base de código é tecnicamente funcional e estruturalmente lixo. O agente não violou nenhuma regra explicitamente, ele simplesmente nunca teve uma regra para seguir.
Nada disso é teórico. Vemos os seis em clientes, muitas vezes no mesmo projeto, e não é o agente sendo ruim no que faz. São modos de falha previsíveis de execução sem supervisão. O SDD ataca os três primeiros diretamente e cria as condições para o sistema lidar com os outros três.
Leia mais: As três eras do software: do autocomplete ao desenvolvimento agêntico
O que é, de fato, Spec-Driven Development
Spec-Driven Development (SDD) é a prática de escrever uma especificação estruturada no repositório, em markdown versionado, antes de o agente escrever uma única linha de código. São quatro fases, com nomes que variam de toolkit para toolkit, mas com um formato que se mantém.
Fase um, Specify: você senta com um agente em plan mode e escreve a spec. Não “construa um fluxo de checkout”, mas uma spec de verdade: qual é o problema do usuário, quem está no escopo, quais são os critérios de aceite, o que está explicitamente fora do escopo, quais edge cases importam. A saída é um arquivo markdown, normalmente spec.md, que o engenheiro e o agente acordam antes de qualquer outra coisa acontecer.
Fase dois, Design. A partir da spec, o agente propõe uma arquitetura, uma sequência de operações, o modelo de dados, os componentes, os contratos de API e as decisões principais. A saída é o design.md. O humano revisa, contesta o que está errado e confirma o que está certo.
Fase três, Tasks. O design é decomposto em tarefas atômicas e ordenadas: cada uma pequena o suficiente para caber em uma única janela de contexto com folga, cada uma com critérios de aceite claros, cada uma testável de forma independente. A saída é o tasks.md.
Fase quatro, Execute. Subagentes pegam tarefas da lista, implementam e atualizam o estado. Cada um roda em uma janela nova, lê a spec, o design e a tarefa correspondente, e produz código apenas para aquela tarefa. O estado do trabalho vive no tasks.md, não na memória de nenhum agente.
As mesmas quatro fases aparecem com nomes diferentes nas ferramentas. O AWS Kiro usa Requirements, Design, Tasks (e escreve os requisitos em notação EARS, “WHEN [condition] THE SYSTEM SHALL [behavior]”). O GitHub Spec Kit usa Spec, Plan, Tasks, Implement. O que usamos na Cheesecake Labs segue Specify, Design, Tasks, Execute e ajusta automaticamente a profundidade de cada fase à complexidade do trabalho. As diferenças são reais, mas não são estratégicas. Escolha uma. Use.
Por que escrever a spec em um arquivo muda tudo
A maioria dos engenheiros com quem converso concorda com a ideia de escrever uma spec e segue fazendo o trabalho no chat. A “spec” vive na conversa. O entendimento que o agente de Inteligência Artificial tem da feature vive na cabeça do agente. Nada é durável.
A maioria dos engenheiros com quem converso concorda com a ideia de escrever uma spec e segue fazendo o trabalho no chat. A “spec” vive na conversa, o entendimento que o agente tem da feature vive na cabeça do agente e nada é durável. O insight do SDD que eu quero que todo engenheiro internalize é este: a spec é o artefato, não a conversa.
Três coisas mudam no instante em que a spec vira um arquivo no repositório.
A spec sobrevive à sessão
O próximo agente que pega uma tarefa lê a spec. O próximo engenheiro que entra no projeto lê a spec. O agente de QA que valida a implementação lê a spec. Quem revisa o pull request lê a spec. Todo mundo recebe a mesma fonte de verdade e você para de pagar três vezes pela mesma conversa.
A spec é revisável
Um pull request com cinco arquivos de código é difícil de revisar; um pull request que diz “implementa a tarefa 4 de docs/specs/checkout.md” é fácil de revisar contra a intenção original. Quem revisa lê o que foi acordado, lê o diff e pergunta se um bate com o outro. A conversa sobe um nível: sai do linha a linha e vai para intenção versus implementação.
A spec é combinável
Você pode ter um agente especificando, outro desenhando, um terceiro quebrando em tarefas, um quarto implementando e um quinto julgando, com a entrada e a saída de cada agente sendo um arquivo markdown ou código. O pipeline inteiro é só arquivos, e é assim que um único engenheiro consegue mudar noventa arquivos em uma feature sem nunca passar de 50K tokens em nenhuma janela.
Sean Grove (OpenAI) fez a versão mais provocativa desse argumento na palestra dele na AI Engineer World’s Fair no ano passado. A tese: “o código que você escreve representa só 10% a 20% do valor que você entrega como programador; os outros 80% a 90% estão na comunicação estruturada.” Para ele, a spec é o produto de verdade e o código é a saída compilada. O SDD é a implementação prática dessa ideia.
Ou, como o time do GitHub Spec Kit coloca no toolkit open source deles, o modelo mental central é “especificações não servem ao código, o código serve às especificações”. A hierarquia é o oposto do que a maioria dos engenheiros internalizou nos últimos vinte anos.
Leia mais: Agent Skills: pare de enfiar workflows no seu arquivo de regras
Os toolkits de SDD
Não existe um motivo forte para preferir um toolkit de SDD a outro, todos funcionam, e a decisão mais importante é escolher um e manter a consistência.
O AWS Kiro é a IDE spec-driven da Amazon. Entrou em preview em 15 de julho de 2025, chegou à disponibilidade geral em 17 de novembro de 2025 e o time do lançamento reportou mais de 250.000 desenvolvedores nos três primeiros meses. Ele é opinativo quanto ao workflow (três arquivos, notação EARS para requisitos, design estruturado com diagramas de sequência, tarefas rastreáveis) e, se você quer o workflow de spec embutido na IDE sem precisar pensar no harness, o Kiro é o caminho mais simples.
O GitHub Spec Kit é a alternativa open source: licença MIT, compatível com mais de 30 agentes de IA de programação, incluindo Claude Code, Copilot e Gemini CLI. O workflow segue Spec, Plan, Tasks, Implement, e o repositório traz templates, slash commands e um documento de metodologia chamado spec-driven.md que vale a leitura mesmo que você não adote o toolkit. A vantagem é a portabilidade: suas specs não ficam presas dentro de uma IDE específica.
Onde o SDD sozinho não dá conta
O SDD ataca diretamente o herói de uma tacada só, a vitória prematura e a amnésia entre sessões. A spec impede que o agente tente construir a feature inteira em uma janela. A quebra em tarefas evita a vitória prematura, porque cada tarefa tem critérios de aceite. Os arquivos markdown resolvem a amnésia entre sessões ao persistir decisões fora da memória de qualquer agente.
O que o SDD não resolve sozinho é o falso pronto, a autoavaliação e o acúmulo de slop. Esses não são problemas de spec, são problemas de execução e de revisão.
O falso pronto se resolve com gates de conclusão que o agente não consegue burlar: lint, typecheck e testes em todo commit; cobertura de diff que verifica se o diff de fato atende à spec; uma checagem de fidelidade que compara a implementação com o design. Nada disso faz parte da spec, faz parte do harness.
A autoavaliação se resolve com um agente juiz separado. O executor entrega a implementação e um segundo modelo, sem nenhum contexto além da spec e do diff, avalia se a implementação atende aos critérios de aceite. O executor não pode dar nota para si mesmo. Chamamos isso de LLM-as-Judge (o padrão original de Zheng et al., 2023) e, na Cheesecake Labs, rodamos em todo PR não trivial.
O acúmulo de slop se resolve com convenções arquiteturais codificadas no harness: arquivos CLAUDE.md na raiz do projeto capturando convenções, skills que codificam a forma certa de fazer tarefas comuns e agentes de code review que fazem valer tudo isso. Sem isso, até uma spec perfeita acaba executada de um jeito que desvia a arquitetura.
Kief Morris, da Thoughtworks, tem o enquadramento mais limpo para isso. No texto dele de março de 2026, “Humans and Agents in Software Engineering Loops”, ele distingue três papéis. “In the loop” é o engenheiro que revisa cada saída do agente linha a linha, o gargalo. “On the loop” é o engenheiro que projeta e mantém os mecanismos que guiam e validam o comportamento do agente, construindo o harness, incluindo o workflow de spec e os gates.
“Out of the loop” é o caso em que o harness está maduro o suficiente para o agente rodar de forma bastante autônoma, com o humano auditando resultados agregados. O SDD é o que leva você de “in the loop” para “on the loop”. O harness é o que leva você a “out of the loop” com segurança. SDD sem harness deixa você com uma pilha de specs bem escritas que continuam sendo entregues erradas.
Como eu uso Spec-Driven Development
Quatro movimentos para colocar na mesa neste trimestre.
Primeiro, escolha um toolkit de SDD e padronize nele. Seja o Kiro, o Spec Kit ou um conjunto de skills internas, o erro é deixar cada engenheiro inventar o próprio workflow de spec. Comprometa-se com um formato só e use para tudo que passe de um limite definido: no nosso caso, “qualquer coisa que toque mais de dois arquivos”. A variação que você elimina ao padronizar vale mais do que a variação que você preserva ao continuar flexível.
Versione as specs no repositório. Toda spec aprovada fica em docs/specs/<feature>/ com spec.md, design.md e tasks.md. Os pull requests referenciam a spec que implementam, e a spec passa pelo code review como o código passa. Só esse movimento já torna o planejamento do time inteiro legível para ele mesmo e para quem for contratado depois.
Adicione os gates de conclusão em ordem de custo. Lint, typecheck e testes em todo PR são o mínimo. Depois, cobertura de diff que verifica se a implementação tocou os arquivos certos, uma checagem de fidelidade comparando a implementação com o design e um agente juiz que avalia contra os critérios de aceite da spec. Os filtros baratos rodam primeiro; o agente juiz roda só nos PRs que passam por eles.
Por último, separe o executor do juiz. Nenhum agente dá nota para o próprio trabalho, ou seja, o agente que implementou a feature não é quem declara que ela está pronta. Um modelo separado, de preferência diferente (rodamos Opus 4.7 como juiz sobre implementações feitas com Sonnet 4.6), lê a spec e o diff e produz um aceite ou uma rejeição explícita, com justificativa. O executor recebe a rejeição e tenta de novo com o feedback. Esse é o movimento de maior alavancagem que você pode fazer na qualidade do output.
A ordem importa: coloque o workflow de spec em pé primeiro, porque tanto os gates quanto o juiz dependem de existir uma spec para validar. Sem a spec, os gates não têm o que checar.
Para fechar
Os agentes disponíveis em 2026 são bons. O gargalo é o sistema ao redor: como a intenção é capturada, como a conclusão é verificada e como a arquitetura se mantém coerente ao longo de centenas de features. As specs são a alavanca mais barata desse sistema.
Custam minutos para escrever, sobrevivem às sessões e viabilizam todos os outros gates. Se o seu time ainda não fez a passagem de “spec no chat” para “spec no repositório”, esse é o trabalho dos próximos trinta dias. Depois vem o harness.
