O desenvolvimento orientado por especificações ganhou força este ano, principalmente com o avanço dos agentes de código. O GitHub lançou o Spec Kit. A Amazon criou o Kiro. Frameworks como Tessl e BMad surgiram propondo a mesma lógica básica: escreva primeiro a especificação e deixe o agente cuidar do restante.

Essa abordagem levanta uma questão: quando um agente escreve o código, onde está a fonte da verdade? No código? Ou na especificação escrita por uma pessoa?

A resposta muda a forma como um time deve criar, revisar e manter software daqui para frente. Hoje, a maioria das equipes está respondendo a essa pergunta por acaso, e não por uma decisão consciente.

O que é desenvolvimento orientado por especificações?

Em sua forma mais simples, o desenvolvimento orientado por especificações transfere o trabalho de escrever código diretamente para a criação de uma especificação. Uma LLM lê essa especificação e escreve o código. Cada vez mais, a especificação funciona como o principal artefato para um agente que passa por ciclos de criação, teste e refinamento até que o código seja aprovado nos testes.

Para obter bons resultados, o desenvolvedor precisa criar uma especificação completa. Mais do que uma lista de funcionalidades e uma descrição do processo, uma boa especificação inclui requisitos, restrições, casos de exceção e o raciocínio por trás das decisões de design.

Quando bem aplicado, o desenvolvimento orientado por especificações acelera a construção, reduz retrabalho e minimiza surpresas depois que algo entra em produção. É a lógica de medir duas vezes e cortar uma. Com uma diferença: aqui, você guarda as medidas para depois, e a próxima pessoa não precisa começar tudo do zero.

A intenção nunca chega intacta ao código

Entregue a mesma especificação a mil desenvolvedores e você terá mil bases de código diferentes, todas defensáveis. Isso não é novidade.

Ao longo do tempo, as organizações criaram convenções e processos de revisão que direcionam o código para padrões mais previsíveis e compreensíveis, pelo menos dentro da própria organização. Agentes eliminam parte desse processo humano gradual, mas não eliminam o não determinismo que tornou esse processo necessário. Na verdade, podem até amplificá-lo.

Peça ao mesmo agente para criar o mesmo código duas vezes e você poderá receber duas implementações diferentes. Isso não é um problema para uma primeira versão. Mas é quando você está construindo algo que precisa funcionar como uma infraestrutura duradoura.

Isso não é um argumento contra o desenvolvimento orientado por especificações. É justamente a razão para adotá-lo. A especificação nunca teve como objetivo tornar todas as implementações idênticas. Seu papel é garantir que o raciocínio por trás do que foi construído permaneça registrado, independentemente da versão que um agente produza.

Tentar reconstruir a intenção a partir do código não funciona

Uma especificação não deveria ser necessária quando o código pode falar por si mesmo, certo? Essa é uma armadilha.

Na melhor das hipóteses, o código mostra o que faz. Muitas vezes, nem isso. Parte de seu comportamento pode ser controlada por sistemas upstream ou arquivos de configuração que não estão visíveis.

E, mesmo quando o código consegue mostrar o que faz, ele não consegue explicar por quê.

Muitos de nós já olhamos para um script sem entender as escolhas feitas pelo desenvolvedor anterior, apenas para perceber depois que nós mesmos éramos esse desenvolvedor. Se não conseguimos reconstruir o raciocínio por trás das nossas próprias decisões, como faremos isso com um código legado de 15 anos escrito por alguém que já deixou a empresa?

Desenvolver software exige fazer escolhas dentro de determinadas restrições. O código carrega as marcas dessas decisões, mas não as explica. Se você investigar por tempo suficiente, talvez consiga entender os trade-offs envolvidos. Talvez.

Uma especificação evita esse trabalho. Além de registrar restrições e trade-offs, ela explica a lógica por trás das principais decisões.

Qual é o problema do vibe coding?

A complexidade e a criticidade dos sistemas corporativos explicam por que times de desenvolvimento frequentemente passam semanas elaborando uma especificação antes de começar um novo projeto. Se pularem essa etapa e forem direto para o agente de código, a conta chega depois. Com juros.

Sem uma intenção de design definida antes do início do desenvolvimento, agentes de código repetem lógicas pela base de código. Não separam responsabilidades adequadamente. Criam tratamentos de erros e logs inconsistentes entre diferentes módulos.

Essa inconsistência traz consequências em produção. Quando os logs não seguem um padrão, encontrar a causa raiz de um incidente demora mais. Cada minuto que um engenheiro de plantão passa tentando entender o formato ou o conteúdo de um log é mais um minuto com o incidente em aberto.

Essa é a armadilha da velocidade. Pular o design permite chegar mais rápido a uma primeira versão. Mas o custo de cada mudança posterior aumenta.

Velocidade sustentável vem de tomar decisões arquiteturais quando elas realmente importam: no início. A alternativa é fazer o time compensar posteriormente decisões que nunca foram tomadas e que já começaram a causar problemas.

Um plano não é uma especificação

Alguns produtos adotaram uma abordagem intermediária entre desenvolvimento orientado por especificações e vibe coding. Chamamos esse modelo de “Prompt, Plan, Build”.

Temos visto essa abordagem em contextos nos quais times técnicos trabalham por meio de uma plataforma que funciona como uma camada entre eles e o código.

O “Prompt, Plan, Build” funciona assim: por meio de uma AI IDE, o usuário descreve o que deseja fazer, como conectar Salesforce ao SAP. A AI IDE usa o MCP da plataforma para acessar ferramentas e apresentar um plano. Depois que o usuário aprova esse plano, o agente segue com a execução.

É uma evolução em relação ao vibe coding, mas ainda não é suficiente. Os usuários podem discordar do plano e solicitar alterações, mas o sistema não investiga aquilo que eles podem ter deixado de considerar.

Para resolver esse problema, criamos o Digibee Digital Worker (DDW). O DDW estabelece um diálogo que explora casos de exceção e trade-offs em vez de simplesmente fazer suposições e partir direto para a construção.

Essa primeira etapa leva mais tempo do que no modelo Prompt, Plan, Build, mas gera uma especificação detalhada para orientar a construção e servir como referência posteriormente.

Quando sistemas de Prompt, Plan, Build chegam a produzir algo semelhante a uma especificação, normalmente isso acontece como consequência da construção. É um resumo do que aconteceu, e não um artefato revisado antes que qualquer coisa seja construída.

Essa diferença importa. Sem uma análise detalhada no início, os trade-offs são definidos por padrão, sem que nenhuma pessoa tenha concordado com as suposições feitas pela IA.

“Muitos clientes com quem conversei tratam a documentação como algo para depois. Às vezes, ela nem existe. Aqui, você já recebe isso antes mesmo de começar a construção.”

— Jeyaram Deivachandran, Head of Forward Deployed Engineering da Digibee

A especificação é o que fica

O código já não dura tanto quanto antes. Frameworks vêm e vão. Uma stack que parecia atual há três anos pode parecer ultrapassada hoje. Se o único registro da lógica do seu negócio estiver em um script dentro de uma ferramenta que será descontinuada, você tem um problema.

É aqui que a especificação mostra seu valor. Esses documentos detalhados podem inicialmente servir para manter um agente de código no caminho certo, mas continuam relevantes no futuro. O raciocínio registrado neles sobrevive a uma migração de framework. Sobrevive à troca de integrantes do time. Sobrevive a uma atualização de modelo que muda a forma como o agente escreve código.

Claro, isso significa que o time precisa atualizar a especificação junto com o código em produção. É um trabalho que precisa ser feito, mas a Digibee incorpora esse processo ao DDW. Atualize a especificação e o DDW reconstrói a integração.

O código será reescrito. O raciocínio, se estiver registrado em um lugar duradouro, não precisa ser redescoberto do zero toda vez.

O que uma especificação de verdade oferece ao time

Uma especificação de verdade reúne em um só lugar as contribuições de diferentes funções, como arquitetos, desenvolvedores, testers e analistas de negócio, em vez de deixá-las espalhadas por conversas isoladas.

Todos conseguem visualizar as questões em aberto, entender por que elas importam e acompanhar o nível de completude da especificação. Também é possível atribuir a um stakeholder de negócio ou administrador de sistemas a parte do problema que cabe a ele, sabendo que tudo continuará sendo acompanhado.

Isso ajuda a identificar conflitos antes que um teste falhe mais adiante e alguém precise descobrir o motivo. Também faz com que a documentação seja produzida como parte natural da construção, em vez de virar uma tarefa posterior que frequentemente acaba esquecida.

A especificação preserva todo o raciocínio por trás do sistema fora da janela de contexto, evitando que ele seja perdido em uma compactação de contexto ou no reinício de uma sessão.

Ela também funciona como um guardrail. Quando os trade-offs são identificados de forma proativa em vez de permanecerem implícitos, a qualidade do resultado deixa de depender tanto da senioridade da pessoa que está criando os prompts.

Um cliente da Digibee afirmou que a abordagem dos DDWs para desenvolvimento orientado por especificações economizaria tempo ao eliminar idas e vindas entre os times de negócio e desenvolvimento. Pessoas sem conhecimento técnico poderiam consultar os fluxogramas e as descrições dos processos gerados pelo sistema e entender diretamente o comportamento esperado das integrações, sem depender da interpretação de um desenvolvedor.

Artefatos diferentes, funções diferentes

O código passa por controle de mudanças. É nele que confiamos às três da manhã quando alguma coisa quebra. Ele é avaliado pelo determinismo: faz a mesma coisa, sempre, de forma confiável, sob carga e mesmo em situações extremas?

A especificação registra e documenta o raciocínio revisado por trás das decisões que levaram àquele código. Ela é avaliada pela durabilidade: ainda consegue explicar corretamente o sistema daqui a um ano, depois que o framework foi substituído e metade do time original já mudou?

Nenhum dos dois funciona sozinho.

Código sem especificação vira um trabalho de arqueologia sempre que alguém novo precisa mexer nele. Uma especificação sem código funcionando é apenas uma opinião bem organizada.

Cada um cumpre uma função diferente. O erro é tentar substituir um pelo outro. Times tratam a especificação como se ela devesse determinar o comportamento com a mesma precisão do código ou tratam o código como se ele pudesse explicar a si mesmo da mesma forma que uma especificação.

Quando essa divisão funciona, os benefícios se acumulam: decisões são tomadas e revisadas uma vez e reaproveitadas em todos os projetos futuros que enfrentarem o mesmo problema.

Caso contrário, alguém terá que explicar o código novamente do zero, para cada nova sessão, cada novo integrante do time e cada novo agente que vier depois.

Tenha acesso antecipado à primeira plataforma de integração AI-native →

‍