- Spec-Driven Development (SDD) revive uma abordagem no estilo waterfall baseada na criação de documentação extensa antes de codificar, com o objetivo de estruturar o trabalho para ferramentas de assistência de código por IA, mas corre o risco de prejudicar a agilidade
- A comunidade open source desenvolveu ferramentas que geram automaticamente especificações, planos de implementação e listas de tarefas com base em prompts e instruções iniciais; entre os principais exemplos estão Spec-Kit, Kiro, Tessl e BMad Method
- Porém, no uso real, surgem várias limitações, como falta de entendimento de contexto, documentação excessiva, revisão dupla de código e falsa sensação de segurança; em codebases grandes, a eficiência cai drasticamente
- O texto argumenta que o SDD, como tentativa de substituir desenvolvedores, repete o fracasso do modelo waterfall e propõe, em vez disso, um modo iterativo de desenvolvimento baseado em linguagem natural
- Uma abordagem que combina os princípios de Agile e Lean Startup é mais adequada ao desenvolvimento moderno com agentes de código, e o próximo desafio está na evolução de ferramentas de interação visual
O surgimento do Desenvolvimento Orientado por Especificação (SDD)
- Spec-Driven Development (SDD) introduz um processo de criação de documentos de especificação antes da codificação para oferecer uma forma estruturada de desenvolvimento voltada a ferramentas de assistência de código por IA
- Com base em prompts e instruções iniciais, o LLM gera especificação do produto, plano de implementação e lista de tarefas
- Cada documento depende da etapa anterior, e o usuário revisa e ajusta os textos para refinar a especificação
- Os documentos finalizados são então passados para agentes de código como Claude Code, Cursor e Copilot, que os usam para escrever código
- Entre as ferramentas representativas estão Spec-Kit, da GitHub, Kiro, da AWS, Tessl e BMad Method (BMM)
- Como análise comparativa relacionada, é mencionado o texto de Birgitta Böckeler, Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl
O problema da documentação em Markdown
- As especificações de SDD geralmente são compostas por arquivos Markdown; como exemplo, a implementação de uma funcionalidade simples com o GitHub Spec-Kit chega a 8 arquivos e 1.300 linhas
- O caso de adicionar o campo “referred by” no Atomic CRM com o Kiro também acaba dividido em vários documentos
- No uso prático, aparecem as seguintes desvantagens
- Falta de percepção de contexto (Context Blindness): detalhes de funções existentes ou do contexto do código passam despercebidos, então a revisão de especialistas continua sendo necessária
- Documentação excessiva (Markdown Madness): documentos longos fazem perder muito tempo até para localizar erros simples
- Burocracia sistemática (Systematic Bureaucracy): repetições desnecessárias e detalhamento exagerado geram ineficiência
- Falso Agile (Faux Agile): uso indevido do conceito de “User Story”, causando dispersão
- Revisão dupla de código (Double Code Review): é preciso revisar separadamente o código presente na especificação e a implementação real
- Falsa sensação de segurança (False Sense of Security): o agente não segue necessariamente a especificação por completo
- Retorno decrescente (Diminishing Returns): útil em projetos iniciais, mas a velocidade cai conforme a escala aumenta
- Como a maioria dos agentes de código já oferece modo de planejamento e listas de tarefas, o ganho extra do SDD é limitado e pode até aumentar o custo de desenvolvimento
A vingança do gerente de projeto
- As limitações do SDD podem até ser atribuídas à imaturidade das ferramentas, mas, de forma mais fundamental, derivam de uma definição errada do problema
- Parte do objetivo de “como remover os desenvolvedores do desenvolvimento de software”
- Substitui o desenvolvedor por um agente de código e tenta controlá-lo por meio de planejamento minucioso
- Isso se parece com o modelo waterfall, em que uma documentação massiva transforma o desenvolvedor em mero tradutor
- Mas desenvolvimento de software é um processo não determinístico (non-deterministic), e planejamento não basta para eliminar a incerteza (com citação ao artigo No Silver Bullet)
- No SDD, é necessário o conhecimento de um analista de negócios na etapa de requisitos e de um desenvolvedor na etapa de design; na prática, isso restringe o uso a poucos que consigam exercer os dois papéis
- Como as ferramentas No Code, ele promete “desenvolvimento sem desenvolvedores”, mas no fim continua precisando deles
Uma nova alternativa: desenvolvimento iterativo baseado em linguagem natural
- A metodologia Agile resolve o problema do desenvolvimento não determinístico ao escolher adaptabilidade em vez de previsibilidade
- Dividir requisitos complexos em vários problemas simples é a chave para aproveitar agentes de código
- O texto apresenta um procedimento iterativo simples com base nos princípios do Lean Startup
- Identificar a hipótese mais arriscada do produto
- Projetar o experimento mínimo necessário para validá-la
- Desenvolver o experimento e iterar conforme os resultados
- Como exemplo, usando o Claude Code, foi possível desenvolver uma ferramenta de escultura 3D (sculpt-3D) em cerca de 10 horas
- Sem especificação formal, apenas com instruções curtas, as funcionalidades foram adicionadas gradualmente
- Implementações incorretas eram corrigidas imediatamente, permitindo iteração rápida
- Esse método permite convergência rápida mesmo sem documentação no estilo waterfall e viabiliza a construção de produtos em tempo real por meio da combinação de Agile com agentes de código
- Ainda assim, como os agentes de código são centrados em texto, falta interação visual, e no futuro será necessário desenvolver ferramentas com interfaces visuais mais fortes
Conclusão
- A metodologia Agile já havia tornado documentos de especificação desnecessários, e o SDD é visto como uma tentativa de trazê-los de volta
- O SDD é uma abordagem teórica que tenta excluir o desenvolvedor e acaba desperdiçando a chance de fortalecer uma nova geração de desenvolvedores com agentes de código
- O texto compara agentes de código a um motor de combustão interna: enquanto o SDD os prende a uma locomotiva, nós deveríamos expandi-los para carros, aviões e várias outras formas
- Por fim, se levarmos o meio ambiente em conta, é preciso fazer um uso comedido dos agentes de código
1 comentários
Opiniões do Hacker News
Como desenvolvedor, o maior ganho de produtividade que tive veio de criar o hábito de planejar todo o trabalho com antecedência
Sempre que recebo um ticket, eu o divido em uma grande lista de TODOs e deixo claros de antemão o design, as dependências e as especificações
Isso me permite entrar com mais frequência em estado de flow quando estou programando
Essa abordagem também funciona bem para agentes de codificação com IA, porque ela externaliza o processo de pensamento antecipadamente
Escrevi mais sobre isso no meu texto
Na prática, decompor o problema e escrever especificações é algo bom
O problema são especificações imutáveis. Se a implementação só começa meses depois, a especificação fica engessada
Já o Agile muitas vezes é usado como desculpa para adiar planejamento estratégico. O resultado é muito retrabalho
No fim, é uma questão de equilíbrio, e acho que “It depends” é um bom lema tanto para a vida quanto para o desenvolvimento
Se um LLM cuidar das especificações, parece haver a vantagem de reduzir a carga de manutenção
O texto relacionado está aqui
Quando é difícil prever, fazemos primeiro um spike para explorar código e bibliotecas
Criamos tanto um diagrama da estrutura ideal quanto um diagrama que reflita as restrições reais, para evitar armadilhas arquiteturais no longo prazo
Depois de alguns meses de vibe coding, nos últimos 6 meses migrei para spec-driven development
Passo de 2 a 3 horas por dia escrevendo especificações e, no mesmo dia, publico funcionalidades testadas
Escrever especificações não me deixou menos ágil. Pelo contrário, isso permite iterações rápidas em ciclos de 8 horas
A especificação não é um prompt, mas um critério de correção
Testes end-to-end bem definidos reduzem bastante os erros da IA
O resultado muda a cada execução e, no fim, um humano precisa revisar tudo, então isso pode ser ineficiente
Chamar um trabalho de um dia de “especificação” gera confusão. No fim, é o processo antigo com um nome novo
Muitas vezes interpretam mal até expressões lógicas simples, então é arriscado fazê-los entender especificações em linguagem natural
Entrego isso ao agente, ele implementa sozinho e eu só reviso no meio do caminho
Enquanto a IA trabalha, eu mexo no meu carro de corrida, então é uma situação de ganha-ganha total
No fim, a única coisa que importa é o código passar nos testes
Este texto parece voltado para pessoas que já concluíram que “spec-based development não serve para mim”
Eu vejo a especificação como um ponto de entrada de contexto para o LLM
Se você fornecer estrutura do projeto, modelos, funções e requisitos com riqueza suficiente, o LLM entende o contexto e consegue expandir a partir daí
Além disso, se o próprio LLM atualizar a especificação, fica possível fazer iterações ágeis
Os testes servem como grounding do LLM na realidade e evitam alucinações
Testes viram documentação e critério de qualidade, e o LLM precisa ser gerenciado como um desenvolvedor júnior
Se você rodar vários agentes em paralelo e fizer com que eles se validem mutuamente por meio de uma camada de testes, surgem resultados impressionantes
Graças aos LLMs, agora dá para iterar a especificação inteira de forma barata e rápida, mas a essência continua a mesma
Especificações longas demais acabam atrapalhando o pensamento exploratório
LLMs não são sistemas determinísticos, mas probabilísticos, então agora precisamos depurar especificações, não código
O desenvolvedor precisa evoluir para um arquiteto de sistemas cognitivos
Coexistem especificações de alto nível e especificações detalhadas de componentes
Eu tentei criar uma ferramenta de CLI com o Spec-Kit do GitHub, mas foram necessárias etapas demais de correção, análise e reescrita
Foi frustrante porque, como no waterfall, havia pouca realimentação iterativa
No fim, em vez de olhar para código errado e tentar achar a causa, era melhor começar de novo
Gosto de programar com LLM, mas o SDD pareceu um fluxo de trabalho pesado e ineficiente
LLMs gostam de contexto, então você precisa instruí-los repetidamente com clareza
Por exemplo, ao criar um app em NextJS, eu descrevo claramente login, RBAC, implementação com testes primeiro etc.
Começar com unidades pequenas e adicionar funcionalidades gradualmente é mais adequado
O problema do waterfall era o lead time longo e o alto custo de iteração
No SDD, essas duas coisas são resolvidas, então acho que tudo bem
Chamar uma especificação de algumas horas de waterfall é exagero
Se você entra cedo demais em um espaço de solução complexo, fica mais difícil resolver o problema de forma simples
O Agile começa em um espaço pequeno e vai expandindo gradualmente
Se a especificação for detalhada o bastante, a iteração fica lenta; se for insuficiente, o LLM não funciona direito
No fim, isso mantém a mesma contradição do waterfall que agrada gestores
LLMs funcionam melhor quando recebem instruções claras em partes pequenas
Vão escrever especificações para anos, rodar LLMs a cada 6 meses e, quando falhar, culpar os desenvolvedores
Sou o próprio autor do texto
Ainda acho interessante como o debate waterfall vs. agile continua vivo
Também é divertido ler o histórico das pessoas que acham SDD valioso
Mas eu já uso o modo Plan antes de implementar, então SDD não me traz valor adicional
Quase nunca vi um agente de codificação implementar tudo perfeitamente de uma vez
No fim, sempre é preciso iterar, então a ideia de Big Design Up Front perde o sentido
Ainda assim, acredito que agentes de codificação estão abrindo um novo paradigma de desenvolvimento
Isso me lembrou este vídeo que vi antes
Ele falava sobre o que engenheiros e programadores podem aprender uns com os outros, e a importância do planejamento prévio me marcou
Dizem que o agile matou os documentos de especificação, mas na prática ele só os quebrou em milhares de tickets no Jira
A IA pode registrar todas essas decisões e contextos dispersos e fazer perguntas quando algo entrar em contradição com escolhas passadas
Poderia dar um retorno como: “A razão pela qual o Jim escreveu esse código assim 5 anos atrás ainda é válida?”
Esse texto me pareceu meio estranho
Receber uma especificação incompleta e resolver por tentativa e erro é igual para desenvolvedores humanos e para IA
Se você sabe claramente o que quer, faz sentido dar instruções detalhadas
Talvez o ponto do texto seja falar de “especificações ruins”
No geral, parece mais uma lógica de autodefesa da indústria Agile
Eu usei SDD com vários arquivos de especificação em Markdown, e a única coisa realmente eficiente foi o beads
Ele permite que o agente siga a árvore de tarefas e mantenha o foco
Divide cada tarefa com TDD e impede avançar para a próxima etapa antes de passar nos testes
O agente ainda informa até os comandos de review, o que facilita a revisão de código
O Spec-Kit é pesado demais, então o beads é muito mais prático
Até o projeto zmx, que foi feito inteiramente no estilo vibe, mais tarde foi totalmente reescrito com base no código de referência do agente