O paradoxo da especificação: quando SDD vira overengineering disfarçado de boa prática

Você abriu a IDE para entregar uma feature de duas horas.

Quatro horas depois, ainda está escrevendo a spec. Markdown indo, markdown voltando. Constitution, requirements, plan, tasks. O agente já gerou três versões do spec.md e nenhuma satisfaz a checklist da equipe. A feature segue não escrita.

Esse é o sintoma. SDD virou ortodoxia em 2026, mas pouca gente discute o custo. Aqui vamos ver de onde veio o método, onde ele entrega de verdade, onde virou cerimônia disfarçada de boa prática, e como aplicar spec proporcional ao risco sem virar refém da metodologia.

TL;DR

• O que é: análise crítica do uso de Spec-Driven Development em features pequenas e médias, e proposta de proporcionalidade.
• Stack/contexto: GitHub spec-kit, Claude Code, Cursor, Kiro, Tessl.
• Custo: tempo e contexto do humano (não dinheiro de API).
• Link útil: spec-kit no GitHub.

De onde veio o SDD (e por que virou ortodoxia)

A ideia é antiga: especificação antes de código. O que mudou em 2026 é que a especificação agora é executável, vira prompt para um agente, e o agente devolve implementação. O GitHub spec-kit formaliza esse fluxo em seis comandos:

/speckit.constitution   # princípios não-negociáveis do projeto
/speckit.specify        # o quê e por quê (sem decisão técnica)
/speckit.clarify        # perguntas para reduzir ambiguidade
/speckit.plan           # arquitetura, stack, contratos
/speckit.tasks          # quebra acionável com dependências
/speckit.implement      # finalmente, o agente codifica

A promessa: spec é fonte da verdade, código é artefato gerado. Se mudar de ideia, atualiza a spec, regenera o plano, deixa o agente refazer. Faz sentido. Especialmente quando o motivo de adoção bate na ferida certa: agente sem contexto alucina, agente com contexto estruturado entrega o que você pediu.

A Thoughtworks chamou isso de uma das práticas-chave de engenharia em 2025. Kiro, Tessl, BMAD, GSD, cc-sdd: todo mundo quer ter o framework. E o Marc Brooker tem razão quando diz que SDD não é waterfall reciclado: a spec é viva, versionada, iterativa.

O problema não é a metodologia. É o uso indiscriminado dela.

Os sintomas da spec inflada

François Zaninotto, da Marmelab, documentou o resultado de uma feature pequena rodada via SDD completo: 8 arquivos, 1.300 linhas de markdown. Tudo isso para gerar um código que ainda precisava ser revisado.

Martin Fowler comparou Kiro, spec-kit e Tessl testando os três em um bug pequeno e numa feature de 3 a 5 pontos. Conclusão dele:

"Using a sledgehammer to crack a nut."

O Kiro gerou 4 user stories com 16 acceptance criteria para corrigir um bug. O spec-kit produziu múltiplos arquivos verbosos para uma feature pequena, e Fowler admite: no mesmo tempo que levou para revisar tudo, teria implementado direto.

O sintoma é específico. Anota:

• Spec maior que o código. Se o markdown gerado tem 3x o tamanho do diff final, você não fez engenharia, fez paperwork.
• Você lê mais do que escreve. Quando a maior parte da sua hora é abrir arquivo, conferir, pedir ajuste, abrir outro, conferir de novo, você virou revisor de spec, não engenheiro.
• A spec gera retrabalho próprio. Você ajusta o spec.md, regenera o plan.md, regenera o tasks.md. Três artefatos para o mesmo "ah, mudei de ideia".
• Constitution para projeto de 2 semanas. Documento de princípios imutáveis para algo que ainda não tem usuário.

Se dois desses bateram, a metodologia está te usando.

O custo invisível

O custo de spec excessiva não aparece no relógio do agente. Aparece no humano.

Tempo de leitura supera tempo de execução. A Marmelab mediu 80% do tempo lendo markdown contra 20% efetivamente decidindo. Esse é o flip que dói: você adotou IA para acelerar, e desacelerou trocando "escrever código" por "ler descrição de código que ainda nem foi escrito".

Revisão dupla. A spec já contém pseudo-código e contratos. O código sai do agente. Você revisa os dois. Antes era um diff, agora são dois artefatos a manter sincronizados.

Falsa sensação de controle. A spec parece um contrato. Não é. O agente segue até onde quer. No exemplo da Marmelab, o agente marcou tarefas como completas sem escrever os testes correspondentes. Spec verde, código incompleto.

Manutenção exponencial. A Isoform descreveu bem: quando finanças pede "VAT europeu" uma semana depois, atualizar o código é mais rápido do que reescrever a spec. Resultado: spec e código divergem. Você passa a ter documentation debt disguised as engineering discipline.

A spec descreve "o quê", nunca o "porquê". Decisões de tradeoff, restrições de produção, insights da iteração: nada disso cabe num markdown gerado upfront. Edge case só aparece quando o sistema roda. Performance só dói depois do deploy.

Tem mais um custo, e esse é o pior: drift de modelo. A Thoughtworks lembrou que LLMs não são determinísticos. Mesma spec, dois agentes, dois códigos diferentes. Se a sua "fonte da verdade" gera artefatos diferentes a cada execução, ela não é fonte da verdade. É roteiro.

Quando spec ainda compensa (porque compensa)

Não é abandonar a metodologia. É proporcionalidade. A spec densa entrega valor quando:

• Sistema crítico. Auth, billing, migração de dados, fluxo financeiro, compliance. Erro custa caro, reverter é difícil. Aqui spec, ADR, evals, tudo.
• Equipe assíncrona ou múltiplos consumidores. A spec virou contrato real entre times. Um time gera evento, outro consome. Sem spec compartilhada, vira telefone-sem-fio.
• Feature grande de verdade. Cinco dias ou mais, vários acoplamentos, decisões arquiteturais que afetam o resto do código. Aqui o tempo de spec se paga em retrabalho evitado.
• Onboarding. Dev novo precisa entender o porquê das decisões. Spec viva é o melhor formato.
• Refatoração de domínio. Mudança que cruza módulos pede ADR + plano antes do diff.

O Brooker está certo nesses contextos: spec viva, versionada, iterativa. O agente acelera a spec, não substitui o pensamento.

O princípio: spec proporcional ao risco

A pergunta que substitui o ritual é uma só:

Se eu errar essa decisão, em quanto tempo eu reverto?

Resposta abaixo de 30 minutos? Vai. Diff é a sua spec.

Resposta entre 30 minutos e meio dia? Plano de uma página, contratos definidos, agente codifica.

Resposta acima de meio dia, ou envolve dado de cliente, dinheiro, ou contrato externo? Aí sim, spec completa, constitution, verificação por evals.

Em formato de checklist, antes de abrir o spec.md:

[ ] Mais de um time consome essa interface?
[ ] Erro custa dinheiro real (billing, fraude, financeiro)?
[ ] Decisão arquitetural que vai durar > 6 meses?
[ ] Dev novo precisa entender o porquê em 6 meses?
[ ] Feature > 5 dias de implementação?
[ ] Compliance / auditoria envolvida?

Zero marcado: spec é o título do PR + 3 bullets de contexto.
1-2 marcados: plano técnico de meia página no PR description.
3+ marcados: spec-kit completo se justifica. Constitution se faz sentido.

Esse é o filtro. Sem ele, você aplica o método pesado em todo lugar e a metodologia consome o tempo que deveria estar gerando produto.

Aplicando isso na prática com Claude Code

Três ajustes que mudam o jogo no dia a dia, sem instalar framework novo:

1. Promova AGENTS.md / CLAUDE.md em vez de Constitution global. Princípios curtos, vivos, no repositório. Lê em qualquer agente. Não exige ferramenta. Para ver como esse arquivo virou padrão de fato em 2026, vale ler a doc oficial do Claude Code.

2. Spec mora no PR description, não em pasta /specs/. Para feature pequena/média, o template de PR já tem o que importa: contexto, decisão, alternativas descartadas, como testar. Spec viva é spec que alguém atualiza. Markdown em pasta separada apodrece.

3. Use prompt de "spec mínima" para o agente. Em vez de rodar o pipeline completo do spec-kit:

Antes de codar, me devolva:

1. Em 3 bullets, o que essa mudança altera no comportamento observável.
2. Os contratos públicos afetados (assinaturas, eventos, schemas).
3. Um caso de teste que falharia hoje e passaria depois.

Espera meu OK antes de escrever código.

Isso é spec-driven sem ser spec-inflado. Captura intent, contrato e verificação. Cabe num scroll. Você revisa em 2 minutos.

Para feature crítica, aí sim, vai de spec-kit completo, com Constitution e tudo. Mas só ali.

Esse tipo de decisão, quando o método ajuda e quando atrapalha, é o que a gente trabalha ao vivo no Harness Engineering com Claude Code, construindo um app de verdade em dois dias (recebe link de produto, pesquisa alternativas em e-commerces, compara preço, devolve recomendação estruturada) com Claude Code, Laravel e NativePHP.

FAQ

SDD é só waterfall com nome novo?

Não, mas pode virar. O Marc Brooker explica bem: a diferença é que a spec é viva e iterativa, não congelada upfront. O risco é o praticante tratar como congelada, e aí, sim, vira waterfall com markdown.

E governança em equipe grande?

Aí faz sentido. Constitution, ADRs, contratos compartilhados: tudo isso ganha valor quando o número de pessoas afetadas pela decisão cresce. O erro é importar a mesma cerimônia para um squad de 3 pessoas com feature de 1 dia.

O agente erra mesmo com spec detalhada?

Sempre. A spec reduz drift, não elimina. A Thoughtworks lembrou que LLM não é determinístico, e a Marmelab mostrou agente marcando tarefa completa sem escrever os testes. Você ainda revisa código, sempre.

Vale spec-kit ou só AGENTS.md resolve?

Para a maioria das features do dia a dia, AGENTS.md + spec curta no PR description resolve. Spec-kit completo se justifica em projeto grande, time distribuído, ou domínio crítico. A pergunta não é qual ferramenta, é qual o tamanho do risco.

Conclusão

SDD não é o problema. SDD aplicado sem juízo é. O método que deveria reduzir desperdício passou a gerar desperdício próprio: markdown que ninguém lê, plano que ninguém segue, constitution que ninguém atualiza.

A regra é simples e cabe numa frase: o tamanho da spec deve seguir o tamanho do risco. Bug pequeno, diff é a spec. Feature crítica, vai de tudo. No meio, plano de meia página no PR. O resto é cerimônia.

A próxima fase do dev sênior em 2026 não é dominar mais um framework de spec. É calibrar o método ao problema, e isso só vem de prática em produto real.