Desenvolvimento orientado por especificações

O desenvolvimento orientado por especificações pode não ter a mesma visibilidade de um termo como vibe coding, mas, ainda assim, é uma das práticas mais importantes a surgir em 2025. Ele também evidencia o quão rapidamente a engenharia de software evoluiu nos últimos meses, à medida que se adaptou a novas ferramentas de IA e encontrou novas formas de aproveitá-las.

No entanto, como acontece com qualquer novo termo ou prática, entender exatamente do que se trata não é simples. Também surgem questionamentos sobre o quão eficaz é uma técnica em que tudo parece ser definido antecipadamente: será que podemos realmente considerá-la ágil? Neste post, vou explorar minha visão sobre o que é o desenvolvimento orientado por especificações e discutir como ele vem sendo aplicado na prática.

Definindo o desenvolvimento orientado por especificações e as interpretações concorrentes sobre ele

O meu entendimento sobre o desenvolvimento orientado por especificações (spec-driven development – SDD) é que se trata de um paradigma de desenvolvimento que utiliza especificações de requisitos de software bem elaboradas como prompts, com o apoio de agentes de codificação baseados em IA, para gerar código executável.
 

Vale destacar, no entanto, que existem diferentes opiniões na indústria sobre o que exatamente é uma spec (especificação) e qual o seu papel no SDD. No extremo mais radical desse espectro, há quem defenda que já podemos descartar o código e tratar as especificações como a única fonte de verdade que precisa ser mantida. Nessa visão, o código seria uma espécie de subproduto, um artefato intermediário entre os requisitos e os binários compilados. Em contraste, profissionais mais tradicionais — como eu — acreditam que as especificações são apenas elementos que orientam a geração de código, assim como acontece no desenvolvimento orientado a testes (test-driven development). O código executável continua sendo a fonte de verdade que precisa ser mantida.
 

Parte da razão para essa divergência está na forma como as abordagens evoluíram nos últimos dois anos, desde que a indústria passou a usar IA generativa para produzir código. Quando começamos a explorar a programação de forma mais séria com o ChatGPT, percebemos que o código gerado a partir da definição de especificações técnicas (stack tecnológica, estilo arquitetural, estilo de codificação), usando chain-of-thought e few-shot prompting, apresentava qualidade significativamente superior em comparação ao código gerado a partir de requisitos em texto livre. Mais recentemente, porém, à medida que as ferramentas de codificação com IA evoluíram, tornou-se mais fácil incorporar também os requisitos funcionais ao processo.
 

Embora isso traga benefícios claros, não podemos depender apenas dos requisitos funcionais: é fundamental prestar atenção aos detalhes técnicos.

O contexto do surgimento do desenvolvimento orientado por especificações

Manipular computadores por meio de linguagem natural que represente o negócio sempre foi o “santo graal” do desenvolvimento de software e da teoria das linguagens de programação. Na verdade, as tentativas de geração de código orientada por especificações antecedem a era dos LLMs — elas apenas nunca chegaram a um nível de adoção no desenvolvimento real.

As especificações já foram usadas de diversas formas na engenharia de software. Em computação distribuída e comunicação via RPC, por exemplo, as specs atuam como contratos de comunicação entre sistemas heterogêneos distintos. Isso geralmente envolve muito trabalho repetitivo e transversal entre camadas, incluindo validação de tipos de dados entre linguagens, roteamento, interceptores e observabilidade.

No desenvolvimento orientado a comportamento (behavior-driven development – BDD), por sua vez, as especificações são usadas como um meio para facilitar a colaboração com pessoas de negócio. Normalmente, elas são escritas na forma de cenários e exemplos e tratadas como documentos vivos do comportamento do sistema. Esse processo é sustentado por mecanismos de testes automatizados e integração contínua.

Independentemente da forma como são utilizadas, as especificações são, em essência, instruções baseadas em texto — e, considerando a capacidade dos LLMs de manipular texto, não é surpreendente que as specs se integrem tão bem ao crescimento da IA na engenharia de software.

É claro que os primeiros assistentes de programação, como o GitHub Copilot, tinham foco apenas na geração de trechos de código. Foi somente com o aumento das janelas de contexto dos modelos fundacionais que se tornou mais viável escrever código e construir software diretamente a partir de requisitos expressos em linguagem natural.

Para viabilizar isso, os agentes de codificação mais recentes baseados em IA geralmente separam, de alguma forma, as fases de planejamento e implementação do processo de desenvolvimento. A fase de planejamento concentra-se na compreensão dos requisitos, no desenho de restrições e na curadoria mais cuidadosa de prompts para as etapas seguintes. Esse processo é, essencialmente, a criação da especificação, que acaba formando a base do desenvolvimento orientado por especificações.

O que é uma spec?

Uma especificação é definitivamente mais do que apenas um documento de requisitos de produto (Product Requirements Document – PRD). Mesmo a simples aplicação de prompts mais estruturados e de restrições técnicas mais explícitas já pode gerar código de melhor qualidade do que um PRD em texto livre.

Do ponto de vista técnico, uma especificação deve definir explicitamente o comportamento externo do software-alvo — incluindo mapeamentos de entrada e saída, pré-condições e pós-condições, invariantes, restrições, tipos de interface, contratos de integração e lógica sequencial ou máquinas de estado.

No passado, as especificações eram frequentemente escritas em formatos altamente formalizados e legíveis por máquina. Hoje, com o auxílio dos LLMs, podemos descrevê-las usando linguagem natural. Essencialmente, no entanto, uma especificação continua definindo o comportamento do software-alvo; ela não se limita a descrever requisitos de negócio.

O que faz uma boa spec?

Nossas experiências com desenvolvimento orientado a comportamento (behavior-driven development – BDD) continuam válidas. Essa nova tecnologia não deveria, na prática, mudar tanto assim esse aspecto.

Por exemplo, as especificações ainda devem usar uma linguagem ubíqua orientada ao domínio para descrever a intenção do negócio, em vez de implementações específicas atreladas à tecnologia. Elas também devem ter uma estrutura clara, com um estilo consistente para definir cenários usando Given/When/Then, e buscar um equilíbrio entre completude e concisão, cobrindo o caminho crítico sem enumerar todos os casos possíveis. Isso traz um benefício adicional no desenvolvimento de software assistido por IA, pois ajuda a economizar tokens.

Também é importante que as especificações busquem clareza e determinismo. Embora os LLMs não gerem código determinístico como os processos tradicionais de geração de código, compilação ou execução de testes automatizados, especificações claras ainda podem ajudar a reduzir alucinações do modelo e produzir código mais robusto.

No entanto, apesar de os LLMs se destacarem principalmente no processamento de linguagem natural, não devemos subestimar o papel de entradas e saídas estruturadas. A experiência mostra que fornecer ao modelo prompts de entrada semiestruturados ou forçar saídas estruturadas pode melhorar significativamente o desempenho de raciocínio e reduzir alucinações. Assim, especificações legíveis por máquina continuam sendo essenciais na era dos LLMs.

Por fim, no que diz respeito à organização dos arquivos de especificação, muitos defendem a separação entre especificações de requisitos de negócio e especificações técnicas. Porém, na prática, definir claramente essa fronteira nem sempre é simples.

Spec-driven development na prática

Os fluxos de trabalho de SDD na prática podem variar bastante dependendo das ferramentas utilizadas. Ferramentas como Amazon Kiro e GitHub Spec-Kit oferecem alguns fluxos de trabalho predefinidos. Já ao usar ferramentas de codificação com IA mais metodologicamente neutras, como Cursor ou Claude Code, é necessário definir um fluxo que melhor atenda às suas necessidades.

O núcleo do SDD vai além do vibe coding, ao separar explicitamente as fases de design e implementação. Na fase de planejamento, os requisitos são inicialmente analisados por um agente de codificação com IA, que gera planos de design e de implementação. Normalmente, essas especificações de requisitos são formalizadas em diferentes arquivos Markdown (.md). A revisão e validação dessas especificações costuma ser um processo iterativo que exige a presença de um humano no loop.

Uma vez que as especificações estejam finalizadas, elas são entregues ao agente de codificação para gerar o código do produto, com base nos requisitos técnicos definidos — como estilo arquitetural e restrições — configurados em regras do Cursor ou no arquivo AGENTS.md.

Existem diferentes visões sobre se as especificações são apenas artefatos intermediários e descartáveis do processo ou se representam a verdade última sobre o comportamento do software. Essas perspectivas distintas também resultam em variações nos fluxos de trabalho para curadoria e manutenção das especificações, bem como na geração de código.

Spec-driven development e context engineering

Costumo dizer que prompt engineering otimiza a interação entre humanos e LLMs, enquanto context engineering otimiza a interação entre agentes e LLMs. Isso acontece porque agentes de IA geralmente precisam de mais informações e de janelas de contexto maiores para executar tarefas, o que representa um desafio significativo para a capacidade de processamento dos LLMs.

Como tarefas de codificação exigem uma grande quantidade de informação contextual, é fundamental curar esse contexto com cuidado. Ferramentas de agentes de codificação, juntamente com arquivos AGENTS.md predefinidos, normalmente fornecem um bom system prompt.

O spec-by-example que usamos com frequência em BDD é, essencialmente, uma aplicação da técnica de few-shot prompting. Separar a análise e o planejamento dos requisitos da fase de implementação do código comprime o contexto nas próprias especificações. Servidores MCP, como o Context7, também podem nos fornecer informações de documentação em tempo real.

Nossa ferramenta CodeConcise extrai a estrutura do código e as dependências de bases de código legadas, constrói um grafo de conhecimento em bancos de dados vetoriais e de grafos e pode se integrar a servidores MCP como JIRA e Confluence para apoiar a geração posterior de código. Muitas práticas de context engineering podem ser aplicadas ao spec-driven development.

O spec-driven development é apenas um retorno ao waterfall?

Já ouvi algumas pessoas afirmarem que isso seria um retorno ao waterfall — e não sem certa razão —, mas acredito que desta vez o contexto é diferente.

O principal problema do desenvolvimento waterfall tradicional é o excesso de ciclos longos de feedback. Ele sofre com um distanciamento entre o design do software e a implementação, o que leva ao surgimento de uma “arquitetura sombra” e a uma enorme ineficiência causada pela necessidade de manter código, documentação e testes continuamente à medida que os requisitos mudam.

Os desafios que enfrentamos hoje com a codificação assistida por IA são diferentes. Eles surgem do fato de que o vibe coding é rápido demais, espontâneo e desorganizado. Como é extremamente fácil para a IA gerar protótipos demonstráveis, muitas pessoas acabam negligenciando a importância de boas práticas de engenharia, o que resulta em um grande volume de código descartável, difícil de manter e com defeitos.

Por isso, é fundamental trazer para o centro do processo uma análise séria de requisitos, um design de software criterioso, restrições arquiteturais necessárias e governança com humanos no loop. Eu diria que é exatamente isso que o spec-driven development nos ajuda a fazer. Ele não cria grandes ciclos de feedback como o waterfall — ao contrário, oferece um mecanismo para ciclos de feedback mais curtos e mais eficazes do que aqueles que seriam possíveis com vibe coding puro.

Os desafios e riscos do spec-driven development

Como mencionado anteriormente, há uma falta de consenso sobre o fluxo de trabalho "correto" do spec-driven development e sobre como exatamente uma boa spec deve ser no contexto da codificação assistida por IA. Embora eu obviamente tenha minha opinião sobre o que faz uma boa spec, ela é baseada na minha experiência — ainda não existe uma maneira sistemática de avaliar as specs como fazemos com as evals, por exemplo.

A geração de código a partir de spec para LLMs não é determinística; isso gera desafios quando se trata de upgrades e manutenção. A spec drift e a hallucination são dificuldades inerentes e difíceis de evitar, portanto, ainda precisamos de práticas CI/CD altamente determinísticas para garantir a qualidade do software e proteger nossas arquiteturas.

Finalmente, a questão de saber se a spec ou o código é o artefato definitivo do desenvolvimento de software ainda precisa ser explorada. As duas abordagens levam a fluxos de trabalho e práticas de desenvolvimento completamente diferentes. Programadores experientes podem perceber que specs excessivamente formalizadas podem causar problemas desnecessários e desacelerar os ciclos de mudança e feedback — assim como encontramos nos primeiros estágios do desenvolvimento waterfall.

O spec-driven development continua sendo uma prática emergente à medida que 2025 chega ao fim, e é provável que vejamos ainda mais mudanças em 2026. Isso torna fundamental acompanhar de perto o pensamento da indústria e os experimentos que estão sendo realizados. Na Thoughtworks, continuaremos a experimentar e, naturalmente, a compartilhar nossos aprendizados e insights com o restante da comunidade de software.