O que é spec-driven development (desenvolvimento guiado por especificação)?

O agente escreve um código lindo, roda de primeira, passa no lint… e entrega outra coisa

Fala aí, beleza? Se o termo spec-driven development começou a pipocar nas suas threads de dev e você ficou com aquela pulga atrás da orelha, é exatamente disso que a gente vai tratar aqui: o que é uma spec, por que ela vira a fonte da verdade antes de qualquer linha de código, e em que ponto isso muda o teu fluxo de trabalho

Sem fórmula mágica, sem prompt secreto

Conceito, fluxo e as ferramentas que já entregam isso pronto 🙂

O que é uma spec (e o que ela precisa ter)

Spec-driven development é a abordagem em que uma especificação estruturada é escrita e acordada antes do código, funcionando como fonte única da verdade sobre o que construir

Estruturada, aqui, quer dizer formato que dá pra ler e versionar: Markdown, OpenAPI, esse tipo de coisa

E o que entra dentro dela? Requisitos, restrições, critérios de aceite e casos de borda, todos definidos antes da implementação

Se você conhece a rotina de escrever documentação DEPOIS que o sistema já está de pé, é justamente o contrário disso

A spec retrospectiva descreve o que já existe

A spec do SDD é o insumo: é o contexto compartilhado que o agente usa pra gerar código, testes e artefatos

Como isso parece na prática?

O Kiro, da Amazon, é um bom exemplo de formato concreto

As specs ficam em .kiro/specs/ e viram três documentos: requirements.md, design.md e tasks.md

O requirements.md usa a notação EARS (Easy Approach to Requirements Syntax), com requisitos escritos no padrão WHEN <condição> THE SYSTEM SHALL <comportamento esperado>

Parece burocrático? Um pouco

Mas olha o efeito: um requisito escrito assim não deixa espaço pro agente adivinhar a intenção, porque a condição e o comportamento esperado estão explícitos na mesma linha

Por que a spec vira a fonte da verdade antes do código

A motivação declarada pelo pessoal do Spec Kit é bem direta: o agente gera código que PARECE correto, mas erra a intenção

Em protótipo isso é tolerável, tu joga fora e refaz

Em aplicação crítica, é risco de verdade

O vibe coding funciona muito bem pra levantar um protótipo rápido, e perde confiabilidade exatamente quando a coisa fica séria

A spec entra aí como o acordo prévio sobre a intenção: antes de gerar, todo mundo (você, o time e o agente) está olhando pro mesmo documento

Só que tem um contraponto honesto

A Thoughtworks é bem explícita nesse ponto, e vale colar aqui pra ninguém sair achando que virou mágica: o código executável continua sendo a fonte de verdade que precisa de manutenção

A spec não substitui o código

Ou seja: não é trocar um artefato pelo outro, é somar um artefato de intenção na frente do artefato que roda

Quem prometer que agora tu só mantém a spec e o código vira detalhe, tá vendendo alguma coisa 😛

Como o fluxo de trabalho muda na prática

O ponto exato onde muda é o começo

Em vez de sair mandando prompt direto pra gerar código, o fluxo típico dos times com agentes fica assim: spec, depois plan, depois implement

O Technology Radar volume 34, de abril de 2026, descreve exatamente esse caminho e trata o SDD como um controle feedforward dentro do harness de agentes, junto de Agent Skills

Feedforward é o oposto de corrigir depois: você coloca a restrição na entrada, não no code review

Os três fluxos mais comuns hoje:

• Spec Kit: Spec → Plan → Tasks → Implement
• OpenSpec: dentro do chat do agente, com /opsx:explore, /opsx:propose, /opsx:apply e /opsx:archive
• Kiro: duas variantes de feature spec, Requirements-First e Design-First

Repara que a etapa de tasks aparece em quase todos

Esse é o pulo do gato do fluxo: quebrar a implementação em tarefas antes de mandar o agente executar, pra ele trabalhar uma de cada vez em vez de tentar acertar o projeto inteiro num prompt só

No Kiro dá até pra acionar o Run all Tasks, que analisa as dependências entre as tarefas e executa em paralelo as que são independentes

Spec Kit, Kiro e OpenSpec: as três portas de entrada

Começando pelo Spec Kit:

O Spec Kit é um toolkit open source da própria GitHub, sob licença MIT

A instalação é pela CLI specify, usando uv:

uv tool install specify-cli --from git+https://github.com/github/[email protected]
specify init meu-projeto --integration claude

Tome cuidado com dois detalhes aí

O primeiro é a tag de versão no fim do comando de instalação: troque pela versão que o repositório indicar, não chute

O segundo é a flag --integration, que já define o agente de codagem na hora de inicializar o projeto

E o Spec Kit trabalha com dezenas de agentes, entre CLIs e assistentes de IDE, incluindo Claude Code, GitHub Copilot, Gemini CLI e Cursor

Detalhe importante: nas integrações de CLI, a ferramenta precisa estar instalada na tua máquina

E o caminho completo, com as etapas de qualidade?

O caminho enxuto do Spec Kit é /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement

Mas o completo acrescenta as etapas que seguram a onda: /speckit.constitution → /speckit.specify → /speckit.clarify → /speckit.plan → /speckit.checklist → /speckit.tasks → /speckit.analyze → /speckit.implement → /speckit.converge

A constitution é o arquivo de princípios do projeto, e o Spec Kit espera ele no caminho padrão .specify/memory/constitution.md

E o OpenSpec, onde entra?

O OpenSpec é um framework open source de SDD com uma proposta diferente de morada: as specs ficam versionadas dentro do próprio repositório do projeto, ao lado do código, organizadas por capability

npm install -g @fission-ai/openspec@latest
openspec init

Depois disso o ciclo acontece no chat do agente mesmo, com /opsx:explore pra entender, /opsx:propose pra propor a mudança, /opsx:apply pra aplicar e /opsx:archive pra arquivar

O que aparece quando você roda um fluxo desses

No vídeo do canal eu montei um infográfico próprio pra explicar a parte teórica e depois fui pra demonstração ao vivo, criando um projeto passo a passo

A regra que eu segui foi simples: executar uma tarefa por vez e pedir pra IA PARAR ao terminar cada uma

E aí acontece uma coisa que eu não esperava tanto: os prompts ficam mais simples depois que a especificação está pronta

Basta mandar executar a tarefa seguinte e seguir o documento de design

Com a base bem estruturada, deixa de ser necessário caprichar tanto no texto de cada prompt

O ritmo também muda de cara ao longo da sessão

A etapa de planejamento consome mais tempo, isso é fato, e é a parte que mais testa a paciência

Mas o que vem depois fica previsível e sequencial: na demonstração eu implementei a autenticação em 2 minutos e depois emendei um gerador de QR Code na página principal como tarefa da mesma sequência

Minha leitura ali, na prática: a especificação funciona como guard rail

Você continua usando sua ideia e seus prompts, só que sem sair da curva

E é por isso que eu defendo que projeto guiado por especificação sai mais robusto, mais seguro, gastando menos tokens e com mais chance de escalar

O problema que motiva tudo isso é bem conhecido: quem não vem da área técnica pede os prompts, às vezes escreve um PRD, e deixa a IA desenvolver sem baliza nenhuma

SDD não é conceito novo, aliás, mas virou pauta agora justamente porque projeto feito só no vibe coding costumava não dar certo

Pra começar do zero com o "o que é", esse vídeo do canal traz a parte teórica no infográfico e a demonstração completa do fluxo, criando um projeto passo a passo até a implementação

No vídeo eu também comento que existem frameworks que automatizam o SDD, evitando que tu escreva os arquivos de especificação na mão

Quando spec-driven development compensa (e quando é peso morto)

Agora a parte que quase ninguém fala, porque não é hype nenhum: isso nem sempre vale a pena

Compensa quando:

• é aplicação crítica, aquela em que errar a intenção custa caro
• a feature tem muita regra de negócio e muito caso de borda pra amarrar
• o trabalho é em equipe e a intenção precisa estar acordada antes, não descoberta no pull request
• a base de código já existe: o Technology Radar registra que a experimentação com o Spec Kit está concentrada principalmente em projetos brownfield

É peso morto quando:

• você só quer um protótipo rápido pra validar uma ideia

Nesse caso o vibe coding entrega, e a spec vira burocracia pura

Tem hora que escrever requisito, restrição e critério de aceite pra uma tela que vai ser jogada fora amanhã é só atraso de vida, né? 😀

A ideia é mais velha que a IA

Antes que alguém trate isso como modinha de 2026, vale olhar pra trás

As raízes da prática remontam a fluxos da NASA nos anos 1960 e a métodos formais

A formalização acadêmica veio em 2004, como junção de TDD com design by contract

E o renascimento é dos anos 2020, puxado pelos fluxos agênticos com LLM

Ou seja: o que é novo não é a prática de especificar antes

O que é novo é ter do outro lado um agente que lê essa especificação e gera o código a partir dela

Vale adotar agora?

Vou ser honesto com o estágio real da coisa

No Technology Radar da Thoughtworks, spec-driven development está na categoria Techniques, no anel Assess (avaliar), e não em Adopt

O OpenSpec aparece em Tools, descrito como uma camada leve de especificação pra alinhar humanos e agentes antes de gerar código

E o Radar registra outra coisa que explica muita confusão de thread: os termos SDD e harness engineering são usados de forma inconsistente entre times e ferramentas, e às vezes se sobrepõem

Então se você leu duas definições diferentes essa semana e achou que estava boiando… não estava, o vocabulário é que ainda não assentou 🙂

Minha recomendação prática, alinhada com o anel Assess: avalie numa feature

Não reescreva o processo do time inteiro por causa de uma técnica que ainda está em avaliação

Conclusão

Spec-driven development, no fim das contas, é isto: escrever e acordar a especificação antes, deixar ela ser a fonte única da verdade sobre O QUE construir, e só então soltar o agente pra gerar

Requisitos, restrições, critérios de aceite e casos de borda na frente

Código depois (e o código executável continua sendo o artefato que você mantém, isso não mudou)

O próximo passo concreto é bem pequeno: escolhe uma ferramenta (Spec Kit, Kiro ou OpenSpec), pega UMA feature de uma base que já existe e roda o ciclo inteiro nela, do spec até o implement

Seja por framework ou fazendo o SDD na mão, é isso que separa um projeto com potencial de crescer de um vibe coding sem estrutura nenhuma

Depois de rodar uma vez, aí sim você decide se vale levar pro time

Até o próximo post! =)