Spec-Driven Development: quando o design vira contrato

O que é Spec-Driven Development

Spec-Driven Development, ou desenvolvimento orientado por especificação, é uma abordagem em que você escreve uma descrição detalhada e precisa do que o sistema deve fazer antes de qualquer linha de código ser escrita. Essa descrição é o spec, uma abreviação de specification, ou especificação.

O spec não é um briefing vago. É um documento que funciona como contrato. Ele descreve: o que o sistema faz, como se comporta em cada situação, quais são os estados possíveis, o que acontece quando algo dá errado, quais são as regras de negócio. Quanto mais detalhado, menos espaço para interpretação errada.

Por que designers se beneficiam

Aqui vem o ponto que vai mudar a sua perspectiva: o spec é, no fundo, o design system descrito em palavras. Quando você projeta um componente no Figma e documenta seus estados (default, hover, disabled, loading, error), suas propriedades (tamanho, cor, variantes), seu comportamento (o que acontece ao clicar, ao receber foco, ao perder conexão), você já está escrevendo um spec.

A diferença é que a maioria dos designers para no Figma. O spec pega tudo isso e traduz para um formato que desenvolvedores e ferramentas de IA conseguem usar como guia. E é aí que acontece a mágica: quando você dá um spec detalhado para uma IA como Claude ou Cursor, o código gerado é drasticamente melhor do que quando você dá uma instrução vaga.

Pense comigo: se o vibe coding é "cria um formulário de login", o spec-driven é:

• Formulário de login com campos de e-mail e senha
• Estado default: campos vazios, botão desabilitado
• Validação de e-mail: formato válido, mensagem de erro inline abaixo do campo
• Validação de senha: mínimo 8 caracteres, indicador de força
• Estado loading: botão com spinner, campos desabilitados
• Estado erro: mensagem "E-mail ou senha incorretos" acima do formulário, em vermelho (#dc2626)
• Estado sucesso: redireciona para /dashboard
• Link "Esqueceu a senha?" abaixo do formulário

Viu? Nenhum código. Só descrição de comportamento. E você, como designer, sabe descrever comportamento melhor do que a maioria dos devs, porque você pensa na experiência completa, não só no happy path.

Como funciona na prática

O fluxo do spec-driven development com IA segue uma lógica que se encaixa naturalmente no processo de design:

1. Designer + PM escrevem o spec juntos: o designer traz a perspectiva do usuário (estados, interações, edge cases visuais). O PM traz as regras de negócio. O resultado é um documento completo.
2. O spec vira o "contrato": o time todo concorda com o que está escrito. Design, dev e produto falam a mesma língua. Não tem espaço para "eu achei que era assim".
3. IA usa o spec para gerar código: ferramentas como Claude Code e Cursor recebem o spec e geram código que segue as regras descritas. Não é perfeito, mas é muito mais previsível do que geração sem spec.
4. Resultado: menos retrabalho: como todo mundo concordou no spec antes, o código gerado está mais alinhado com o design, e as revisões são sobre detalhes, não sobre "refaz tudo".

Um spec completo na prática: o fluxo de login

Na seção anterior, mostrei um mini-spec do formulário de login. Agora vamos ver como ficaria um spec completo, do tipo que realmente funciona como contrato entre design e engenharia. Repare na diferença de profundidade:

Spec: Fluxo de login com e-mail e senha

Escopo: tela de login para usuários já cadastrados. Não inclui cadastro nem login social.

Layout: formulário centralizado na viewport, largura máxima 400px, padding de 32px. Logo acima do formulário, alinhado ao centro.

Campos:

• E-mail: input type email, placeholder "seu@email.com", autocomplete="email". Validação: formato de e-mail válido. Mensagem de erro inline: "Digite um e-mail válido", exibida abaixo do campo em vermelho (#dc2626) ao perder o foco se inválido.
• Senha: input type password, placeholder "Sua senha", autocomplete="current-password". Ícone de toggle visibilidade (olho aberto/fechado) dentro do campo, à direita. Validação: campo não pode estar vazio. Sem requisito de força neste fluxo (apenas no cadastro).

Botão de submit:

• Estado default: desabilitado (opacity 0.5, cursor not-allowed) enquanto campos estão vazios
• Estado habilitado: ativo quando ambos os campos têm valor, cor primária do sistema
• Estado loading: texto muda para "Entrando...", spinner à esquerda do texto, botão e campos desabilitados, sem duplo-submit
• Estado erro: botão volta ao estado habilitado, foco retorna ao primeiro campo com erro

Tratamento de erros do servidor:

• Credenciais inválidas: mensagem "E-mail ou senha incorretos" em banner acima do formulário, fundo vermelho claro (#fef2f2), borda esquerda vermelha, ícone de alerta. Não indicar se é o e-mail ou a senha que está errado (segurança).
• Conta bloqueada (após 5 tentativas): mensagem "Conta temporariamente bloqueada. Tente novamente em 15 minutos ou redefina sua senha." Link inline para redefinição.
• Erro de servidor (500): mensagem genérica "Algo deu errado. Tente novamente em instantes." Botão "Tentar novamente" que resubmete.
• Sem conexão: mensagem "Sem conexão com a internet. Verifique sua rede e tente novamente." Detectado via navigator.onLine.

Sucesso: redireciona para /dashboard com animação de fade. Token JWT (o crachá de login do usuário) guardado em um httpOnly cookie, mais seguro que o localStorage (a gavetinha do navegador que o código da página consegue ler).

Links auxiliares: "Esqueceu a senha?" abaixo do formulário, à direita. "Criar conta" abaixo, centralizado.

Acessibilidade: todos os campos com label visível (não apenas placeholder). Mensagens de erro vinculadas ao campo via aria-describedby. Formulário inteiro navegável por teclado. Enter submete o formulário. Focus trap no modal de loading.

Viu a diferença? Esse spec cobre o happy path, os erros, os edge cases, a acessibilidade e até decisões de segurança. Um dev ou uma IA que recebe esse documento produz algo radicalmente diferente do que produziria com "faz um login bonito".

Se termos como JWT ou focus trap soaram novos, tudo bem: são detalhes de engenharia dentro do contrato. O que importa para você é o nível de precisão, não decorar cada sigla.

Como specs previnem os problemas do vibe coding

Na página anterior, vimos como vibe coding pode gerar um formulário que quebra com texto em português ou um card que não sobrevive a dados reais. O spec é exatamente o antídoto para esses problemas. Quando você descreve no spec que o campo de nome deve aceitar caracteres acentuados, que o card deve lidar com títulos de até 120 caracteres, que o loading state é obrigatório, esses requisitos deixam de ser "coisas que alguém deveria ter pensado" e viram regras explícitas do contrato.

O vibe coding é a velocidade. O spec é a direção. Juntos, eles são poderosos: você pode usar vibe coding para prototipar rápido e depois escrever o spec para a versão de produção. Mas nunca confunda o protótipo com o produto final.

O diferencial para sua carreira

Se você quer se diferenciar como Product Designer, aprender a escrever specs é ouro. Um designer que entrega no handoff não só as telas, mas um documento que descreve comportamentos, estados, regras e exceções, reduz o retrabalho do time, ganha respeito da engenharia e se posiciona como alguém que pensa em sistema, não só em tela.

Essa é a skill mais valiosa que um Product Designer pode desenvolver em 2026. Saber escrever specs é saber pensar em sistema. É a diferença entre entregar um layout e entregar uma solução completa. Quem domina essa habilidade não compete por vagas, é disputado por times.

E com o avanço da IA no desenvolvimento, quem sabe escrever specs detalhados vai ter uma vantagem absurda: vai conseguir gerar código de qualidade muito superior usando as mesmas ferramentas que todo mundo tem. A ferramenta é a mesma. A instrução é que faz a diferença.