Don't Code, Specify: por que devs sêniores estão tendo resultados piores com IA

A metodologia que usei para construir uma fintech cripto (13 apps) em 70 dias, sozinho, com agentes de IA.

Escrevo código de produção há mais de 25 anos. Quando as ferramentas de IA para código chegaram, fiz o que todo dev experiente faz: mergulhei, digitei um prompt e vi o Claude gerar 500 linhas de código em 30 segundos.

Foi lindo. Foi rápido. E estava completamente errado.

Não errado de sintaxe. O código compilava. Errado no que importa: resolvia um problema que eu não tinha definido direito, com premissas que eu não tinha feito, numa arquitetura que eu não queria.

Passei meses nesse ciclo. Prompt, gera, joga fora, prompt de novo. Até que caiu a ficha: o problema não era a IA. O problema era eu.

Eu estava tratando um engenheiro de nível mundial como um dev júnior. “Cria um sistema de tarefas.” “Adiciona autenticação.” “Agora deixa em tempo real.” Cada prompt era um comando sem contexto, jogado numa ferramenta sem nenhuma memória das minhas decisões anteriores.

Foi aí que adotei Spec-Driven Development (SDD). Com ele, construí um monorepo de 13 apps, com 3 APIs, 3 bancos de dados e Kubernetes em produção. Sozinho. (Termo novo para você? Comece pelo que é Spec-Driven Development, o guia completo.)

Rápido e errado continua errado

Contrate o pedreiro mais rápido do mundo. Ele levanta parede em minutos, instala o encanamento em segundos, termina o telhado antes do almoço.

Esqueça de entregar a planta para ele.

Você ganha um prédio de pé: banheiro onde devia ser a cozinha, porta que abre para a parede, escada que não leva a lugar nenhum.

Claude Code, Cursor, Copilot. Eles são esse pedreiro. Geram código numa velocidade que era ficção científica cinco anos atrás. Mas velocidade sem direção é só um jeito mais rápido de chegar ao lugar errado.

O custo real aparece na conta:

✗

Sem specs

1. 01prompt → gera → percebe que faltou algo
2. 02novo prompt → quebra algo → corrige → novo prompt
3. 03repete até funcionar mais ou menos
4. 048 a 12 horas para uma única feature

✓

Com specs

1. 012 horas de planejamento
2. 02gera a partir da spec
3. 03pequenos ajustes
4. 043 horas, pronto

Por que devs experientes resistem

Se você tem 10, 15, 20 anos de experiência, provavelmente está pensando: “Eu já sei o que preciso construir. Spec formal é burocracia.”

Eu também pensava assim. Durante anos, as boas práticas empurraram agilidade, iteração rápida, “software funcionando mais que documentação abrangente”.

Só que você não programa mais sozinho. O seu modelo mental não passa para o agente.

Quando você escreve código, seu cérebro segura o sistema inteiro. Você sabe que aquela função obscura em utils.ts é crítica porque lembra da vez em que ela salvou o projeto às 2 da manhã. O Claude não tem essa memória. Toda sessão começa do zero.

Os quatro pilares do SDD

O SDD se apoia em quatro pilares, cada um com um gate de aprovação humana antes de a próxima fase começar:

Os quatro pilares

1. 01Requisitos (O QUÊ)

   O que o sistema precisa fazer. Linguagem de negócio, comportamentos observáveis, independente de tecnologia.

2. 02Design (COMO)

   Como funciona. Decisões de arquitetura, escolhas de tecnologia com justificativa, modelos de dados, contratos de API.

3. 03Tarefas (QUANTO)

   Quebrar em unidades implementáveis. Cada tarefa: 2 a 4 horas, testável de forma independente, dependências claras.

4. 04Implementação (EXECUÇÃO)

   O código segue a spec. Verificação contra os critérios de aceite. Registro das decisões.

Quanto mais cedo você pega um erro, mais barato é corrigir. Os gates garantem que os erros sejam pegos antes de se propagarem.

A anatomia de uma boa spec

O princípio da criança esperta

Explique seu sistema para uma menina de 12 anos muito inteligente. Ela é afiada, faz boas perguntas e lida com conceitos complexos, mas não tem o seu contexto implícito.

“Faz aquele negócio com as tarefas.” Ela se perde.

“Quando alguém cria uma tarefa, salva o título, confere se a pessoa tem permissão naquele workspace e notifica todo mundo que está olhando a lista.” Agora ela consegue trabalhar com você.

Esse é o nível de clareza que suas specs precisam ter.

Seja específico, não genérico

Ruim: “O sistema deve ser rápido.”

Bom: “O endpoint GET /api/v1/tasks deve responder em menos de 500ms no p95 para listas de até 1.000 tarefas.”

Defina o escopo negativo

O que você explicitamente não vai construir importa tanto quanto o que vai:

• Este MVP não suporta tarefas recorrentes
• Sem integração com calendário (v2)
• Sem controle de horas
• Sem dependências entre tarefas (só subtarefas)

Isso impede a IA de, na boa vontade, adicionar features que você não pediu. Acontece o tempo todo.

Use exemplos concretos

Em vez de “validar o título da tarefa”, especifique o comportamento exato:

• "" → Erro: “Title is required”
• "A" → Erro: “Minimum 2 characters”
• "Fix bug #123" → Sucesso
• "A" × 501 → Erro: “Maximum 500 characters”
• " " → Erro: “Title is required”

Cada pergunta que você responde na spec é uma premissa errada a menos no código.

O que SDD NÃO é

Não é Waterfall. Specs em SDD são documentos vivos. Elas evoluem, mas de forma controlada. Você pode voltar e mudar requisitos, mas a mudança se propaga de forma consciente pelo design e pelas tarefas.

Não é exagero para tudo. Use SDD quando o projeto dura mais que alguns dias, envolve várias features complexas ou atravessa várias sessões de desenvolvimento. Para um script de uma hora, é só mandar o prompt.

Como as abordagens se comparam

Como as abordagens se comparam. Winner: Spec-Driven with a weighted score of 48. Scale 1-5 (5 = best).

Critério (peso)	Prompt puro	Waterfall	Spec-Driven
Velocidade até o primeiro resultado (2)	5	2	4
Corretude (3)	2	4	5
Custo de retrabalho (menor é melhor, nota invertida) (3)	1	3	5
Escala com o tamanho do time (2)	1	3	5
Pontuação ponderada	21	31	48

Scale 1-5 (5 = best). Highlighted column: winner by weighted score.

As provas

Construí uma plataforma de fintech cripto completa com SDD: gateway de pagamento, motor de exchange OTC, servidor de autenticação OAuth 2.1, arquitetura multi-tenant, deploy em Kubernetes. 13 apps num monorepo, 8 pacotes compartilhados. Sozinho.

As specs foram o multiplicador. Não a IA. As specs.

Sem elas, o Claude Code é um pedreiro rápido sem planta. Com elas, é um engenheiro sênior que lembra de cada decisão que você tomou.

Escolha uma feature. Escreva três arquivos.

Comece por uma feature. Escreva estes três arquivos:

1. requirements.md: O que ela faz? Para quem? Quais são os critérios de aceite?
2. design.md: Como funciona? Modelo de dados, endpoints da API, decisões de arquitetura.
3. tasks.md: Quebre em blocos implementáveis de 2 a 4 horas, com dependências claras.

Entregue ao seu agente. O sistema é só isso.

Continue lendo:

• O que é Spec-Driven Development?: o método completo, os quatro pilares e quando pular
• O estudo de caso: 13 apps, 70 dias e as provas
• Como escrever uma spec: templates e o formato EARS
• SDD vs. vibe coding: o antídoto disciplinado para programar no feeling

---

Sou praticante de SDD, não o criador. Minha autoridade vem de aplicar em escala: 13 apps, 70 dias, sozinho, em produção. Já treinei 30.000+ desenvolvedores em engenharia de software e 400+ profissionais em fluxos de trabalho com IA.

A primeira spec toma tempo. A segunda, metade. Na terceira, já é memória muscular.

O código se escreve sozinho. A spec, não.

Felipe