Estudo de caso de Spec-Driven Development: 13 apps em 70 dias, sozinho, com IA

A maioria dos artigos sobre desenvolvimento assistido por IA descreve uma ferramenta de fornecedor, um experimento de workshop ou um protótipo solo feito numa tarde. Este não é nenhum desses. É alguém que pratica descrevendo um build real de produção: um sistema, um dev, setenta dias, dinheiro de verdade, compliance de verdade. Os números são públicos. Os limites são honestos.

Se você quer o método em si, comece por o que é Spec-Driven Development. Isto aqui é a prova de conceito por trás dele: um sistema real, setenta dias, o método aplicado numa escala em que os modos de falha são caros e difíceis de reverter.

Uma fintech cripto, construída sozinho com SDD

13

apps em produçãomonorepo Turborepo

3

APIs, 3 bancosauth, pagamentos, exchange

8

pacotes compartilhadosauth, ui, i18n, logger...

70

diassozinho, dinheiro de verdade

~1.650

testes automatizadosVitest e Playwright

138K

linhas de TypeScript39 migrations

A aposta

O escopo não era um protótipo. Construir uma plataforma completa de pagamentos cripto: um gateway de pagamento PIX para o mercado brasileiro, um motor de exchange OTC e liquidação on-chain na Liquid Network do Bitcoin. De ponta a ponta. Nível de produção. Dinheiro de verdade, compliance de verdade, prazo de verdade. Sozinho. Setenta dias.

Não é um projeto que se improvisa numa janela de chat. Três bancos PostgreSQL isolados. Três APIs Fastify. Nove frontends Next.js. Uma biblioteca de componentes compartilhada. Uma camada de autenticação compartilhada. Kubernetes por trás de tudo, num monorepo Turborepo. Some a superfície regulatória: o PIX passa pelo Banco Central, com hooks de compliance próprios e um endpoint de integração bancária direta via TLS mútuo. Some um motor de exchange OTC que precisa de precificação determinística, spreads assimétricos e uma cadeia de fallback entre cinco fontes de mercado. Some um motor de liquidação que precisa lidar com transações travadas, reembolsos por desvio e um teto de liquidação automática que transborda para aprovação manual quando os saldos passam de um limite. Cada domínio tem seus próprios modos de falha. E eles se somam. Uma premissa errada na camada de precificação aparece depois, na camada de liquidação, com dinheiro de verdade em trânsito.

As principais objeções ao spec-driven development em 2026 vieram de dois tipos de experimento: protótipos de workshop, em que times testam o método em projetos de brinquedo durante uma tarde, e builds solo pequenos, em que um engenheiro entrega algo em poucas horas sem SDD e conclui que era overhead desnecessário. Nenhum dos dois é o teste relevante. Um projeto solo de 10 horas, sem pressão de compliance, sem saldos reais e sem prazo externo, não precisa de um corpus de 28 arquivos de spec. Um motor de exchange OTC com modelo de precificação em duas fases, cinco fontes de mercado e integração direta com o BACEN precisa, e muito. O método é proporcional ao que você está protegendo.

A abordagem ingênua de desenvolvimento com IA nessa escala é abrir uma janela de chat e sair descrevendo features. Já fiz isso. É o pedreiro rápido sem planta: paredes em minutos, escada dando na parede. Na escala de uma fintech multi-tenant com hooks de compliance, o prompt-e-reza não te atrasa aos poucos. Ele constrói algo que parece completo e passa numa revisão rasa, depois quebra quando chega um edge case real. O código compila. Os testes passam. A premissa que ninguém escreveu volta em produção com o saldo de um cliente pendurado nela.

Então eu não mandei prompt. Eu especifiquei.

Quem faz o modelo manda planejar primeiro

Não é mania pessoal nem opinião do contra. A própria orientação da Anthropic para o Claude Code descreve um ciclo de quatro passos: explorar, planejar, implementar, fazer commit. Existe um plan mode dedicado no produto cuja única função é impedir o agente de escrever código enquanto pensa. O raciocínio deles é direto: “deixar o Claude pular direto para o código pode produzir código que resolve o problema errado”.

É a empresa que treinou o modelo dizendo o que a maioria dos devs pula. Eles publicam um template de prompt para você se entrevistar até chegar a uma especificação antes de existir qualquer código, e depois abrir uma sessão nova para executá-la. Três frases, vindas de quem construiu a ferramenta.

Um ensaio randomizado de 2025 do METR mostrou que devs experientes trabalhando com IA em codebases reais ficaram 19% mais lentos do que sem ela, apesar de esperarem ficar 24% mais rápidos. Erraram com confiança nas duas direções: sobre o resultado e sobre a própria percepção dele depois. O modo de falha não é o modelo. É capacidade sem direção. Quanto mais capaz o modelo, mais longe uma instrução vaga o leva na direção errada. Capacidade amplifica a direção. Não a fornece.

Em 13 aplicações de produção, rodei em escala o que a Anthropic descreve. O mecanismo foi um corpus permanente de specs: 28 specs em markdown cobrindo 12 domínios, mais 8 slash commands customizados, morando no repositório e carregados como contexto do agente no início de cada sessão. Nada de prompt improvisado. A memória do projeto, em disco, versionada no git.

Spec primeiro, prompt nunca

Cada capability começou como uma especificação escrita: requisitos, design, tarefas. Não uma mensagem de chat. Os agentes executavam contra a spec. Eu revisava contra os critérios de aceite e publicava. Quando o output saía errado, eu corrigia a spec, não o prompt. Cada linha de código gerado remetia a uma decisão que eu tinha tomado e conseguia apontar.

O corpus permanente de specs: a memória do agente, em disco

• .claude/
  • auth/domínio// papéis, scopes, permissões de rota
  • exchange/domínio// pricing.md: o contrato de VWAP e spread
  • database/domínio// entidades, migrations, design de schema
  • testing/domínio// convenções, db, ui
  • ui/// design tokens, componentes
  • codebase/// convenções, server actions
  • commands/8 comandos// /new-route, /migrate, /verify...
  • skills/1 skill// convenções da plataforma

Vinte e oito specs em markdown cobrindo doze domínios, mais oito slash commands customizados que transformaram os passos repetíveis de geração em contratos que o agente tinha de seguir. Os slash commands são a parte que quase todo mundo deixa passar. Não são atalhos de teclado. Cada um codifica um workflow completo: geração de rota, migration de banco, scaffolding de testes, verificação de deploy. O agente executa todos do mesmo jeito, em toda sessão. Sem drift. Sem reinvenção. Os slash commands são a unidade repetível de trabalho. As specs são a memória persistente por trás deles.

O domínio de auth, por exemplo, não é uma nota solta dizendo “use JWT”. É uma spec que cobre cinco papéis, dezenove scopes, dezoito permissões granulares, a regra de que toda rota declara o scope exigido no momento do registro e o fluxo machine-to-machine com escopo por linha para client credentials. Quando o agente gera uma rota nova, ele lê essa spec primeiro. A declaração de scope não é algo que o dev precisa lembrar de adicionar. É algo que a spec exige, e o agente confere.

Um dev sozinho não guarda uma fintech de 13 apps na cabeça. A spec guarda. O dev guarda a spec.

O ciclo de entrega

O ciclo de entrega, repetido a cada capability

Entrada

Uma capability para entregar (ex.: o motor de liquidação)

↓

1. 01Specify

   Requisitos, design e tarefas escritos antes de qualquer linha de código. A spec é o contrato, não enfeite. Aprovação humana obrigatória antes de avançar.

   ↓
2. 02Generate

   O agente implementa contra a spec e escreve os testes junto com o código. Sem prompt. A spec é a instrução.

   ↓
3. 03Verify

   Revisão contra os critérios de aceite e o gate do pnpm verify: Prettier, ESLint com zero warnings, tsc strict, testes num banco real.

   ↓
4. 04Corrigir a spec

   Output errado significa spec errada ou incompleta. Corrija o documento, regenere. Nunca corrija o código deixando a spec para trás.

↓

Saída

Mergeado, testado, rastreável até uma decisão

O quarto passo é onde mora a disciplina. Quando algo saía errado, o instinto é corrigir o código e seguir em frente. Esse instinto é veneno em escala. Corrija o código, deixe a spec intocada, e na próxima vez que aquele módulo for regenerado ou estendido o agente reconstrói a partir da spec e reintroduz o mesmo erro. A spec é a fonte da verdade. O código é o que sai dela. Toda correção entra primeiro no documento.

O ciclo se repetiu para cada capability nas treze aplicações: o motor de precificação, o motor de liquidação, a camada de idempotência, o servidor de auth, a fila de webhooks, o poller de depósitos on-chain, os manifests do Kubernetes, a biblioteca de UI compartilhada. Mesmo ciclo. Mesma disciplina. Mesma regra para correções. A repetição é o ponto. Consistência nessa escala não é exercício de gestão. É o que impede uma pessoa sozinha de perder o controle de um sistema grande demais para caber na memória.

O que as specs pegaram

O motor de precificação

O exemplo mais claro é o motor de precificação da exchange OTC. Antes de existir qualquer código, o comportamento de precificação morava num único arquivo de spec. O modelo em duas fases: uma taxa de peg fixada a um índice de referência, ativa até a janela de VWAP entrar em vigor, o que exige pelo menos cinco trades confirmados numa janela móvel de 24 horas. A cadeia de fallback entre cinco fontes de mercado, agregadas por mediana com filtro de outliers. Spreads assimétricos por par, aplicados depois da resolução do VWAP. E a regra de precisão da qual tudo dependia: toda a matemática de dinheiro em inteiros de 8 casas decimais, precisão de satoshi, nunca ponto flutuante.

Essa última regra não era um comentário nem uma convenção de código. Era um requisito, escrito na spec antes da primeira linha de implementação, expresso como condição de falha de teste. Aritmética de ponto flutuante em software financeiro não falha de forma barulhenta. Ela deriva. Pequenos erros de arredondamento se acumulam em várias operações, vários trades, vários clientes. Quando a diferença aparece num ledger, já é problema de suporte, não falha de teste. A spec fez disso uma falha de teste no primeiro dia.

Aqui está um trecho representativo de como era essa spec:

## Precision rule (MUST)
All money arithmetic uses 8-decimal integers (satoshi precision).
No float or double anywhere in the pricing path.
A float in any response field is a test failure, not a lint warning.

## Two-phase model
Phase 1 (peg): price is fixed to the reference index.
Phase 2 (VWAP): rolling 24h VWAP, active once >= 5 confirmed trades exist.
The engine falls back from Phase 2 to Phase 1 when VWAP is unavailable.
Fallback is logged and triggers an ops alert.

## Fallback chain (market sources, in order)
1. Internal VWAP from confirmed trades (primary)
2. Cross-rate from 5 external sources, median-aggregated, outliers removed
3. Last known good price, flagged stale, ops notified

## Acceptance criteria
- Request with < 5 confirmed trades MUST use the peg price, not VWAP.
- When source 1 is unavailable, fallback to source 2 within 200ms.
- All returned amounts MUST be integers. A float anywhere is a test failure.
- Spread changes take effect on the next quote, never retroactively.

## Out of scope (v1)
- Dynamic spread adjustment based on volatility.
- Per-user spread overrides.

O código de produção espelha essa spec quase linha por linha. A cadeia de fallback está implementada na mesma ordem. A regra de precisão é garantida tanto pelo sistema de tipos quanto por um teste dedicado que falha se qualquer campo da resposta de precificação tiver um float. O limite de ativação do VWAP é uma constante nomeada que bate com a spec. A lista de fora de escopo impediu o agente de adicionar features que ninguém pediu, em duas ocasiões diferentes. O documento é o motivo pelo qual um dev sozinho podia confiar saldos reais a um motor de exchange: as decisões difíceis foram tomadas, revisadas e congeladas antes de o agente tocar na aritmética.

Idempotência de pagamentos

O mesmo padrão vale no gateway de pagamento. Uma spec congelou a regra de idempotência antes de uma linha sequer do endpoint de cobrança ser escrita:

## Idempotency (MUST)
WHEN a merchant POSTs a charge with a valid Idempotency-Key,
THE SYSTEM SHALL create at most one charge for that key.

WHEN the same Idempotency-Key is replayed within 24h,
THE SYSTEM SHALL return the original charge and create no new row.

## Schema
charges(id, merchant_id, amount_cents, currency, status,
        idempotency_key, created_at)
UNIQUE(merchant_id, idempotency_key)
-- Enforced at the database level. Application logic alone is not sufficient.
-- A retry that hits a constraint violation returns the original charge.

A constraint UNIQUE coloca a regra no banco: fora do código da aplicação, fora de um cache, fora de uma checagem de middleware que um refactor futuro pode remover. Sem spec, essa constraint mora na sua cabeça. E cai na próxima regeneração. O agente reconstrói a partir da spec, a spec não tem índice único, a nova versão do módulo não tem constraint. Um retry do cliente, uma cobrança em dobro. A constraint na spec é a constraint na migration, que é a constraint no schema em produção. Essa corrente é o que garante correção entre sessões.

✗

Se eu tivesse ido no prompt

1. 01"crie um motor de precificação para a exchange" te dá aritmética de ponto flutuante e erro de arredondamento acumulando em saldos reais
2. 02scope creep silencioso: o agente adiciona coisas que acha úteis, mas ninguém pediu
3. 03edge cases como liquidações travadas e reembolsos por desvio aparecem em produção
4. 04a constraint de idempotência mora na sua cabeça, cai na regeneração, cliente cobrado em dobro
5. 05nenhum registro de por que cada decisão foi tomada

✓

Porque eu especifiquei

1. 01matemática com inteiros de 8 casas decimais declarada na spec antes de qualquer linha gerada, garantida por uma falha de teste para qualquer float
2. 02o escopo negativo impediu o agente de construir o que ninguém pediu
3. 03edge cases escritos como critérios de aceite, pegos na revisão e não em produção
4. 04UNIQUE(merchant_id, idempotency_key) no schema, garantida pelo banco
5. 05toda decisão rastreável no git, para sempre

Na plataforma inteira, essa disciplina produziu o que é preciso para dinheiro circular com segurança. Um gateway de pagamento com quatro provedores PIX atrás de um factory pattern, incluindo uma integração bancária direta BACEN Cob v2 via TLS mútuo. Webhooks assinados com HMAC-SHA256 e fila de retry com backoff exponencial de seis tentativas. Um servidor de auth OAuth 2.1 e OIDC com cinco papéis, dezenove scopes, 2FA via TOTP e client credentials machine-to-machine com escopo por linha. Um motor de liquidação com confirmação em dois blocos, reembolso automático por tolerância para desvios acima de 10%, teto de US$ 10K para liquidação automática que transborda para aprovação manual, commit atômico em três fases e recuperação de liquidações travadas no meio do caminho. A página do projeto tem o checklist completo de produção.

Cada uma dessas features começou numa spec. Cada spec tinha seu modo de falha descrito antes de existir uma linha de implementação. Cada modo de falha foi pego no gate de revisão, não em produção.

O resultado em números

O que a execução guiada por spec produziu

28

arquivos de spec12 domínios, 8 slash commands

~1.650

testes automatizadosVitest e Playwright

138K

linhas de TypeScripttudo gerado a partir de specs

39

migrations de bancotodas rastreáveis

O que isto prova, e o que não prova

Não se generaliza para qualquer dev. Tenho 25 anos de experiência, incluindo trabalhos anteriores em fintech, aeroespacial e integração corporativa. O SDD escalou um modelo mental maduro. As specs que escrevi eram boas porque eu já sabia o que colocar nelas: quais edge cases importam em fluxos de pagamento, onde matemática de ponto flutuante dá dor de cabeça, como estruturar uma cadeia de fallback. Não há nenhuma evidência aqui de que o SDD salve quem ainda está construindo esse modelo. O método externaliza expertise. Não a fabrica.

A velocidade foi medida; a qualidade não foi auditada. “13 apps em 70 dias” não diz nada sobre densidade de defeitos no longo prazo nem sobre manutenibilidade. O gate de CI era rígido e os testes eram reais: Prettier, ESLint com zero warnings, tsc strict, cerca de 1.650 testes Vitest e Playwright contra um PostgreSQL real. Mas não faço nenhuma afirmação sobre o custo desse código em cinco anos. Testes verdes e CI apertado já colocaram sistemas ruins em produção antes.

Um prazo externo fez diferença real. Já vi o SDD entregar sob prazo de cliente e já vi projetos pessoais com o mesmo método empacarem indefinidamente. A spec amplifica a execução. Não substitui responsabilidade, urgência nem a pressão de uma data de entrega real.

Produção não é negócio. Dinheiro de verdade passando por uma infraestrutura com hardening não é o mesmo que uma empresa sustentável com clientes, margem e fila de suporte. Este caso prova um método de engenharia, não um mercado.

Um único ponto de dado, sem grupo de controle. A resposta certa a este estudo de caso não é “SDD sempre funciona nessa escala”. É “SDD comprovadamente funcionou nessa escala, uma vez, para este operador”. Se você aplicar o método e ele falhar, a falha também é dado. Um caso com resultado favorável não é o mesmo que uma metodologia com amplo respaldo empírico. Afirmo que o mecanismo é sólido, não que o resultado é garantido. O mecanismo é este: um agente de IA não tem memória entre sessões, e a spec é a memória externa que você dá a ele. É um argumento estrutural, não empírico. O estudo de caso mostra que funcionou. Não prova que sempre vai funcionar.

Nada disso enfraquece o argumento central. A especificação foi o multiplicador, não a IA. Sem as specs, o agente é um pedreiro rápido sem planta. Com elas, é um engenheiro sênior que lembra perfeitamente de cada decisão que você tomou. Isso é algo que uma pessoa consegue dirigir na escala de uma fintech.

Leve o método, não só a história

A história é um ponto de dado. O método é portátil.

• Aprenda o método: O que é Spec-Driven Development?
• Escreva sua primeira spec: Como escrever uma spec a partir da qual uma IA consiga construir
• Faça no seu editor: Spec-Driven Development com Claude Code
• Veja o projeto: A fintech cripto em produção

O código se escreveu sozinho. As specs, não. Foi nelas que os setenta dias foram parar, e é por isso que eles bastaram.