5 sinais de que sua especificação virou burocracia (e como voltar à base bem feita)

Em 2026 todo mundo escreve spec antes do código. Spec Kit, Kiro, Claude Code com Skills, Tessl. O pêndulo balançou. Time que ano passado tacava prompt no Cursor e rezava agora abre cada feature com markdown de duas páginas, três reuniões e quatro reviewers.

A intenção é boa. Spec-driven funciona. Mas tem um problema que nenhum vendor de SDD vai te contar: a maioria das specs que vejo em produção não é fonte de verdade. É ritual. Documento que existe para alguém aprovar, não para um agente executar.

A diferença é grande. Spec viva é harness, estrutura de contexto, critério e teste que prende o agente no escopo certo. Spec morta é overhead. Custa tempo de quem escreve, tempo de quem revisa, tempo de quem lê (quase ninguém), e ainda atrapalha o agente, que precisa filtrar ruído pra achar o que importa.

Cinco sintomas que aparecem antes de a coisa virar uma fábrica de SRS de 2003 reembalada com Markdown. Para cada um, o ajuste prático.

TL;DR

• O que é: cinco sinais de que sua spec virou ritual e perdeu utilidade técnica.
• Quem deveria ler: dev, tech lead e PM usando spec-driven development com agentes (Claude Code, Spec Kit, Kiro, Cursor com regras).
• Custo do ajuste: zero. É só remover ritual.
• Leitura paralela: Spec Kit no GitHub e Spec-Driven Development with Coding Agents (DeepLearning.AI).

Sinal 1: a spec é maior que o código que ela descreve

Feature de 80 linhas de código. Spec de 800.

Quando isso acontece, a spec deixou de descrever o sistema e virou o sistema. O time gasta mais energia mantendo o markdown do que mantendo o software. E pior: o ThoughtWorks colocou spec-driven development no anel "Assess" do Tech Radar exatamente alertando para o "viés para especificação pesada antecipada e releases big-bang". O nome velho disso é waterfall.

Ajuste: uma spec de feature normal precisa caber confortável na janela de contexto do agente sem comer mais de uns 2 a 3 mil tokens. Se passa disso, ou a feature foi mal fatiada, ou a spec está descrevendo coisa que o código já documenta sozinho. Apagar parágrafo de spec é tão saudável quanto deletar dead code.

Sinal 2: três reuniões para aprovar uma spec de um dia de código

Apareceu o comitê de spec. Quatro stakeholders no review. Cada um pede uma cláusula defensiva ("e se o usuário não tiver permissão?", "considera o caso de timezone?", "e mobile?"). A spec sai duas vezes maior. Metade dos casos cobertos nunca acontecem em produção.

Esse é o PMI dos anos 2000 voltando vestido de Notion. O custo de aprovação ultrapassa o custo de implementação, e a spec fica defensiva ao invés de prescritiva.

Ajuste: spec tem um autor e um reviewer técnico. Só. Os outros leem o resultado, não o documento. Se um stakeholder quer garantia, ele pede um teste de aceitação, não um parágrafo. Teste é executável; parágrafo é torcida.

Sinal 3: ninguém lê a spec antes de implementar

Pergunta ao dev no fim do sprint: "você releu a spec antes de mexer nessa parte?". Silêncio.

Spec que vive no Confluence e não é carregada literalmente no contexto do agente é spec morta. Ela serve para auditoria, não para decisão. Voltamos ao FRS impresso e assinado de 2003, o documento existe para o caso de alguém perguntar, não para guiar trabalho.

Ajuste: a spec precisa estar no mesmo lugar onde o trabalho acontece. Pasta specs/ no repositório. Lida no CLAUDE.md, no AGENTS.md, no system prompt do skill. Versionada junto com o código. Se o agente não tem acesso direto à spec quando vai implementar, ela não está sendo usada, está sendo cumprida.

repo/
  app/
  specs/
    01-busca-produtos.md      ← critério, entrada, saída, exemplos
    02-recomendacao.md
  CLAUDE.md                   ← aponta o agente para specs/ na ordem certa

Spec no repositório vira parte do contexto. Spec no Confluence vira PDF assinado.

Sinal 4: o agente ignora metade da spec na implementação

"Deve ser robusto." "Considerar performance." "Pensar em escalabilidade." "Tratar edge cases."

O agente lê isso e descarta. Não porque é preguiçoso. Porque não tem critério verificável. Esses requisitos são placeholder de pensamento, não pensamento. Eles existem para o autor sentir que cobriu o caso, não para alguém executar.

A literatura sobre anti-patterns em SDD chama parte disso de over-prompting: salvar coleção de adjetivos como se fosse spec, quando spec é contrato comportamental — entrada, saída, invariante.

Ajuste: cada requisito vira um teste, uma métrica, ou um critério verificável. "Deve ser rápido" não é requisito; "p95 abaixo de 200 ms em 1k req/s no endpoint X" é. Se você não consegue escrever o teste que prova o requisito, o requisito não existe. Corta da spec.

<!-- ruim -->
- O endpoint deve ser performático e robusto.

<!-- bom -->
- p95 < 200ms em 1.000 req/s (medido com k6, payload de 1KB).
- Falha de upstream retorna 503 com retry-after; nunca propaga 5xx genérico.
- Idempotência por chave `request_id` (mesma chave em 24h = mesma resposta).

Mesmo assunto, dois universos diferentes. Um é decorativo. O outro é executável.

Sinal 5: mudou a spec, o retrabalho dobrou

Toda alteração na spec dispara cascata. Revisão. Aprovação. Reescrita do plano. Reescrita dos testes. O time começa a evitar mudar a spec, e a spec começa a divergir do código real.

Esse é o sinal mais grave. Significa que a spec virou contrato com fornecedor e não ferramenta de engenharia. Cada mudança é negociação. O escopo congela porque mexer na documentação dói mais do que mexer no software.

Ajuste: trata spec como código. Versiona. Refatora. Apaga requisito morto. Mudança na spec é commit, não reunião. Se uma mudança de spec exige mais cerimônia que uma mudança de código, o pêndulo passou do ponto e está caindo do outro lado da escada.

FAQ rápido

Quanto deve ter uma spec boa? Cabe na janela de contexto do agente sem dominar. Para feature normal, 1 a 2 páginas markdown (1.500 a 3.000 tokens). Se está maior, fatia a feature ou apaga parágrafo decorativo.

Spec-driven não é só waterfall com markdown? Pode virar, é o ponto desse post. A diferença é que a spec executável (com critério verificável) alimenta agente, alimenta teste e é refatorada como código. Spec de aprovação é waterfall. Spec de harness é engenharia.

Onde a spec deve viver? No mesmo repositório do código, em specs/. Versionada, lida pelo agente, revisada como diff. Confluence é arquivo morto.

E quando o stakeholder pede spec longa "para garantir"? Pede teste de aceitação no lugar. Garantia executável é mais forte que garantia textual, e custa metade da reunião.

Voltando à base bem feita

Spec-driven funciona quando a spec é harness, a estrutura mínima de contexto, critério e teste que segura o agente no escopo certo. Para de funcionar no momento em que vira ritual de aprovação ou produto paralelo a manter.

A pergunta que separa as duas coisas é simples. Se você apagasse essa spec amanhã, o que quebraria? Se a resposta é "o agente perde direção e o time perde alinhamento", está viva. Se a resposta é "ninguém ia perceber", você está fazendo waterfall com markdown.

Esse é exatamente o tipo de prática que vamos exercitar ao vivo no Harness Engineering com Claude Code, nos dias 16 e 17 de maio: dois dias construindo do zero um app real com Claude Code, Laravel e NativePHP, recebendo link de produto, pesquisando alternativas em e-commerces e devolvendo recomendação estruturada, com foco em harness aplicado em produto.

Se a sua próxima spec não cabe em duas páginas, não tem critério verificável, ou ninguém vai abrir antes de implementar, é hora de cortar. Spec é ferramenta. Volta a ser uma.