Jonathan Machado
Você descreve a tarefa em três linhas, manda para o assistente de código e recebe 400 linhas de volta. O código roda. A estrutura é limpa. Os nomes das variáveis fazem sentido. E ele resolveu um problema parecido com o seu, não o seu.
Esse é o modo de falha novo. Não é código quebrado, é código plausível e errado, entregue rápido demais para você notar antes de já ter sido integrado.
O SDD é a resposta a isso. E a primeira coisa a resolver é que a sigla tem dois significados diferentes.
SDD tem dois significados. Saiba qual você está usando
Se você buscar a sigla, vai encontrar duas coisas distintas:
- Software Design Document (Documento de Desenho de Software), o sentido clássico: um documento de arquitetura que descreve como o sistema é construído, para quem vier depois entender.
- Spec-Driven Development (Desenvolvimento Orientado por Especificações), o sentido que ganhou uso prático com as ferramentas de desenvolvimento assistidas por IA como Claude Code, Cursor e Copilot: você escreve a especificação primeiro, e ela é o insumo que dirige a geração do código.
A diferença não é acadêmica. No primeiro sentido, o documento é descritivo e vem depois ou junto do código. No segundo, ele é prescritivo e vem antes, porque é literalmente a entrada do processo.
O resto deste artigo trata do segundo sentido, que é o que mudou de peso.
Por que a especificação virou o gargalo
Durante décadas, escrever código foi a parte caríssima. Especificar era rápido e implementar era lento, então valia a pena especificar mal e corrigir no caminho.
Essa economia inverteu. Quando a implementação de uma funcionalidade média sai em minutos, o custo migra inteiro para a etapa anterior: decidir com precisão o que deve ser construído. Uma especificação vaga não fica mais escondida atrás de semanas de desenvolvimento. Ela vira código errado imediatamente, em volume.
É por isso que a queixa mais comum de quem usa esses assistentes não é "a IA não consegue escrever isso". É "a IA fez o que eu pedi, mas não o que eu queria". Essas duas frases descrevem um problema de especificação, não de modelo.
O gargalo nunca foi digitar. Era saber. Só ficou visível agora.
As 6 seções de um SDD que a IA consegue executar
Uma especificação boa para IA tem uma propriedade que uma especificação boa para humano não precisa ter: ela não pode depender de bom senso para ser interpretada. Humano preenche lacuna com contexto. Modelo preenche lacuna com o padrão mais provável do treino, que pode não ser o seu caso.
Este é o formato que usamos na eBuz:
| # | Seção | Função |
| 0 | Fontes da investigação: verificado, não suposto | Trava o que é fato conferido contra o que é hipótese |
| 1 | Problemas nomeados (P1, P2, P3...) | Dá identidade a cada defeito, para poder cobrar depois |
| 2 | Desenho-alvo: decisões (D1, D2, D3...) | Cada decisão declara qual problema ela mata |
| 3 | Fases de implementação | Cada fase entregável sozinha, com gate e rollback |
| 4 | Matriz de verificação (smoke matrix) | O teste que libera cada fase, de preferência em script |
| 5 | Decisões pendentes do dono | O que a execução NÃO pode escolher no lugar de você |
Três dessas seções carregam quase todo o valor. Vale detalhar.
Seção 0: "verificado, não suposto"
É o gate anti-invenção, e o motivo de existir é direto: modelo de linguagem preenche lacuna com fluência. Se a especificação afirma que "a tabela de usuários tem uma coluna de status", o assistente vai escrever código contra essa coluna com total confiança, exista ela ou não.
A seção 0 lista, item por item, o que foi conferido de verdade e como. Nome de arquivo, número de linha, saída de comando, resultado de consulta. O que não foi conferido entra rotulado como hipótese, e uma hipótese nunca vira base de decisão sem antes ser verificada.
Custa dez minutos e elimina a categoria mais chata de erro: aquela em que o código está certo e a premissa estava errada.
Cada decisão tem que matar um problema nomeado
Este é o truque estrutural que mais melhora uma especificação, e é quase gratuito.
Numere os problemas (P1, P2, P3) na seção 1. Numere as decisões (D1, D2, D3) na seção 2. E escreva, ao lado de cada decisão, quais problemas ela resolve: "D1. Resolver a identificação de cliente por dados em vez de por código (mata P1 de forma permanente)".
O efeito é imediato. Toda decisão sem um P do lado é decisão que ninguém pediu, e ela sai. Todo P sem um D é problema que a especificação está fingindo que resolve, e ele volta para a mesa. A tabela de amarração faz a auditoria sozinha.
Gate por fase: a matriz de verificação
Fase sem gate não é fase, é intenção. O gate é a lista de checagens que precisa passar antes de a fase seguinte começar, escrita de forma que dê para rodar em vez de julgar.
Exemplo concreto, desta operação. Uma passada de correção ortográfica trocou 3.345 palavras em 14 artigos publicados deste blog. A especificação definiu o gate antes de qualquer edição:
- o número e a ordem das tags HTML têm que ser idênticos antes e depois;
- a lista de palavras tem que ser idêntica, desconsiderando acento;
- qualquer divergência aborta a gravação, sem gravar nada.
As três checagens rodaram em cada uma das três passadas. Nenhuma quebra estrutural chegou em produção. Isso não foi confiança no processo, foi trava executável: se a especificação estivesse errada, o próprio script recusaria escrever.
É o mesmo princípio de testar rápido e refinar depois, com uma diferença importante: o passo rápido só é seguro quando existe uma verificação automática dizendo que ele não estragou nada.
Seção 5: o que a execução não tem permissão de decidir
Toda especificação tem lacunas que só o dono pode fechar. Preço, nome público, o que fazer com dados antigos, se uma rota pode quebrar.
Se essas lacunas ficam implícitas, alguém decide por você, e a IA decide sempre: ela escolhe a opção mais comum e segue. Listar as decisões pendentes numa seção própria transforma a lacuna em pergunta explícita e bloqueia o início até ela ser respondida. É o oposto de burocracia. É evitar descobrir a decisão depois, lendo o código.
PRD e SDD: o que muda entre os dois
| PRD | SDD | |
| Pergunta | Que problema, e como sabemos que resolvemos | Como construir, em que ordem, com qual gate |
| Vocabulário | Do usuário e do negócio | Do sistema: arquivo, rota, tabela, comando |
| Nível de detalhe | Evita solução de propósito | Prescreve solução de propósito |
| Critério de aceite | Métrica de negócio | Checagem que roda |
| Quem lê | Time e quem decide | Quem executa, humano ou IA |
Os dois não competem, encaixam. O PRD trava o que precisa ser resolvido e o SDD trava como. Pular o PRD e ir direto ao SDD produz uma especificação técnica impecável para um problema que ninguém confirmou existir.
E depois que a escolha de arquitetura é feita, quem guarda o porquê dela é um terceiro documento: o ADR, que registra as alternativas descartadas. Os três juntos cobrem o problema, a execução e a memória da decisão.
Como escrever a sua primeira especificação
Sem template de trinta páginas. Comece com este ciclo, que cabe em uma página:
- Investigue e registre. Abra os arquivos, rode as consultas, colete a saída real. Anote o que conferiu e o que só supôs.
- Nomeie os problemas. P1, P2, P3. Um defeito por linha, na forma observável.
- Decida e amarre. D1, D2, D3, cada um dizendo qual P morre.
- Fatie em fases entregáveis. Cada fase tem que poder ir sozinha, e voltar sozinha.
- Escreva o gate antes de executar. Se dá para rodar, melhor que julgar no olho.
- Liste o que você precisa decidir. E decida, antes de começar.
Depois entregue esse documento ao assistente em vez de entregar a tarefa solta. A diferença de resultado não vem de o modelo ficar mais inteligente, vem de ele parar de precisar adivinhar.
A especificação é o novo código-fonte
Quando a implementação fica barata, o artefato que importa deixa de ser o código e passa a ser o documento que gera o código. Código gerado a partir de uma especificação boa é descartável: dá para jogar fora e regenerar. Código gerado a partir de conversa solta não é, porque a intenção só existe dentro dele.
É essa a inversão que o Spec-Driven Development nomeia. Não é uma metodologia nova para escrever documento, é o reconhecimento de que o documento virou a parte difícil.
Se você ainda não fechou o problema antes de partir para a construção, comece por lá: veja o que é um PRD e as 11 seções que ele fecha. E para montar o ambiente que sustenta esse fluxo, o stack completo da eBuz tem as 31 ferramentas agrupadas por função, incluindo o que o Claude faz além de escrever texto.
