A Spec É o Novo Código

De Onde Veio a Ideia de Escrever Antes de Construir

Durante décadas, a engenharia de software seguiu um ritual familiar: alguém descreve o que quer, outra pessoa traduz isso em código, e todo mundo torce para que o resultado corresponda à expectativa. Esse processo funcionou — mais ou menos. Funcionou com dor, retrabalho e reuniões intermináveis para alinhar o que deveria ter sido óbvio desde o começo. Especificações existiam, claro. Mas eram documentos longos que ninguém lia, escritos antes do projeto e abandonados na primeira semana de sprint.

A ideia de usar especificações formais como guia de desenvolvimento não nasceu agora. Na computação distribuída e em protocolos de comunicação como RPC, specs já serviam como contratos entre sistemas heterogêneos — definindo validação de tipos, rotas, interceptores e observabilidade. No Behavior-Driven Development, serviam como veículo de colaboração com o negócio. A diferença é que essas specs eram lidas por humanos. O que mudou em 2025 é que agora as specs são lidas, interpretadas e executadas por máquinas.

A convergência de três forças criou o cenário perfeito. Primeiro, os modelos de linguagem cresceram em capacidade e em janela de contexto — o Claude opera com 200 mil tokens, o Gemini com até dois milhões. Segundo, os agentes de codificação como Cursor, Windsurf e Claude Code passaram a separar a fase de planejamento da fase de implementação. Terceiro, pesquisadores começaram a medir o que acontece quando você dá código gerado por IA direto para produção sem nenhuma verificação estrutural: vulnerabilidades em até 42% dos outputs, segundo estudo de Yan et al. publicado em 2025.

O Spec-Driven Development — ou SDD — é o nome que a indústria deu a essa prática. A Thoughtworks o identificou como uma das práticas mais importantes surgidas em 2025. O Technology Radar volume 33 o colocou no anel “Assess”. O GitHub lançou o Spec Kit, que em fevereiro de 2026 já acumulava mais de 72 mil estrelas. A AWS construiu o Kiro, uma IDE inteira ao redor da ideia. E Martin Fowler mapeou mais de trinta frameworks de codificação agêntica que adotaram o SDD como fluxo base.

Os Três Padrões de Spec que Você Precisa Conhecer

Antes de mergulhar nas ferramentas, é preciso entender que nem toda especificação funciona da mesma forma. A indústria convergiu para três padrões distintos de SDD, cada um representando um nível diferente de autoridade da spec sobre o código. Pense neles como três marchas de um carro: você escolhe a marcha certa para a estrada que está enfrentando.

O primeiro padrão é o Spec-First Development. Aqui, a equipe escreve a especificação antes de começar a codificar. O código continua sendo o entregável principal, mas a spec funciona como uma cerca que delimita o que o agente de IA pode gerar. É o ponto de entrada mais acessível — exige disciplina, não revolução. Você escreve um documento descrevendo comportamento, contratos de dados, regras de erro. Depois entrega ao agente. O agente codifica. Você revisa.

O segundo padrão é o Spec-Anchored Development. Neste modelo, a spec não desaparece depois que o código é gerado. Ela permanece como documento vivo, referenciada em cada mudança, cada refatoração, cada merge request. Camadas de governança, restrições constitucionais e checkpoints de supervisão humana são adicionados ao fluxo. A spec aqui não apenas guia — ela governa. É a diferença entre um GPS que sugere uma rota e um controlador de tráfego aéreo que impede colisões.

O terceiro padrão — o mais radical — é o Spec-as-Source Development. Aqui, a especificação literalmente se torna o código-fonte. Não há mais tradução manual. A spec é o artefato primário do desenvolvimento. O código é um efeito colateral, gerado automaticamente, validado automaticamente, mantido automaticamente. Esse padrão ainda está na ponta da experimentação, mas é para onde a indústria aponta.

A escolha entre os três padrões não é uma questão de maturidade linear. Um projeto greenfield de baixa complexidade funciona perfeitamente com Spec-First. Uma plataforma de pagamentos com requisitos regulatórios exige Spec-Anchored. Uma organização que quer reduzir radicalmente o tempo entre intenção e produção experimenta com Spec-as-Source. O padrão certo depende do risco que você está disposto a aceitar — e do rigor que está disposto a investir.

Existe também uma distinção importante entre a spec e o que alguns frameworks chamam de memory bank — arquivos de contexto geral do projeto como regras de estilo, descrições de alto nível da arquitetura e convenções do time. O memory bank é relevante em todas as sessões de codificação. A spec é relevante apenas para a tarefa que cria ou modifica aquela funcionalidade específica. Confundir os dois é um erro comum — e caro.

A Anatomia de uma Spec que Funciona

Uma spec mal escrita é pior do que nenhuma spec. Isso não é exagero — é o que os primeiros adotantes do SDD descobriram na prática. Quando você dá a um agente de IA uma especificação vaga, ele não pede esclarecimento. Ele inventa. Ele preenche os espaços em branco com suposições plausíveis que passam nos testes unitários e explodem em produção. Um estudo da SonarQube analisando cinco LLMs gerando código Java encontrou que mais de 70% das vulnerabilidades do Llama 3.2 90B foram classificadas como severidade BLOCKER.

A boa notícia é que escrever uma spec eficaz não exige uma linguagem nova. Specs são escritas em linguagem natural — português, inglês, o idioma que sua equipe domina. O que exigem é precisão na descrição do comportamento desejado. Não o que o sistema é, mas o que o sistema faz em cada cenário, inclusive nos cenários de erro.

Uma spec funcional precisa cobrir cinco dimensões. Primeiro, o comportamento esperado: o que acontece quando tudo funciona. Segundo, os contratos de dados: formatos de entrada e saída, validações, tipos. Terceiro, os pontos de integração: quais sistemas externos são chamados, com quais protocolos, com quais timeouts. Quarto, a estratégia de erro: o que acontece quando algo falha, como o sistema se recupera, o que o usuário vê. Quinto, as restrições arquiteturais: decisões de design que não devem ser violadas, como escolha de framework, padrões de segurança, requisitos de performance.

Addy Osmani, engenheiro do Google Chrome e autor de referência em padrões JavaScript, publicou em janeiro de 2026 um guia prático sobre specs para agentes de IA. Sua recomendação central é começar com um brief conciso de alto nível e deixar o agente expandir em plano detalhado. Isso aproveita a força do modelo em elaboração enquanto o humano mantém controle da direção. A segunda recomendação é pensar em Agent Experience — projetar a spec para ser facilmente consumida pela máquina, usando formatos parseáveis como OpenAPI, arquivos llms.txt e definições de tipo explícitas.

Mas talvez a lição mais contraintuitiva seja esta: contexto pequeno e focado supera um prompt gigante. Mesmo com janelas de contexto de milhões de tokens, pesquisa da Chroma em 2025 mostrou que a acurácia dos modelos cai conforme o volume de tokens cresce — porque a atenção é um recurso fixo. Os pesos sempre somam 1. Mais tokens significa menos atenção por fragmento. É como uma lanterna: quanto mais largo o feixe, mais fraca a luz em cada ponto.

As Ferramentas, os Tamanhos e o Fluxo Real

Na prática, a escolha da ferramenta de SDD determina o formato e o tamanho da spec. Mais de quinze plataformas foram lançadas entre 2024 e 2025, organizadas em três categorias: IDEs nativas de IA, ferramentas de linha de comando, e extensões integradas a editores existentes. Não existe uma ferramenta “melhor” — existe a mais adequada ao tamanho do time, ao tipo de projeto e à infraestrutura existente.

O AWS Kiro é o exemplo mais estruturado. Opera em três fases: Specify → Design → Tasks. O agente converte prompts em linguagem natural em requisitos formais usando notação EARS, depois gera arquitetura e design de sistema, e finalmente cria um plano de implementação com tarefas discretas e sequenciadas por dependência. A spec vive em três arquivos Markdown dentro do diretório .kiro/specs/: requirements.md, design.md e tasks.md. O formato é Markdown puro — sem linguagem proprietária.

O GitHub Spec Kit segue um fluxo similar em quatro fases: Specify → Plan → Tasks → Implement, com checkpoints humanos entre cada uma. É open-source, funciona como CLI Python, e suporta mais de quatorze plataformas de agente. A spec aqui é um documento Markdown que descreve jornadas do usuário, requisitos de negócio e critérios de sucesso.

E qual o tamanho ideal de uma spec? Depende da complexidade do que você está construindo:

1. 01
   Função simples — 15 a 30 minutos

   Uma função isolada com inputs e outputs claros. A spec cabe em um parágrafo: comportamento, tipos, exceções. Exemplo: validar CPF com dígitos verificadores.

2. 02
   Endpoint de API — 1 a 2 horas

   Inclui edge cases, validação de entrada, tratamento de erros e documentação de contrato. A spec ocupa uma a duas páginas. Exemplo: POST /charges com chave de idempotência.

3. 03
   Componente ou módulo — 2 a 4 horas

   Unidades multi-função com dependências internas. A spec descreve interfaces públicas, estado interno e interações com outros módulos. Exemplo: sistema de notificações com preferências por canal.

4. 04
   Arquitetura de sistema — 8 a 16 horas

   Especificações multi-componente cobrindo seleção de framework, design de banco de dados, padrões de autenticação e integrações. A spec vira um conjunto de documentos inter-referenciados.

5. 05
   Skills e subagentes — tempo variável

   Para specs muito grandes, divida em sub-specs atribuídas a agentes especializados. Um subagente cuida do modelo de dados, outro dos endpoints de API, outro da infraestrutura. Cada um opera com contexto menor e papel mais focado.

Um ponto que merece atenção especial: os formatos de arquivo para agentes. Existem hoje três convenções principais. O AGENTS.md, promovido pelo GitHub e adotado pelo Codex, funciona como um “README para agentes” — Markdown puro sem campos obrigatórios, descoberto automaticamente pelo agente na raiz do repositório. O CLAUDE.md funciona de forma similar para o Claude Code. E os arquivos de steering do Kiro (.kiro/steering/) permitem configurar padrões de código, convenções de teste e políticas de segurança que o agente respeita em cada sessão. A hierarquia de descoberta é sempre do geral para o específico: arquivo na raiz → arquivos em subdiretórios → overrides locais.

Três nomes que definem o pensamento atual sobre specs para agentes:

Por Que Quem Escreve Melhor Vai Construir Mais

A transformação mais profunda do Spec-Driven Development não é técnica — é cultural. O que muda é a definição de “qualidade de engenharia”. Durante toda a história do software, qualidade significava código limpo, testes verdes, deploys sem downtime. No paradigma agêntico, qualidade significa especificações rigorosas o suficiente para gerar código confiável de forma consistente. Um engenheiro júnior que escreve código rápido mas specs soltas cria um perfil de risco completamente diferente de um sênior que escreve specs disciplinadas com contratos apertados — mesmo que o sênior produza menos linhas de código por dia.

Isso tem consequência direta em como times são estruturados, como fornecedores são avaliados, e como qualidade é medida. O modelo tradicional de avaliação era claro: você verificava padrões de codificação, cobertura de testes, processos de review, cadência de entrega. O SDD não torna nada disso irrelevante, mas adiciona uma dimensão que a maioria das avaliações simplesmente não sonda: a capacidade de escrever especificações precisas o suficiente para gerar output consistente de agentes de IA.

A Gartner prevê que até 2028, 90% dos engenheiros de software corporativo usarão assistentes de IA — contra menos de 14% no início de 2024. Até 2027, pelo menos 55% dos times de engenharia estarão construindo funcionalidades baseadas em LLMs. O papel do desenvolvedor migra de implementação para orquestração, resolução de problemas e design de sistemas. O controle de qualidade migra de testes manuais para validação de outputs de IA contra especificações formais.

Mas é importante ser honesto sobre os limites. O SDD não é para todo projeto. Prototipagem rápida, provas de conceito, exploração criativa — nesses contextos, a estrutura da spec pode ser mais obstáculo que ferramenta. A Thoughtworks alertou especificamente sobre o antipadrão de “especificação pesada antecipada com releases big-bang” — que é exatamente o erro que o movimento ágil nasceu para corrigir, décadas atrás. O SDD funciona melhor quando combinado com iteração: spec parcial → implementação → validação → refinamento da spec → próximo ciclo.

Também é honesto dizer que agentes ainda não seguem specs perfeitamente. Birgitta Böckeler, da Thoughtworks, relatou que mesmo com todos os arquivos, templates e workflows definidos, o agente frequentemente ignorava instruções ou as seguia com entusiasmo excessivo. Uma janela de contexto maior não significa que o modelo vai processar tudo que está dentro dela com igual atenção. A pesquisa de Chroma confirma: atenção é recurso finito, independentemente do tamanho do container.

O que o SDD faz de verdade é tornar boas práticas de engenharia inevitáveis. Specs fracas ficam impossíveis de ignorar quando o output do agente depende diretamente delas. Decisões arquiteturais ficam explícitas, revisáveis e evoluíveis — em vez de presas em threads de email, documentos espalhados ou na cabeça de alguém que pode sair da empresa amanhã.

A pergunta que resta não é se você vai adotar o SDD. É se vai adotá-lo quando ainda pode escolher como — ou quando não tiver mais escolha.