O spec-driven development ganhou espaço como resposta a um problema que a adoção acelerada de inteligência artificial tornou visível: gerar código ficou barato, enquanto garantir que esse código faça a coisa certa continua caro. Segundo o relatório DORA 2025, do Google Cloud, 90% dos profissionais já usam IA no trabalho e mais de 80% percebem ganho de produtividade. O mesmo estudo mostra que a adoção de IA passou a acelerar o ritmo de entregas, mas continua associada a mais instabilidade nas mudanças que chegam à produção.
Esse descompasso tem uma explicação concreta no dia a dia. Quando a instrução dada ao modelo é uma frase solta em uma conversa, o resultado depende do que o desenvolvedor lembrou de mencionar naquele momento, e regras de negócio que ninguém citou simplesmente não aparecem no código. A ausência só é percebida na revisão, no teste ou, no pior caso, em produção, e quanto mais rápido o código é gerado, mais cedo esse gargalo aparece.
A resposta que vem se consolidando no mercado é deslocar o esforço para antes da geração. O time escreve uma especificação revisável, aprova esse documento e só então libera o agente para executar, de modo que o artefato aprovado passa a ser o contrato do que será construído e a revisão alcança também a intenção por trás do código.
Neste guia, você vai entender o que é spec-driven development, como ele funciona, quais são suas fases, quando ele vale mais que a abordagem informal e como aplicá-lo em um time que já produz com inteligência artificial. Acompanhe:
O que é spec-driven development?
Spec-driven development é a prática de escrever uma especificação estruturada e revisável antes de gerar código, tratando esse documento como a fonte de verdade da implementação. A especificação passa por aprovação humana antes de qualquer linha ser escrita, e o código se torna consequência do documento aprovado. Em geral, ela descreve:
- Comportamento esperado: o que a funcionalidade deve fazer, incluindo os casos de exceção;
- Decisões técnicas: quais componentes mudam e quais contratos são afetados;
- Tarefas: os passos de implementação, em ordem e verificáveis um a um.
O diferencial está no destino do artefato, uma vez que um documento de requisitos costuma ser lido por pessoas e traduzido manualmente para código, com perdas em cada tradução. Nesse método, um agente consome a especificação diretamente, o que reduz a distância entre o que foi combinado e o que foi implementado.
Como funciona o spec-driven development?
O spec-driven development funciona em um ciclo de três movimentos: especificar, aprovar e executar. A demanda é descrita em linguagem natural, transformada pela ferramenta em requisitos, desenho técnico e tarefas, e então revisada pelo time antes da implementação. A execução acontece a partir dessa especificação, mantendo a rastreabilidade entre o pedido original, as decisões técnicas e o que foi entregue.
1. Especificar a demanda
O processo começa com a descrição do que precisa ser desenvolvido, preferencialmente em linguagem natural e com contexto suficiente para deixar claro o resultado esperado. A ferramenta transforma essa demanda em uma especificação estruturada, que pode incluir requisitos, critérios de aceitação e regras do sistema.
2. Aprovar a especificação
Antes de escrever código, o time revisa os requisitos e o desenho técnico proposto. É nesse momento que decisões sobre arquitetura, validações e comportamento podem ser discutidas e ajustadas. Uma divergência sobre onde deve ficar a validação de um dado, por exemplo, pode ser resolvida aqui antes de se espalhar pela implementação.
3. Executar e verificar
Com a especificação aprovada, as tarefas são executadas de acordo com o que foi definido. Cada entrega pode ser verificada em relação aos requisitos e critérios de aceitação, mantendo a conexão entre a demanda original e o código produzido. O ganho está justamente em deslocar parte da discussão técnica para antes da implementação, quando corrigir uma decisão tende a custar menos.
Spec-driven development é a mesma coisa que documentação de requisitos?
Não, embora os dois tenham parentesco. A documentação de requisitos tradicional descreve o que o sistema deve fazer e fica separada do código, envelhecendo à medida que a implementação avança. Já a especificação desse método é versionada junto ao repositório, consumida por um agente e atualizada no mesmo fluxo da mudança. Veja as diferenças:
| Critério | Documentação de requisitos | Especificação do método |
|---|---|---|
| Onde fica | Em documento separado do código | Versionada no repositório |
| Quem consome | Pessoas, que traduzem para código | Um agente, com revisão humana |
| Escopo | Grandes blocos do sistema | Uma mudança executável em uma sessão |
| Atualização | Costuma envelhecer com o tempo | Revisada a cada mudança |
Essa escala menor é o que mantém a especificação viva, porque revisá-la custa pouco. O time lê, comenta e aprova um documento curto, com a mesma frequência com que revisa código.
Quais são as fases do spec-driven development?
O método se organiza em três fases encadeadas, 1) requisitos, 2) desenho técnico e 3) tarefas, e cada uma tem um critério de saída próprio. Pular qualquer uma delas devolve o time ao improviso: sem requisitos claros o desenho vira palpite, e sem desenho aprovado a lista de tarefas não tem como estar correta. Explicamos cada fase:
1. Requisitos
A primeira fase transforma o pedido em critérios de aceitação verificáveis, incluindo os casos de exceção que costumam ficar implícitos. É aqui que aparecem as perguntas que ninguém tinha feito, como o que acontece quando o cliente já tem um cadastro parcial ou quando o pagamento é aprovado depois do cancelamento.
2. Desenho técnico
A segunda fase define como a solução será construída: quais componentes mudam, quais contratos são afetados e quais decisões de arquitetura estão envolvidas. Revisar esse documento é o ponto de maior alavancagem do método, porque corrigir uma escolha estrutural nessa etapa custa uma fração do que custaria depois.
3. Tarefas
A terceira fase quebra o desenho em passos executáveis e verificáveis individualmente. Uma lista bem construída permite acompanhar o avanço item a item e interromper a execução no meio sem deixar a base em estado inconsistente. A execução dessas fases dentro de uma ferramenta específica está detalhada no conteúdo sobre spec-driven development com Kiro.
Vibe coding ou spec-driven development: quando usar cada um?
A escolha entre a abordagem informal, conhecida como vibe coding, e o spec-driven development depende do custo do erro e da vida útil do que está sendo construído. Descrever a tarefa em uma frase e iterar rápido funciona bem em exploração, prova de conceito e script descartável. Já em código que vai para produção e será mantido por anos, a especificação prévia se paga na primeira regressão evitada. Veja a comparação:
| Critério | Abordagem informal | Spec-driven development |
|---|---|---|
| Melhor cenário | Protótipo e exploração | Produção e código mantido |
| Onde está a revisão | No código pronto | Na intenção, antes do código |
| Rastreabilidade | Baixa, dispersa no histórico da conversa | Alta, versionada no repositório |
| Custo inicial | Muito baixo | Médio, concentrado no início |
| Risco de regressão | Alto em base complexa | Reduzido pelos critérios de aceitação |
As duas abordagens convivem no mesmo time, desde que a fronteira esteja combinada. Um arranjo comum reserva a abordagem informal para investigação e protótipo e exige especificação para qualquer alteração que chegue ao repositório principal.
Como aplicar spec-driven development no time?
Aplicar spec-driven development em um time que já usa IA passa por cinco etapas: 1) escolher uma demanda piloto, 2) documentar os padrões do projeto, 3) definir quem aprova cada fase, 4) revisar a especificação como código e 5) medir o resultado. A adoção é principalmente uma mudança de processo, por isso vale começar pequeno, com uma demanda de complexidade média que o time já compreende. Explicamos cada etapa:
1. Escolha uma demanda piloto
Selecione uma demanda real e delimitada para ser piloto, evitando começar pela tarefa mais crítica do trimestre. Assim, o time consegue comparar o resultado com a própria estimativa original sem pressão excessiva de prazo.
2. Documente os padrões do projeto
Registre convenções, bibliotecas e decisões de arquitetura em arquivos de contexto versionados, como os steering files do Kiro. Dessa forma, cada especificação nasce alinhada à arquitetura existente.
3. Defina quem aprova cada fase
Nomeie os responsáveis e os critérios de aprovação de requisitos, desenho e tarefas antes da primeira execução. Sem esse combinado, a aprovação vira formalidade e o método perde a razão de existir.
4. Revise a especificação como se revisa código
Trate a especificação com comentários, pedidos de ajuste e aprovação explícita, no mesmo fluxo da revisão de código. A participação de quem conhece a regra de negócio nessa etapa é o que revela as exceções não documentadas.
5. Meça o resultado
Compare tempo de ciclo e taxa de falha em mudanças antes e depois de dois ciclos completos de entrega. O efeito desse tipo de adoção nos indicadores está detalhado no conteúdo sobre produtividade de times com o Kiro, e a capacitação prática do time é tratada no conteúdo sobre treinamento de IA para times de desenvolvimento
Leia também:
Quais ferramentas suportam spec-driven development?
O spec-driven development pode ser praticado com qualquer agente capaz de ler arquivos versionados no repositório, e o que muda entre as ferramentas é o grau de formalização. Algumas oferecem as três fases como recurso nativo, enquanto outras exigem que o time crie a convenção manualmente. Na prática, as opções se dividem em:
- IDEs com fluxo nativo: o Kiro, IDE da AWS, integra especificações e arquivos de direcionamento ao editor, como mostra o guia do Kiro AWS;
- Agentes de terminal: atendem ao mesmo método com convenções próprias, comparação detalhada no conteúdo sobre Claude Code e Kiro;
- Agentes conectados a sistemas internos: usam o protocolo MCP para consultar dados e ferramentas da empresa durante a execução.
Qual a importância do spec-driven development para a empresa?
O spec-driven development reduz o retrabalho causado por mal-entendidos sobre requisitos, que é uma das principais fontes de atraso em times que geram código com IA. Como a especificação fica versionada, a empresa também ganha:
- Histórico das decisões: algo valioso em auditorias e na entrada de novas pessoas no time;
- Reforço em práticas como controle de versão bem estabelecido e trabalho em lotes pequenos.
Com especificações curtas e revisadas, a velocidade da geração de código passa a vir acompanhada de previsibilidade na entrega.
Spec-driven development com a UDS
Levar especificação estruturada para dentro do fluxo de engenharia demanda padrões documentados, critérios de aprovação definidos e indicadores acompanhados. A UDS Tecnologia tem 23 anos de mercado, é AWS Advanced Consulting Partner e mantém certificações ISO 27001 e PCI DSS, credenciais que sustentam esse rigor em projetos com exigência formal de qualidade. A experiência da UDS com ferramentas agênticas aparece no relato sobre como a UDS usa o Kiro em projetos.
Esse cuidado com processo aparece também em entregas de longo prazo. No case da Verocard, uma equipe de 16 especialistas da UDS construiu a plataforma própria de benefícios da empresa, com arquitetura serverless baseada em microsserviços na AWS, e a migração da infraestrutura para a nuvem gerou 35% de economia e 75% menos chamados de suporte.
Quem quer estruturar esse método internamente pode conhecer os serviços de desenvolvimento de software e a atuação da UDS.
Perguntas frequentes sobre spec-driven development
O que é spec-driven development?
É uma forma de trabalhar em que a especificação aprovada vem antes do código e orienta toda a implementação. O nome vem do inglês e pode ser traduzido como desenvolvimento orientado por especificação.
Spec-driven development serve só para projetos grandes?
Serve para qualquer alteração cujo erro tenha custo relevante, inclusive correções pequenas em sistemas críticos. Em scripts descartáveis e em exploração, a formalização costuma custar mais do que entrega.
O método deixa a entrega mais lenta?
O tempo até a primeira linha de código aumenta, e o tempo total até a entrega estável costuma cair, porque boa parte do retrabalho nasce de mal-entendidos sobre o requisito. Por isso, a comparação justa considera o ciclo inteiro da demanda.
Preciso de uma ferramenta específica?
Não é obrigatório, já que o método pode ser praticado com convenções manuais em qualquer agente que leia arquivos do repositório. Ferramentas com suporte nativo ajudam principalmente times maiores, em que manter a mesma convenção entre muitas pessoas é mais difícil.
Quem escreve a especificação?
Normalmente o desenvolvedor responsável pela demanda, com apoio do agente para estruturar o texto em requisitos, desenho e tarefas. A revisão envolve quem conhece a regra de negócio, porque é nesse momento que aparecem as exceções não documentadas.
A especificação substitui os testes?
Não. Os critérios de aceitação orientam quais testes escrever, e a verificação automatizada continua necessária, já que especificação e teste atuam em momentos diferentes, um antes e outro depois da implementação.
Como o método lida com mudança de escopo?
Mudanças entram como revisão da especificação, que é versionada junto ao código e passa por nova aprovação. Isso preserva o histórico da decisão e evita alterações silenciosas que ninguém consegue explicar meses depois.
Spec-driven development funciona para correção de bugs?
Funciona bem, com a especificação descrevendo o comportamento observado, o comportamento esperado e o critério de verificação. Em bugs intermitentes, esse registro costuma ser o que permite reproduzir o problema de forma confiável.
Qual o maior erro de quem começa?
Escrever especificações longas demais, que ninguém revisa com atenção e que envelhecem antes de serem executadas. Escopo estreito e revisão rápida sustentam o método muito melhor do que documentos extensos.
Como convencer o time a adotar?
O argumento que costuma funcionar é comparar o retrabalho de duas demandas semelhantes, uma conduzida de cada forma. Números da própria equipe convencem mais do que a descrição do método em abstrato.
O que acontece se o agente ignorar a especificação?
Isso normalmente indica especificação ambígua ou contexto insuficiente sobre os padrões do projeto. Ajustar os arquivos de direcionamento e estreitar o escopo da tarefa resolve a maior parte desses casos.
