Vibe coding se popularizou como jeito de construir software com IA. Você descreve, o agente gera, você roda. Funciona, e é divertido. O aperto costuma chegar quando aquele código precisa ir para produção.
Nos dois artigos anteriores, falamos do ambiente de execução (harness) e do que entra no modelo (context). Este fecha o primeiro bloco da série com a pergunta que vem antes dessas duas: o que estamos construindo, afinal? Spec-driven development é a aposta de que essa resposta merece um artefato próprio, escrito antes do código.
De onde veio o vibe coding
O termo nasceu em um tweet de Andrej Karpathy, em 2 de fevereiro de 2025:
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. […]
Na transcrição completa do tweet, que Simon Willison reproduz em seu blog, Karpathy descreve o resto do fluxo. Ele aceita todos os diffs sem ler e cola mensagens de erro sem comentário, o que em geral resolve. Às vezes o LLM não consegue corrigir um bug; ele então contorna, ou pede mudanças aleatórias até o problema sumir.
A ressalva já estava no tweet original; foi ela que se perdeu na popularização. Karpathy avalia o resultado como “not too bad” para projetos descartáveis de fim de semana, e fecha com “it’s not really coding”.
Willison, em março de 2025, já reclamava da diluição do termo. Para ele, vibe coding é especificamente não ler o código. Se um LLM escreveu o código, mas você revisou, testou e consegue explicar como funciona, isso não é vibe coding. É desenvolvimento de software, e o uso do LLM é detalhe.
Um ano depois, o próprio autor revisitou o termo
Em 4 de fevereiro de 2026, dois dias depois de o tweet original completar um ano, Karpathy publicou uma retrospectiva no X. Ele descreve o original como “a shower of thoughts throwaway tweet”, disparado sem pensar.
O balanço dele sobre o presente:
Today (1 year later), programming via LLM agents is increasingly becoming a default workflow for professionals, except with more oversight and scrutiny. […]
O objetivo, diz ele na sequência, é capturar a alavancagem dos agentes “without any compromise on the quality of the software”. Para esse fluxo profissional, ele diz preferir outro nome, “agentic engineering”. No trecho reproduzido pelo The New Stack:
‘agentic’ because the new default is that you are not writing the code directly 99% of the time, you are orchestrating agents who do and acting as oversight […]
A conexão com spec é nossa, não dele: oversight e scrutiny precisam de um referencial. Comparar o resultado com o quê? Spec-driven development propõe um artefato escrito como esse referencial.
O problema: código sem contrato
O blog de lançamento do Kiro, o IDE da AWS construído em torno de specs, abre com o cenário exato:
I’m sure you’ve been there: prompt, prompt, prompt, and you have a working application. It’s fun and feels like magic. But getting it to production requires more. What assumptions did the model make when building it? You guided the agent throughout, but those decisions aren’t documented. Requirements are fuzzy and you can’t tell if the application meets them. […]
O GitHub, no post de lançamento do Spec Kit, dá o diagnóstico técnico. Modelos são excepcionais em completar padrões, não em ler mentes. Um prompt vago como “adicione compartilhamento de fotos ao meu app” força o modelo a chutar potencialmente milhares de requisitos não declarados. O modelo faz suposições razoáveis, algumas erradas. E você costuma descobrir quais só no meio da implementação.
O prompt não foi feito para ser documentação. As decisões que o modelo tomou não ficam documentadas, aponta o texto do Kiro. Sem um artefato explícito, o código tende a virar o único registro. E quando o comportamento diverge do que você queria, pode não existir registro algum do que “certo” significava.
Em maio de 2026, o time do Kiro voltou ao tema com uma taxonomia de bugs de requisito: nível de detalhe errado, ambiguidade, inconsistência e incompletude. O post é direto sobre o novo cenário: “the prompt you give to the agent is the de-facto requirement now”. Prompt vago produz spec vaga. E o agente que implementa essa spec produz código cheio de decisões não declaradas, tomadas em seu nome.
O que é spec-driven development
Birgitta Böckeler, da Thoughtworks, analisou as ferramentas da área. Ela nota que a definição ainda está em fluxo, mas resume o uso corrente: spec-driven development significa escrever uma spec antes de escrever código com IA. A spec vira a fonte de verdade para o humano e para a IA.
O documento de metodologia do Spec Kit descreve a mudança com ambição:
In this new world, maintaining software means evolving specifications. […] The lingua franca of development moves to a higher level, and code is the last-mile approach.
Böckeler observa que, na prática, o termo cobre três níveis diferentes de implementação:
| Nível | O que significa |
|---|---|
| Spec-first | Uma spec bem pensada é escrita antes e usada no workflow da tarefa em questão. |
| Spec-anchored | A spec fica após a tarefa e evolui junto com a feature. |
| Spec-as-source | O humano edita só a spec e nunca toca o código, que vira artefato gerado. |
Tabela adaptada das definições dela.
O teste que ela fez à época a levou a achar que o Spec Kit ainda era spec-first apenas, não spec-anchored ao longo do tempo. O Tessl é a única das três ferramentas que aspira explicitamente ao spec-anchored, e chega a explorar o spec-as-source. A documentação do Tessl, citada por ela, define specs, não código, como o artefato primário.
Para o spec-as-source em particular, Böckeler aponta um paralelo com o model-driven development (MDD), que nunca decolou para aplicações de negócio. LLMs removem parte do overhead e das restrições do MDD, mas ela aponta o preço: o não determinismo dos LLMs. E deixa a dúvida registrada: spec-as-source, e até spec-anchored, podem acabar herdando as desvantagens dos dois mundos, inflexibilidade e não determinismo.
A família do spec-driven development continuou crescendo em 2026. Em abril, o martinfowler.com publicou o Structured-Prompt-Driven Development (SPDD), método do time interno de TI da Thoughtworks. A variação: o artefato de primeira classe é o prompt estruturado, versionado junto com o código e usado para alinhar o desenvolvimento com o negócio. Os nomes mudam, mas o movimento é o mesmo: dar à intenção um artefato revisável, separado do código.
Como as ferramentas implementam spec-driven development
Spec Kit: um pipeline de comandos
O Spec Kit é um toolkit open source do GitHub. No lançamento, em setembro de 2025, ele funcionava com agentes como GitHub Copilot, Claude Code e Gemini CLI. Em julho de 2026, o README lista integrações com mais de 30 agentes de código. O post de lançamento descreve o processo em quatro fases com checkpoints claros: specify, plan, tasks e implement. O README atual organiza isso em comandos, um núcleo central mais comandos opcionais de qualidade:
/speckit.constitution -> /speckit.specify -> [/speckit.clarify]
| | |
project principles what and why resolve ambiguity
-> /speckit.plan -> /speckit.tasks -> [/speckit.analyze] -> /speckit.implement
| | | |
tech choices task breakdown cross-check specs executionFluxo adaptado do README do Spec Kit. Comandos entre colchetes são opcionais: o README recomenda clarify antes do plano, e analyze depois das tarefas.
A separação de responsabilidades sustenta o pipeline. Na fase de spec, o foco é o quê e o porquê, sem stack, sem API, sem estrutura de código. A stack entra só no /plan. O /clarify existe para atacar as áreas subespecificadas antes do plano. E o /analyze cruza spec, plano e tarefas procurando inconsistência antes de qualquer código.
O /speckit.checklist, também opcional, gera checklists de qualidade para validar completude e clareza dos requisitos. O README descreve a ideia como “unit tests for English”: testes unitários para a prosa da spec.
Kiro: três arquivos por feature
O Kiro estrutura cada spec em três arquivos:
requirements.md: user stories com critérios de aceitaçãodesign.md: arquitetura técnica, diagramas de sequência, considerações de implementaçãotasks.md: plano de implementação em tarefas discretas e rastreáveis
Os critérios de aceitação usam notação EARS (Easy Approach to Requirements Syntax). O exemplo do blog de lançamento: o prompt “Add a review system for products” vira user stories para visualizar, criar, filtrar e avaliar reviews. Cada user story sai com critérios de aceitação cobrindo edge cases. O objetivo declarado é tornar explícitas as suposições do prompt.
O Kiro saiu de preview para disponibilidade geral em 17 de novembro de 2025. O anúncio de GA parte do que chama de problema fundamental da geração de código com IA: “how do you know the code actually does what you specified?”. A resposta deles é property-based testing para “spec correctness”. O Kiro extrai propriedades dos requisitos em EARS e gera testes com entradas aleatórias contra essas propriedades. O argumento do anúncio: testes de exemplo checam só os casos que alguém lembrou de escrever; propriedades testam contra o comportamento declarado na spec.
As duas ferramentas compartilham o mesmo mecanismo: transformar um prompt curto em artefatos revisáveis antes da implementação. A aposta declarada pelo GitHub é trocar a revisão de “thousand-line code dumps” pela revisão de mudanças focadas, guiadas por tarefa. Se essa conta fecha na prática é o assunto da próxima seção.
Onde o entusiasmo encontra a prática
Böckeler testou as ferramentas e documentou as arestas. São relatos exploratórios, não um estudo controlado. Ainda assim, valem como contrapeso aos posts de lançamento.
Ao pedir para o Kiro corrigir um bug pequeno, o workflow virou, nas palavras dela, uma marreta para quebrar uma noz. O documento de requisitos transformou o bug em 4 user stories com 16 critérios de aceitação no total. Incluindo pérolas como uma user story sobre “handle edge cases gracefully” para uma função de transformação.
Com o Spec Kit, ela relata a mesma dúvida de calibragem: qual tamanho de problema justifica o processo? Os tutoriais disponíveis partem de aplicações criadas do zero, porque é o que funciona em tutorial. Em uma feature de tamanho médio, dependente de código existente, a quantidade de passos e de arquivos markdown para revisar pesou. No resumo dela sobre os artefatos gerados: “very verbose and tedious to review”.
A observação estrutural dela: Kiro, Spec Kit e Tessl se rotulam como spec-driven development, mas são bem diferentes entre si. SDD não é uma coisa só. Quando alguém defender ou atacar a sigla perto de você, vale perguntar qual dos três níveis está em discussão.
Em março de 2026 apareceu evidência publicada na mesma direção. Um experience report no arXiv documenta um time full-stack pequeno construindo dois sistemas sob restrições de produção, com prompting contextual e restrições arquiteturais explícitas. O vibe coding acelerou scaffolding e integração. Mas o código gerado com frequência subespecificava regras de isolamento e restrições de infraestrutura quando elas não estavam definidas explicitamente. Os autores observam o esforço de engenharia migrando do boilerplate para “constraint specification and enforcement auditing”. E nomeiam “non-delegation zones”: áreas arquiteturais onde a geração conversacional de código segue insuficiente para confiabilidade de produção.
Nem tudo precisa de spec
A resposta para “vibe coding ou spec-driven development?” não é binária. Willison propõe uma regra de ouro pessoal para código de produção: não commitar nada que ele não consiga explicar exatamente o que faz para outra pessoa.
Böckeler estrutura a decisão como avaliação de risco em três dimensões:
- Probabilidade: qual a chance de a IA errar nessa tarefa?
- Impacto: se errar e você não notar, qual a consequência?
- Detectabilidade: quão fácil é perceber o erro?
Os extremos ilustram a escala. Probabilidade baixa, impacto baixo e detectabilidade alta: vibe coding está ok, nem precisa ler o código. Probabilidade alta, impacto alto e detectabilidade baixa: revisão pesada, assuma que a IA pode ter errado. A maioria dos casos reais fica no meio. Ela não conecta esse framework a specs; a conexão aqui é nossa. Nesse raciocínio, a spec entra como uma das mitigações possíveis para os casos de maior risco.
Dois sanity checks dela para a dimensão de impacto:
- Você faria deploy disso se estivesse de plantão hoje à noite?
- Esse código tem raio de impacto alto, usado por muitos componentes ou consumidores?
Como começar com spec-driven development
Não precisa adotar um IDE novo nem um framework inteiro para testar spec-driven development. O caminho incremental:
- Na próxima feature não trivial, escreva o que ela deve fazer antes de abrir o agente. Uma página, linguagem natural, foco em comportamento e edge cases.
- Peça para o agente criticar a spec antes de implementar: o que está ambíguo, o que está faltando. É o papel do
/clarifydo Spec Kit, e funciona sem o Spec Kit. - Só depois peça o plano técnico, e só depois o código.
- Compare o resultado com a spec, não com a sua memória do que você pediu.
- Se a feature vai evoluir, guarde a spec no repositório junto com o código.
- Bug pequeno e óbvio? O processo completo dificilmente se justifica. No teste da Böckeler, virou marreta em noz.
- Quando o fluxo manual ficar repetitivo, aí sim avalie Spec Kit, Kiro ou equivalente.
Três ângulos da mesma mudança
Os três primeiros artigos desta série descrevem a mesma mudança por ângulos diferentes. O harness define onde o agente trabalha e o que ele pode fazer. O context engineering define o que entra no modelo a cada passo. A spec define o contrato do que deve ser construído, antes de qualquer token de código.
O código sempre teve dono: o compilador executa, o humano lê. Em workflows onde o agente escreve a maior parte do código, a pergunta “o que é a fonte de verdade?” fica aberta. No vibe coding, por definição, o código nem é lido; o contrato fica implícito no histórico do chat. Spec-driven development responde com um documento que humano e modelo leem. Entre os dois extremos existe um espectro, e engenharia é saber onde cada projeto fica nele.
O prompt descartável foi suficiente para a demo. Para o software que fica, o contrato escrito é um candidato forte a registro da intenção, desde que o custo dele fique proporcional ao tamanho do problema.
Fontes
- Retrospectiva de Karpathy sobre um ano de vibe coding (X, 4 fev 2026)
- Vibe coding is passé (Darryl K. Taft, The New Stack, 10 fev 2026)
- Context Before Code: An Experience Report on Vibe Coding in Practice (arXiv, 10 mar 2026)
- Structured-Prompt-Driven Development (Wei Zhang e Jessie Xia, martinfowler.com, 28 abr 2026)
- Requirements analysis: catching requirement bugs before they become code (blog do Kiro, 12 mai 2026)
- Spec Kit (README do repositório, consultado em jul 2026)
- Tweet original de Andrej Karpathy sobre vibe coding (2 fev 2025)
- Not all AI-assisted programming is vibe coding (Simon Willison, 19 mar 2025)
- Spec-driven development with AI (Den Delimarsky, GitHub Blog, 2 set 2025)
- Specification-Driven Development (documento de metodologia do Spec Kit)
- Introducing Kiro (blog do Kiro, jul 2025)
- Kiro is generally available (blog do Kiro, 17 nov 2025)
- Specs (documentação do Kiro)
- Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (Birgitta Böckeler, 15 out 2025)
- To vibe or not to vibe (Birgitta Böckeler, 23 set 2025)
Deixe um comentário