Spec-Driven Development: Escrevendo Specs, Não Código

O código se escreve sozinho. A spec não.

Um time na Amazon lança uma feature em três dias usando spec-driven development. Eles escreveram zero linhas de código de aplicação manualmente. Eles escreveram uma spec: 47 linhas de requisitos estruturados, critérios de aceitacao, edge cases e restrições de integração. Um agente leu a spec e produziu 2.300 linhas de código funcional. Os testes passaram. O deploy ficou verde. A feature chegou em produção.

Isso é De acordo com o guia da product.engineer, isso é spec-driven development: a prática de definir especificações estruturadas e legiveis por máquina que agentes de AI interpretam e executam como software funcional. Em vez de escrever código diretamente, engenheiros escrevem o documento de requisitos que um agente usa para gerar, testar e iterar código de forma autônoma. A spec se torna a fonte da verdade. O código se torna um artefato.

Spec-driven development inverte o fluxo de trabalho tradicional de engenharia. Você para de ser a pessoa que digita código. Você se torna a pessoa que define o que o código deve fazer, como deve se comportar e quais restrições deve satisfazer. O agente cuida da implementação. Você é dono da intenção.

Isso importa porque o papel de um product engineer sempre foi sobre resultados, não sobre outputs. Você lança software funcional que resolve problemas reais para usuários reais. Spec-driven development remove a parte de menor valor desse ciclo (traduzir intenção em sintaxe) e substitui pela parte de maior valor (definir intenção com precisão suficiente para que uma máquina execute). Essa traducao de desejo humano nebuloso para requisito técnico preciso sempre foi a parte mais difícil de construir software. Agora é a única parte que importa.

O Kiro da Amazon, apresentado no AI Engineer Summit em 2025 (a palestra acumulou mais de 48.000 visualizações desde então), formalizou essa abordagem para uso em produção. O sistema ingere specs estruturadas e produz implementações completas incluindo testes, tratamento de erros e configurações de deploy. Os dados de adoção interna foram impressionantes: times usando workflows de spec-driven lançaram 2,7x mais features por sprint com 40% menos incidentes em produção comparado a times fazendo desenvolvimento tradicional. As specs capturavam ambiguidades e edge cases que humanos tipicamente perdem durante a implementação porque escrever a spec forcava o engenheiro a pensar completamente no problema antes de qualquer código existir.

Por que código é a abstração errada

Por sessenta anos, a indústria de software assumiu que código era o artefato principal. Você contratava engenheiros para escrever código. Você media produtividade em linhas de código, commits ou pull requests. Code reviews eram o gate de qualidade. Código era a coisa.

Essa premissa esta se dissolvendo.

Código não é a intenção. Código é uma possível expressão da intenção. Quando você escreve if (user.subscription.tier === 'enterprise' && user.seats > 100), você está expressando uma regra de negócio. Mas o código obscurece a regra dentro de sintaxe, fluxo de controle e detalhe de implementação. A regra de negócio e: "Contas enterprise com mais de 100 seats recebem precificação por volume." Essa frase é a spec. O código é um artefato derivado.

Essa distinção importava menos quando humanos eram os únicos que podiam traduzir specs em código. Você precisava do código porque o computador precisava do código. Mas quando um agente de AI consegue traduzir de forma confiável requisitos estruturados em implementações corretas, o código para de ser o artefato criativo. A spec se torna.

O relatório Octoverse 2025 do GitHub descobriu que 47% do código commitado em repositórios com ferramentas de AI habilitadas foi gerado por AI. Na Shopify, métricas internas mostraram que 68% dos pull requests mergeados no Q3 2025 continham código gerado por AI. A contribuição humana estava migrando upstream: em direção à definição de problemas, especificação de requisitos e revisão.

O product engineer que entende essa mudança para de otimizar sua velocidade de digitação e começa a otimizar sua velocidade de pensamento. Ele investe em escrever specs melhores, não código mais rápido. Desenvolve a habilidade de context engineering para garantir que agentes recebam informação estruturada suficiente para agir corretamente. E reconhece que os 25 minutos gastos escrevendo uma spec precisa frequentemente economizam 4 horas de implementação manual e debugging.

A anatomia de uma spec executavel

Nem todas as specs são criadas iguais. Um Google Doc com bullet points não é uma spec executavel. Um ticket no Jira com critérios de aceitacao esta mais próximo, mas ainda e insuficiente. Uma spec executavel tem propriedades estruturais específicas que a tornam interpretavel por um agente.

Depois de estudar como o Kiro da Amazon, o v0 da Vercel e ferramentas internas da OpenAI lidam com inputs de especificação, uma estrutura comum emerge:

Os cinco componentes de uma spec executavel

Cada componente serve uma função distinta no loop de execução do agente. A declaração de intenção guia a abordagem geral. Critérios de aceitacao se tornam assertions de teste. Edge cases previnem os modos de falha mais comuns. Restrições de integração impedem o agente de reinventar infraestrutura existente. Não-requisitos previnem scope creep.

Essa estrutura não é arbitraria. Ela mapeia diretamente como engenheiros experientes pensam sobre problemas antes de escrever código. A diferença é que a maioria dos engenheiros faz esse pensamento implicitamente, na cabeca, enquanto simultaneamente digita. Spec-driven development torna esse pensamento explícito e externo. Você termina de pensar antes do agente começar a trabalhar.

O que torna uma spec legivel por máquina

Três propriedades distinguem uma spec que agentes podem executar de uma spec que é apenas documentação:

Critérios de aceitacao deterministicos. "A UI deve parecer rápida" não é executavel. "O carregamento da página completa em menos de 200ms para o percentil 95 dos usuários" e executavel. Todo critério deve ser verificavel por um teste automatizado.

Limites explícitos. Agentes que encontram ambiguidade vão preenche-la com suposições. Suposições ruins produzem bugs. Uma boa spec elimina ambiguidade sendo explícita sobre restrições: "Usar React Server Components, não renderizacao client-side." "Armazenar estado na URL, não em estado local." "Chamar o serviço de pagamento existente em /api/v2/charges, não criar um novo serviço."

Prioridade ordenada. Quando requisitos conflitam (e eles sempre conflitam nas bordas), a spec deve dizer ao agente qual requisito vence. "Se a geração de PDF levar mais de 30 segundos, retornar um resultado parcial com aviso em vez de dar timeout." Ordenacao de prioridade impede o agente de ficar preso em loops infinitos tentando satisfazer requisitos contraditorios simultaneamente.

O framework Kiro: como a Amazon operacionalizou isso

O sistema Kiro da Amazon, revelado no AI Engineer Summit, representa a implementação de produção mais madura de spec-driven development em escala. Não é um prototipo de pesquisa. Roda em produção em múltiplos times da Amazon.

O workflow tem quatro fases:

Fase 1: Autoria da spec. O engenheiro escreve uma especificação estruturada seguindo um schema predefinido. O Kiro fornece templates, mas a spec e escrita por humanos. Este é o trabalho criativo. E aqui que vive o julgamento de produto.

Fase 2: Validação da spec. Antes da execução começar, o sistema analisa a spec quanto a completude, ambiguidade e contradicoes internas. Ele faz perguntas de esclarecimento. Isso é crítico porque uma conversa de cinco minutos no estágio da spec previne cinco horas de debugging após a implementação. O passo de validação do Kiro capturou em média 3,2 ambiguidades por spec em testes internos, cada uma sendo um bug potencial que teria sido descoberto muito mais tarde no desenvolvimento tradicional.

Fase 3: Implementação. O agente gera código, testes, documentação e configuração de deploy a partir da spec validada. Roda testes iterativamente. Se um teste falha, faz debug e tenta novamente. O engenheiro observa mas não escreve código. Intervem apenas quando o agente está travado ou indo numa direção errada.

Fase 4: Revisão e refinamento. O engenheiro revisa a implementação gerada contra a spec original. Não linha por linha (isso é trabalho do agente) mas resultado por resultado. O PDF esta correto? A exportacao completa em menos de 30 segundos? O tratamento de erros corresponde ao que a spec exigiu? Este é o gate de qualidade.

Métricas internas dos times da Amazon usando o Kiro mostraram:

• Tempo médio de spec até PR mergeado: 3,4 horas (reduzido de 14,2 horas para features de complexidade similar)
• Cobertura de testes em código gerado: 87% em média (comparado a 64% para código escrito manualmente nos mesmos times)
• Taxa de incidentes em produção: 0,3 por 100 deploys (comparado a 0,8 por 100 para implementações manuais)

O número de cobertura de testes e particularmente revelador. Humanos cortam caminho nos testes. Agentes não. Quando a spec diz "testar estes edge cases", o agente escreve esses testes. Toda vez.

O que spec-driven development exige dos engenheiros

Esta não é uma historia sobre engenheiros se tornando obsoletos. E uma historia sobre o trabalho mudando de forma. Spec-driven development eleva o patamar para as habilidades que realmente importam e abaixa o patamar para as habilidades que sempre foram commoditizadas.

Habilidades que se tornam mais valiosas

Pensamento preciso. Escrever uma spec executavel é mais difícil do que escrever código. Código permite que você seja vago porque você pode se virar com ambiguidade durante a implementação. Uma spec força você a resolver cada ambiguidade antecipadamente. Você não pode escrever "tratar erros adequadamente" numa spec. Você deve especificar exatamente quais erros podem ocorrer é exatamente o que acontece para cada um.

Design de sistemas. Quando você não está escrevendo código, você está projetando sistemas. você está decidindo quais são os componentes, como eles interagem, quais contratos eles mantém. Este é o pensamento arquitetural que sempre foi a parte mais valiosa da engenharia senior. Spec-driven development apenas remove o ruido de implementação e torna isso o output principal.

Expertise de domínio. Um agente não pode te dizer qual é o comportamento correto do produto. Não pode entrevistar usuários. Não pode interpretar requisitos de negócio ambiguos de stakeholders. O product engineer que entende profundamente o domínio escreve specs melhores, que produzem software melhor. Conhecimento de domínio se torna a vantagem competitiva, não velocidade de digitação.

Comunicação escrita. Ha uma conexão direta entre spec-driven development é a capacidade de comunicar com precisão por escrito. Specs são artefatos escritos. Sua qualidade depende inteiramente da capacidade do autor de expressar ideias complexas com precisão e completude. Engenheiros que escrevem bem especificam bem.

Habilidades que depreciam

Velocidade bruta de código não diferencia mais. Memorizar superficies de API importa menos quando o agente conhece todas elas. Debugar erros de sintaxe não é uma habilidade quando o agente produz código sintaticamente correto por padrão. Estas nunca foram as habilidades de alto valor, mas eram as visíveis. As habilidades que diferenciam num mundo spec-driven estão todas upstream do código.

Minha experiência com workflows spec-driven

Comecei a experimentar com abordagens spec-driven na AWS no início de 2025, inicialmente com ferramentas internas e depois com features customer-facing. A primeira coisa que notei foi o quao mal a maioria dos engenheiros (incluindo eu mesmo) específica requisitos quando forcados a torna-los explícitos.

A gente acha que sabe o que quer. Dai tenta escrever como uma spec deterministica e descobre seis ambiguidades no que parecia ser uma feature simples. "Adicionar uma barra de busca ao dashboard." Buscar o que? Por quais campos? O que acontece com zero resultados? E case-sensitive? Filtra em tempo real ou ao submeter? Qual é o tamanho máximo da query? São decisões que normalmente tomamos inconscientemente durante a implementação. Spec-driven development força essas decisões para o aberto.

Tendo treinado mais de 12.000 engenheiros e contratado mais de 600, posso te dizer que a capacidade de pensar precisamente sobre requisitos antes de escrever código é o mais forte preditor individual de efetividade em engenharia que já observei. Correlaciona mais fortemente com qualidade de output do que anos de experiência, expertise em linguagens ou conhecimento algoritmico. Spec-driven development formaliza essa habilidade é a torna o trabalho principal.

Os times com quem trabalho que adotaram workflows spec-driven reportam o mesmo padrão: as primeiras duas semanas parecem mais lentas. você está escrevendo specs em vez de código, e parece que você não está "construindo." Na terceira semana, a diferença de velocidade se torna inegavel. Features chegam mais rápido, com menos bugs e com melhor cobertura de testes. Na sexta semana, ninguém quer voltar atrás.

Spec-driven development e agentic engineering

Spec-driven development é uma peça de uma mudança maior em direção a agentic engineering. Responde uma pergunta específica: o que o humano faz quando o agente escreve o código? O humano escreve a spec.

Mas se conecta a outros padrões:

• Context engineering fornece ao agente a informação que ele precisa para executar a spec corretamente. Uma spec sem contexto (qual codebase? quais padrões existentes? quais convenções de estilo?) produz código genérico que não se encaixa no sistema.
• Review engineering é o que acontece depois que o agente gera código. O product engineer revisa resultados contra a spec, não detalhes de implementação contra suas preferências.
• Loops de iteração lidam com os casos em que a primeira geração não satisfaz completamente a spec. O engenheiro atualiza a spec ou fornece restrições adicionais, é o agente itera.

Juntos, esses padrões formam o workflow do product engineer moderno: especificar, fornecer contexto, revisar resultados, iterar. Nenhuma dessas etapas exige escrever código manualmente. Todas exigem julgamento profundo de produto e técnico.

Começando com spec-driven development

Você não precisa do Kiro da Amazon para começar a praticar spec-driven development. Os princípios se aplicam com qualquer ferramenta de AI coding.

Um framework prático para começar

1. Antes de abrir um editor, escreva a spec. Use a estrutura de cinco componentes: intenção, critérios de aceitacao, edge cases, restrições de integração e não-requisitos. Mantenha num arquivo markdown na raiz do feature branch.

2. Alimente a spec para seu agente. Seja usando Claude Code, Cursor ou GitHub Copilot Workspace, cole a spec completa como o prompt inicial. Deixe o agente fazer perguntas de esclarecimento. Responda, depois adicione essas respostas a spec.

3. Revise contra critérios, não contra código. Quando o agente produzir uma implementação, não leia cada linha buscando problemas de estilo. Execute os critérios de aceitacao. Os testes passam? Os edge cases se comportam corretamente? Integra com sistemas existentes como especificado?

4. Itere na spec, não no código. Se algo está errado, não corrija o código manualmente. Atualize a spec para ser mais precisa e deixe o agente regenerar. Isso mantém a spec como fonte da verdade e previne drift entre o que você especificou é o que existe.

5. Versione a spec com o código. O arquivo de spec vai junto com o PR. Engenheiros futuros (e agentes futuros) podem ler a spec para entender a intenção, não apenas a implementação. Isso é documentação que se escreve sozinha porque foi escrita primeiro.

Erros comuns

Sub-especificar edge cases. O happy path e fácil de especificar. Os modos de falha são onde os bugs vivem. Force-se a enumerar pelo menos cinco edge cases para cada feature, mesmo as simples.

Super-especificar implementação. A spec deve dizer o que, não como. "Ordenar a lista alfabeticamente" é uma spec. "Usar Array.prototype.sort com um comparador locale-aware" é um detalhe de implementação. Deixe o agente escolher o como a menos que você tenha uma restrição específica.

Pular os não-requisitos. Sem não-requisitos explícitos, agentes vão construir demais. Vão adicionar features que você não pediu porque pareciam lógicas. "Não suporta exportacao em lote" impede o agente de gastar três horas construindo exportacao em lote quando tudo que você precisava era download de item único.

A economia do spec-driven development

O argumento econômico e direto. No desenvolvimento tradicional, o gargalo é a implementação. Um engenheiro senior custa $200-400 por hora com encargos completos. Eles gastam 60-70% desse tempo escrevendo e debugando código. Spec-driven development desloca o tempo deles para os 30-40% que sempre foram o trabalho de alto valor: entender problemas, projetar soluções e validar resultados.

A pesquisa interna de produtividade da Stripe (compartilhada no offsite de engenharia de 2025, depois referenciada no blog de engenharia) descobriu que seus engenheiros de maior impacto gastavam menos de 40% do tempo escrevendo código mesmo antes de ferramentas de AI. Eles gastavam a maioria em especificação, revisão e coordenação entre times. Spec-driven development não é uma mudança radical para esses engenheiros. E uma formalizacao do que eles já estavam fazendo.

Para times adotando essa abordagem, a matemática fecha claramente. Uma feature que levava um engenheiro cinco dias agora leva um engenheiro dois dias (um dia especificando, um dia revisando e iterando). Os três dias economizados se acumulam ao longo de dezenas de features por trimestre. Em escala, isso não é uma melhoria marginal. E uma mudança estrutural na economia da engenharia.

Principais conclusões

• Spec-driven development trata a especificação como o artefato criativo primário e código como output downstream.
• Engenheiros definem intenção, critérios de aceitacao, edge cases e restrições; agents geram a implementação.
• Uma feature que levava cinco dias agora leva dois (um dia especificando, um dia revisando e iterando).
• A spec deve ser legivel por máquina, estruturada e precisa o suficiente para agents executarem sem ambiguidade.
• Essa abordagem se compoe em escala, criando uma mudança estrutural na economia de engenharia em dezenas de features por trimestre.

FAQ

O que é spec-driven development?

Spec-driven development é a prática de escrever especificações estruturadas e legiveis por máquina que agentes de AI interpretam e executam como software funcional. Engenheiros definem o que o software deve fazer (intenção, critérios de aceitacao, edge cases, restrições) e agentes geram a implementação. A spec é o artefato criativo principal; o código é um output derivado.

Spec-driven development substitui engenheiros de software?

Não. Muda o que engenheiros fazem, não se eles são necessários. Spec-driven development exige pensamento de produto mais profundo, habilidade de design de sistemas e expertise de domínio. Remove a traducao manual de intenção em sintaxe. O julgamento de engenharia necessário para escrever uma boa spec é o mesmo julgamento que tornava alguém um bom engenheiro antes de ferramentas de AI existirem.

Quais ferramentas suportam spec-driven development hoje?

O Kiro da Amazon é a implementação mais formalizada. Porém, os princípios funcionam com Claude Code, Cursor, GitHub Copilot Workspace, v0 da Vercel e qualquer assistente de AI coding que aceite input estruturado. A chave e fornecer ao agente uma spec completa em vez de instruções ad-hoc. A ferramenta importa menos do que a disciplina de especificar antes de gerar.

Como spec-driven development e diferente de escrever bons tickets?

Bons tickets descrevem intenção para humanos. Specs executaveis descrevem intenção para máquinas. A diferença e precisão: tickets podem conter ambiguidade porque um implementador humano vai fazer perguntas ou fazer suposições razoáveis. Specs devem ser inequivocas porque agentes vão preencher lacunas com suposições potencialmente erradas. Uma boa spec elimina toda ambiguidade que um ticket deixaria em aberto.

Engenheiros juniors conseguem fazer spec-driven development?

Engenheiros juniors podem começar mas vão produzir specs mais fracas inicialmente porque tem menos intuicao sobre edge cases, restrições de sistema é modos de falha. Spec-driven development eleva o piso de qualidade do output (o agente escreve código bom independente da habilidade de programação do autor da spec) mas o teto ainda e determinado pela capacidade do engenheiro de pensar completamente sobre problemas. A habilidade se desenvolve com prática e mentoria.

Leitura relacionada

• What Is a Product Engineer?
• Context Engineering: A Habilidade que Substituiu Prompt Engineering
• Agentic Engineering: How Product Engineers Build with AI
• Written Communication for Product Engineers
• Don't Build Agents, Build Skills