Spec-driven development é a metodologia de desenvolvimento de software que prioriza a especificação documentada de requisitos, arquitetura e plano de implementação antes da escrita de qualquer código. O Kiro, IDE agentic da AWS, é a primeira ferramenta a integrar essa metodologia diretamente na experiência de desenvolvimento com IA, gerando especificações em notação EARS que podem ser convertidas em testes automatizados.
Neste artigo, você vai entender como o spec-driven development funciona na prática dentro do Kiro, por que ele resolve os problemas do vibe coding em escala e como adotar a metodologia de forma incremental no seu time.
O problema do vibe coding em escala
A popularização do vibe coding trouxe ganhos reais de produtividade para desenvolvedores individuais. Descrever o que você quer em linguagem natural e deixar a IA gerar o código funciona bem para protótipos. O problema aparece quando esse padrão é adotado por times inteiros, sem coordenação.
Código gerado por IA sem estrutura tende a ser verboso, sem aderência aos padrões do time e difícil de manter. Cada desenvolvedor usando IA de forma diferente cria um codebase fragmentado. Os requisitos ficam na cabeça de quem escreveu o prompt, não no repositório. Quando alguém sai do time, o conhecimento vai junto.
O spec-driven development existe para resolver exatamente esses problemas. Em vez de ir direto do prompt para o código, a metodologia força um processo estruturado que documenta decisões, padroniza o fluxo entre desenvolvedores e gera artefatos rastreáveis.
O que é spec-driven development?
Spec-driven development é uma metodologia em que especificações se tornam artefatos de primeira classe no repositório, não documentos descartáveis. O desenvolvedor descreve o que quer construir, e a ferramenta conduz um processo de três fases antes de escrever código: definição de requisitos, proposta de design técnico e criação de um plano de tarefas sequenciado.
O Kiro da AWS é o primeiro IDE a implementar spec-driven development de forma nativa. Quando você cria um novo spec no Kiro, o agente gera três arquivos Markdown versionados no Git, dentro da pasta .kiro/specs/[nome-da-feature]/ (veja a documentação oficial de Specs):
requirements.md — histórias de usuário com critérios de aceitação em notação EARS.
design.md — arquitetura técnica, diagramas de fluxo e decisões de stack.
tasks.md — plano de implementação com tarefas discretas, sequenciadas por dependência.
Esses arquivos ficam no repositório junto com o código. Não são rascunhos temporários: são artefatos de projeto que documentam por que o código existe da forma que existe.
“O tempo que você investe no planejamento com specs retorna multiplicado no código que funciona de primeira.” – Desenvolvedor na comunidade DEV.to sobre spec-driven development
As três fases do spec-driven development no Kiro
Fase 1: Requirements — transformando ideias em requisitos verificáveis
Quando você cria um novo spec e descreve uma funcionalidade em linguagem natural, o Kiro não gera código: ele gera histórias de usuário estruturadas com critérios de aceitação em notação EARS (Easy Approach to Requirements Syntax).
EARS é um padrão de escrita de requisitos criado originalmente pela Rolls-Royce para sistemas de software críticos. O formato segue uma estrutura específica: WHEN [evento], THE SYSTEM SHALL [comportamento]. Esse padrão torna os requisitos verificáveis: é possível escrever testes automatizados diretamente a partir de cada critério de aceitação. A AWS detalhou a visão por trás dessa escolha no artigo Kiro and the future of AI spec-driven software development.
Exemplo de requisito em notação EARS gerado pelo Kiro:
História: Como usuário, quero avaliar produtos para ajudar outros compradores.
Critério 1: WHEN o usuário acessa a página de um produto, THEN o sistema SHALL exibir a média de avaliações e o total de reviews.
Critério 2: WHEN o usuário envia uma avaliação sem texto, THEN o sistema SHALL exibir uma mensagem de erro solicitando ao menos 10 caracteres.
O resultado é armazenado em requirements.md. O Kiro também suporta dois workflows de spec: Requirements-First (define requisitos primeiro, depois gera design) e Design-First (começa pela arquitetura e depois deriva os requisitos), conforme detalhado na documentação de Feature Specs. A escolha depende do cenário: funcionalidades novas geralmente se beneficiam de Requirements-First, enquanto refatorações complexas podem partir do design.
Fase 2: Design — arquitetura antes do código
Com os requisitos aprovados, o Kiro analisa o codebase existente e propõe a arquitetura técnica necessária. Isso inclui decisões de stack, novos componentes, mudanças em componentes existentes, schemas de banco de dados e diagramas de sequência.
O design é armazenado em design.md e deve ser revisado pelo time antes da implementação. Esse é o momento ideal para identificar conflitos de arquitetura, dependências problemáticas e decisões que vão afetar a manutenção futura. Capturar um erro de design nessa fase custa minutos; capturá-lo em produção custa dias.
Fase 3: Tasks — implementação sequenciada e rastreável
A partir do design aprovado, o Kiro gera um plano de implementação em tasks.md: uma lista de tarefas discretas, sequenciadas por dependência, com descrição clara do que cada uma deve produzir. O desenvolvedor executa cada tarefa individualmente, acompanha o progresso em tempo real e ajusta antes de prosseguir.
Toda a pasta .kiro/specs/ deve ser versionada no repositório junto com o código. As specs documentam o contexto das decisões tomadas, o que é valioso para onboarding de novos desenvolvedores e para manutenção futura: qualquer pessoa do time pode entender por que o código foi construído daquela forma.
Para configurar o Kiro e criar seu primeiro spec na prática, leia: Como instalar e configurar o Kiro IDE.
Spec-driven development também funciona para bugs
Além de Feature Specs, o Kiro suporta Bugfix Specs: um fluxo dedicado para diagnosticar e corrigir bugs de forma estruturada. Em vez de ir direto para o código com um fix, o Bugfix Spec conduz o desenvolvedor por uma análise que documenta o comportamento atual, o comportamento esperado e o que não deve mudar (regressões). Isso é especialmente útil em codebases grandes, onde um fix apressado pode quebrar algo em outro lugar.
Vibe coding vs spec-driven development: comparativo em produção
Para quem está avaliando se vale a pena investir tempo em spec-driven development, a tabela abaixo compara os dois fluxos em critérios que importam para times de engenharia em produção.
| Critério | Vibe Coding | Spec-Driven Development (Kiro) |
|---|---|---|
| Documentação de requisitos | Não gerada automaticamente | Automática, versionada no Git |
| Rastreabilidade de decisões | Perdida após a sessão | Preservada em design.md |
| Consistência entre devs | Baixa (cada um usa IA do seu jeito) | Alta (specs compartilhadas via Git) |
| Onboarding de novos devs | Lento (sem contexto documentado) | Rápido (specs explicam o porquê) |
| Manutenção a longo prazo | Alta complexidade | Controlada com specs atualizadas |
| Cobertura de testes | Irregular | Derivada dos critérios de aceitação EARS |
O spec-driven development não substitui o vibe coding em todos os cenários. Para protótipos rápidos, exploração e features pequenas, o vibe coding continua sendo mais eficiente. O valor do spec-driven development aparece quando o código precisa ir para produção, ser mantido por meses e revisado por pessoas que não participaram da implementação original.
Como integrar spec-driven development ao processo do time
A adoção do spec-driven development não exige uma revolução no processo existente. A recomendação, baseada na experiência da UDS com clientes reais, é começar de forma incremental:
1. Piloto. Escolha uma funcionalidade nova (não urgente) para ser desenvolvida com o fluxo completo de specs. Documente o tempo investido em cada fase para ter dados de comparação.
2. Retrospectiva. Após a entrega, compare com uma funcionalidade similar desenvolvida sem specs: qualidade do código, número de bugs, facilidade de code review e tempo total de entrega.
3. Templates via steering files. Crie steering files que guiem o Kiro a gerar specs no formato que o time prefere. Por exemplo: specs que sempre incluam testes escritos antes do código (TDD) ou que sigam um template específico de design.
4. Expansão gradual. Adote specs para todas as novas funcionalidades. Funcionalidades de manutenção podem continuar no fluxo existente até o time ganhar confiança com a metodologia.
Para configurar steering files que otimizem o spec-driven development, leia: Steering Files no Kiro: como dar contexto persistente ao agente.
Perguntas frequentes sobre spec-driven development
Spec-driven development é mais lento que vibe coding?
A fase de planejamento adiciona tempo no início do processo, mas reduz significativamente o retrabalho, os bugs em produção e o tempo de code review. Times que adotaram spec-driven development com o Kiro relatam que o tempo total de entrega de funcionalidades complexas caiu de semanas para dias, porque o código gerado a partir de specs bem definidas precisa de menos iterações para ficar pronto.
Posso usar spec-driven development sem o Kiro?
A metodologia pode ser aplicada com qualquer ferramenta (inclusive existe o GitHub Spec Kit, que é open source). A diferença é que o Kiro é o único IDE que integra as três fases (requirements, design, tasks) de forma nativa, com geração automática em notação EARS, rastreamento de progresso embutido e sincronização entre specs e código.
O que é a notação EARS?
EARS (Easy Approach to Requirements Syntax) é um padrão de escrita de requisitos criado pela Rolls-Royce para especificar sistemas de software de forma não ambígua. O formato segue a estrutura WHEN [evento], THE SYSTEM SHALL [comportamento]. O Kiro usa EARS porque os critérios gerados nesse formato podem ser diretamente convertidos em testes automatizados, criando uma ponte entre especificação e validação.
As specs ficam desatualizadas quando o código muda?
O Kiro permite sincronizar specs com o código: você pode pedir ao agente que atualize as specs após mudanças na implementação, ou atualizar as specs manualmente para gerar novas tarefas. O ideal é tratar specs como artefatos vivos, revisados a cada sprint junto com o código.
Spec-driven development funciona para projetos legados?
Sim, mas com adaptação. Para codebases existentes, o fluxo de Bugfix Specs é o ponto de entrada mais natural: cada correção de bug passa por uma análise estruturada antes do fix. Para novas funcionalidades em projetos legados, o fluxo completo de Feature Specs funciona normalmente.
