Pra mim, a maior parte do código gerado por agentes de IA em produção falha não por limitação do modelo, mas por insuficiência da entrada. O desenvolvedor descreve o que quer em linguagem livre e o agente interpreta com a melhor aproximação que o contexto permite. O resultado é código que funciona na superfície mas diverge da intenção em detalhes que só aparecem em edge cases, integração ou revisão. O padrão se repete em times de todos os tamanhos e com todos os modelos: a qualidade do código gerado é função direta da qualidade da especificação. Não do modelo.
Spec Driven Development, na forma como pratico, é o processo em que a especificação formal vira artefato primário do ciclo, e o código vira artefato derivado. A inversão parece sutil, mas muda a dinâmica inteira do fluxo. Em vez de escrever código e depois documentar, o desenvolvedor escreve a especificação com o comportamento esperado, os contratos de entrada e saída, as precondições, as invariantes e as restrições, e o agente gera código a partir desse contrato. O código se torna verificável contra a spec, não contra a intenção implícita de quem escreveu o prompt.
A formalização do conceito tem rastreabilidade clara. O Kiro da Amazon, em julho de 2025, e o Spec Kit do GitHub, em setembro, padronizaram workflows nessa direção. A Thoughtworks incluiu spec-driven development no Technology Radar de novembro de 2025, e o termo deixou de ser experimentação de practitioners. O que pratico vai além, porque não trata a spec como passo intermediário entre humano e agente, mas como o artefato que persiste e governa o ciclo inteiro, inclusive a validação do output.
Na minha análise, o mecanismo é previsível pra quem acompanhou a série sobre otimização de contexto. Um agente opera melhor quando o contexto que recebe é denso em informação relevante e baixo em ambiguidade. Uma user story do tipo "como usuário, quero poder filtrar pedidos por data" carrega ambiguidade em todas as dimensões: qual formato de data, qual fuso, filtragem inclusiva ou exclusiva nos limites, paginação do resultado, ordenação padrão, comportamento quando não há resultados. O desenvolvedor humano resolve essas ambiguidades consultando conhecimento tácito acumulado. O agente resolve por inferência estatística, o que significa que vai escolher a resposta mais provável, não a mais correta pro domínio específico. A especificação formal elimina essa classe de falhas ao tornar explícito o que a user story deixa implícito.
Uma spec no formato que uso em produção define mapeamentos de entrada e saída com tipos explícitos, pré e pós-condições, e o comportamento esperado em cenários de erro, incluindo invariantes que não podem ser violadas no fluxo. O formato é Markdown estruturado, não porque Markdown seja a melhor linguagem de especificação, mas porque é o formato que agentes de IA processam com menor perda de informação e que humanos revisam sem tooling adicional. Quando o agente recebe essa spec como contexto, o código gerado tende a cobrir os casos descritos de forma consistente, porque não precisa inferir o que está explicitamente declarado.
O trade-off mais visível é o tempo investido na escrita da spec. Quem está acostumado a escrever código direto percebe a spec como overhead, etapa que atrasa a entrega em vez de acelerá-la. Na minha avaliação, a percepção é correta no curto prazo e incorreta no ciclo completo. O tempo gasto na spec é tempo que seria gasto de qualquer forma em debugging, revisão, correção de edge cases e retrabalho de integração. A spec concentra esse investimento no início do ciclo, onde alterações custam menos e onde o agente absorve a informação de forma estruturada. Em projetos onde adotei o modelo, o tempo total de entrega caiu entre 30% e 40% comparado com fluxos de prompt livre, com a maior parte da economia vindo da redução de ciclos de correção.
O segundo trade-off é a manutenção da spec ao longo do tempo. Spec drift, a divergência progressiva entre a especificação e o código em produção, é o modo de falha mais previsível da abordagem. A mitigação passa por tratar a spec como código: versionada no repositório e validada em CI contra o comportamento real, com revisão em cada alteração. Testes gerados a partir da spec funcionam como detecção de drift: quando o código muda sem a spec acompanhar, o teste falha e o desenvolvedor reconcilia os dois artefatos.
Pra mim, o que diferencia Spec Driven Development de abordagens anteriores como BDD ou design by contract está no consumidor da especificação, porque a ideia de especificar antes de implementar existe desde os anos 80. Em BDD, a spec é consumida por um framework de teste que valida o comportamento do código escrito por um humano. No Spec Driven Development, a spec é consumida diretamente pelo agente que gera o código, e também pelo framework de teste que valida o código gerado. A spec vira artefato de geração com verificação embutida, e isso muda o incentivo econômico. Antes, escrever specs detalhadas competia com escrever código. Agora, é a forma mais eficiente de produzir código confiável em escala, porque o custo marginal de gerar código a partir de uma boa spec tende a zero enquanto o custo de gerar a partir de instruções ambíguas cresce com a complexidade do sistema.
Os próximos posts da série exploram como o modelo se aplica fora do código, porque a redução de ambiguidade que vale pra software vale pra qualquer artefato gerado por agente.