Qual o nível certo de detalhe em uma spec (e quando especificar demais atrapalha)?

Já apareceu por aí uma spec de cerca de 1.300 linhas de Markdown pra uma mudança de uma linha de código, e isso não é piada de internet: é caso documentado 😅

O Spec-Driven Development nasceu pra resolver um problema real, aquele em que a IA chuta o stack, chuta as features, chuta o design e te entrega um projeto que não tem nada a ver com o que você pediu

Só que tem um extremo oposto pouco discutido: a spec detalhada DEMAIS

Ela engessa a implementação, dobra o trabalho de revisão e custa mais tempo do que economiza

Bora ver onde cortar?

O que vai na spec e o que fica com quem codifica

A régua mais simples que existe pro nível de detalhe da spec é essa aqui: separar decisão de produto de decisão de implementação

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Essa divisão não é invenção minha, ela está no desenho da ferramenta mais conhecida do método

O Spec Kit é um toolkit mantido pela própria GitHub, descrito como "Toolkit to help you get started with Spec-Driven Development"

O fluxo central dele é Spec → Plan → Tasks → Implement, e cada fase cospe um artefato Markdown que alimenta a próxima

E aqui vem a parte que interessa: o comando de especificação diz, com todas as letras, pra focar no "what and why, the user-facing behavior and goals, not the tech stack, which belongs in /speckit.plan"

Já o comando de plano é descrito como "this is where implementation detail belongs"

Ou seja, o detalhe técnico não é proibido, ele só tem endereço

O prompt padrão de especificação é ainda mais direto: "Focus on user goals, scenarios, and acceptance criteria. No implementation details."

E se eu já misturei tudo em um documento só?

Quebra em dois

O blog de engenharia da Allegro recomenda exatamente isso: um documento com os requisitos de produto e funcionais (o quê, sem dependência técnica nem detalhe de implementação) e outro com os requisitos técnicos e não funcionais (o como)

É a mesma ideia da separação specify e plan, só que sem ferramenta nenhuma no meio

Se você conhece a diferença entre um documento de requisitos e um documento de arquitetura, é isso, com outro nome e com a IA lendo os dois

Sinais de que a sua spec passou do ponto

O sintoma número um é constrangedor de tão óbvio: a spec ficou maior que a mudança

François Zaninotto, da Marmelab, documentou um caso em que uma feature de exibir a data atual gerou cerca de 1.300 linhas de especificação em Markdown usando Spec Kit

A descrição dele foi certeira: "a one-line fix wrapped in a six-phase ceremony and 1,300 lines of Markdown"

O artigo saiu com o título "Spec-Driven Development: The Waterfall Strikes Back" e o argumento é esse mesmo, o método ressuscita a documentação pesada antes do código, num eco da era Waterfall

Os outros sintomas listados por ele são fáceis de reconhecer no seu próprio arquivo:

• repetição: a mesma regra reescrita em três seções diferentes
• casos de borda imaginários, que ninguém nunca viu acontecer
• refinamento excessivo, aquele parágrafo que só existe porque o modelo tinha espaço pra escrever
• revisão que dobra de trabalho: agora tu revisa a spec E o código

Por que isso acontece?

Porque quando a spec desce ao nível de código, ela deixa de ser spec

O blog da Allegro coloca assim: ao especificar demais, o agente até implementa com muita precisão, mas em algum ponto "the line between specification and code starts to blur and the specification loses its value"

Sacou o problema? Se o documento descreve o como com a mesma precisão do código, ele virou uma segunda cópia do código, escrita em português e sem compilador pra dizer que ela está errada

Como consertar e como prevenir:

O conserto é bruto e funciona: passa o olho linha a linha e corta tudo que responde "como"

O que fica de pé é o critério de aceite verificável, aquela frase que outra pessoa consegue ler e dizer se o resultado está certo ou errado

Pra prevenir, o caminho não é escrever menos prosa vaga, é escrever menos prosa e mais estrutura

Times que estão experimentando SDD relatam justamente que os formatos tradicionais de requisito são vagos demais, e por isso adotam formatos estruturados como EARS (Easy Approach to Requirements Syntax), máquinas de estado e tabelas de decisão

Uma tabela de decisão de dez linhas mata três parágrafos de "o sistema deverá considerar os casos em que"

E vale reconhecer que acertar esse ponto é difícil pra todo mundo: o Technology Radar da Thoughtworks lista spec-driven development como técnica e registra que desenvolvedores e líderes de engenharia lutam pra achar o equilíbrio entre planejar demais e planejar de menos, a ponto de algo ir pra produção sem ninguém entender como funciona ou sem testes

Quando vale detalhar e quando a spec é overhead

A pergunta não é "quanto detalhe", é "detalhe pra qual tipo de trabalho"

Tarefa leve: SDD é exagero

A Allegro é explícita nisso: pra tarefas leves e de baixa complexidade, o SDD é overhead desnecessário

O exemplo citado é adicionar um campo novo em uma API

Nesse caso o método provavelmente é exagero e só complica uma tarefa simples

Se tu já sabe o arquivo, a linha e o efeito, escrever seis artefatos antes é cerimônia

Mudança pequena com alguma incerteza: plan mode resolve

Tem um meio termo bem mais barato que um fluxo completo de spec

No Claude Code existe o plan mode, em que o Claude pesquisa e propõe as mudanças sem editar o código-fonte

Tu chega nele ciclando os modos de permissão com Shift+Tab, ou prefixando um prompt único com /plan

Dentro do modo, o Claude lê arquivos e roda comandos de exploração, escreve um plano, e não edita o código

Seguindo com o Shift+Tab tu sai do modo sem aprovar o plano

Detalhe importante pra não se perder: o Shift+Tab cicla entre os modos de permissão durante a sessão, na ordem default → acceptEdits → plan (isso no CLI; nas versões VS Code, Desktop e claude.ai existe um seletor de modo)

Quer dizer: saindo do default, o plan mode não está no primeiro toque, tu passa pelo acceptEdits antes

Isso conversa direto com a documentação oficial de boas práticas do Claude Code, que recomenda um fluxo de explorar, planejar, implementar e commitar

Quer dizer: planejar antes de codar continua valendo, mas planejar não é sinônimo de gerar oito arquivos de Markdown

Se tu ainda está decidindo em qual dos dois mundos o seu projeto cai, escrevi um comparativo direto sobre quando usar spec ou vibe coding

Sistema de produção com vida longa: escolhe o nível de rigor

Aqui a spec deixa de ser opcional, e a discussão vira o quanto ela manda no código

Um artigo acadêmico no arXiv, "Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants" (arXiv 2602.00180), formaliza três níveis de rigor:

1. spec-first: a spec semeia a geração inicial e o código pode divergir depois
2. spec-anchored: a spec é mantida junto do código durante a vida do sistema, com testes garantindo o alinhamento
3. spec-as-source: humanos editam só a spec e a máquina gera todo o código

O spec-anchored é apontado como o ponto de equilíbrio pra maioria dos sistemas em produção

Faz sentido, né? É o único dos três em que existe um mecanismo automático (os testes) dizendo se a spec e o código ainda combinam

No spec-first a spec vira folclore conforme o código anda sozinho, e o spec-as-source cobra um nível de detalhe altíssimo justamente porque nada mais além dela é editável

O que eu vi na prática usando SDD

No vídeo do canal eu montei um gerador de QR code seguindo o método, executando por etapas: setup, autenticação e a funcionalidade principal, cada uma pedida separadamente

A parte que mais me impressionou foi a autenticação: com a tarefa já escrita na spec, a IA implementou em cerca de 2 minutos

E os prompts ficaram ridículos de curtos, do tipo "lê esses arquivos e executa a tarefa X"

Esse é o ganho real do detalhe bem colocado: o esforço todo fica no início, e as etapas seguintes viram algo previsível e sequencial

Uma coisa que eu recomendo mesmo assim é ser explícito no prompt em vez de implícito, mesmo quando o modelo provavelmente entenderia sozinho, só pra garantir que ele PARE na tarefa que você pediu

Onde eu vi o custo aparecer:

Especificar não é de graça

A etapa de planejamento consome tokens a mais, porque o modelo raciocina mais pra produzir algo cuidadoso

Por causa disso, o arquivo de contexto do projeto eu gerei de forma sucinta, só com o conhecimento condensado e referências aos outros documentos, pro modelo gastar menos token toda vez que lê aquilo

Repare que isso é o oposto de inchar a spec: quanto mais o documento se repete, mais caro fica CADA execução seguinte

E tem caso em que simplesmente não compensa: projeto pessoal que ninguém vai usar é queima de token

A régua que eu uso pra decidir é grosseira e resolve: se o projeto passa de três prompts, ou se envolve autenticação, pagamento, usuário admin e comum e dashboard, provavelmente precisa de spec

E o outro lado, sem spec nenhuma?

O oposto é o projeto sem base: sem planejamento, a IA escolhe stack, features e design por conta própria, e o resultado destoa do que você queria

O problema disso não aparece no dia um, aparece na escala

O consumo de tokens sobe feio quando uma funcionalidade nova obriga a regra de negócio inteira a mudar

E decisão ruim tomada no começo faz o projeto travar depois em coisa simples, mesmo tendo avançado rápido nos primeiros dias

Aplicação simples e projeto pessoal funcionam sem spec numa boa, o gargalo aparece quando a intenção é comercializar e crescer

Quem não é técnico sai em desvantagem nas decisões de arquitetura, isso é fato, e dá pra apoiar essas escolhas na IA, com a ressalva honesta de que o resultado não equivale ao de um arquiteto experiente

No vídeo acima eu mostro o fluxo completo do método na prática, do documento até a implementação

Conclusão

O nível de detalhe da spec tem um ponto de parada bem definido: escreva até o ponto em que outra pessoa (ou a IA) conseguiria verificar se o resultado está certo, e pare ali

Tudo que vem depois disso é decisão de implementação disfarçada de requisito, e é ela que engessa quem codifica, borra a linha entre spec e código e faz a revisão dobrar

O próximo passo é bem prático: pega a última spec que você escreveu, marca cada linha como produto ou implementação, e move a segunda metade pro plano

Aposto que o arquivo encolhe pela metade e não perde nada de valor 😀

até o próximo post!