Spec detalhada demais ou vaga demais: qual é o nível certo de detalhe?

Fala aí, beleza? O conceito de spec já entrou na cabeça de todo mundo, o que ninguém fala é onde PARAR de escrever

Você senta, escreve o objetivo, escreve o contrato, e a spec começa a crescer sozinha

Aí bate a dúvida que trava todo mundo: detalhei demais? Ou deixei vago e o agente vai inventar moda?

Os dois lados quebram o processo do mesmo jeito. Granular demais e você já podia ter escrito o código na mão, vago demais e você perde as guardrails (os limites) que fazem a spec existir

A régua deste post é o risco da tarefa: o nível de detalhe da spec não é uma constante, ele sobe e desce conforme o que pode dar errado

Os dois extremos que quebram o processo

Extremo 1: a spec que virou pseudocódigo

O sintoma: tu abre a spec e ela já diz qual função criar, qual loop usar, em que ordem chamar cada método

Se alguém pudesse colar aquilo no editor e quase compilar, não é mais spec, é código escrito em português

A causa: medo. Quando não confiamos no agente, a reação natural é fechar TODAS as portas, e fechar todas as portas significa decidir a implementação no lugar dele

O custo: você perde justamente a vantagem de o modelo achar a solução algorítmica, que é o motivo de ele estar ali

E tem custo mensurável também. Um estudo conduzido por pesquisadores da ETH Zurich avaliou se arquivos de contexto de repositório (os famosos AGENTS.md e CLAUDE.md) ajudam agentes de código, e o resultado foi um banho de água fria: arquivos de contexto gerados por LLM REDUZIRAM a taxa de sucesso em cerca de 3%, e os escritos por desenvolvedor deram um ganho marginal de cerca de 4%

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

Pior: no mesmo estudo os arquivos de contexto aumentaram o custo de inferência em mais de 20% e todos eles aumentaram consistentemente o número de passos pra resolver a MESMA tarefa

Se liga que arquivo de contexto não é spec, são coisas diferentes, mas o mecanismo é o mesmo: texto empilhado não é gratuito, ele compete por atenção e por contexto

E tem o outro lado da mesma moeda, o paper "Curse of Instructions": a aderência dos modelos cai conforme o número de instruções simultâneas cresce

No benchmark ManyIFEval (até dez instruções objetivamente verificáveis), seguir as dez ao mesmo tempo deu 15% no GPT-4o e 44% no Claude 3.5 Sonnet

Ou seja, quanto mais regra você empilha, menos regra é cumprida… não é intuitivo, mas faz todo sentido

Como prevenir: toda vez que uma linha da spec descrever COMO em vez de O QUE, pergunte se aquilo é contrato ou preferência sua. Preferência sai

Extremo 2: a spec que só repete o pedido

O sintoma: a spec diz "criar um sistema de login seguro e performático" e acabou

É o pedido reescrito com palavra bonita, sem nada que o agente possa verificar

A causa: a gente confunde "curto" com "enxuto". Curto sem contrato não é enxuto, é vago

O GitHub analisou arquivos agents.md de mais de 2.500 repositórios e a falha mais comum foi exatamente essa: o arquivo genérico, do tipo "you are a helpful coding assistant"

A solução, seguindo o que o próprio GitHub identificou como padrão do que funciona:

• papel específico, não "assistente prestativo"
• comandos executáveis logo no início
• limites bem definidos
• exemplos de código em vez de explicação

Repara que exemplo de código aqui NÃO é o mesmo que o extremo 1. Exemplo mostra o formato esperado, pseudocódigo dita a implementação inteira

Como prevenir: leia cada linha da spec e pergunte "dá pra conferir se isso foi cumprido?". Se não dá, é enfeite

A formulação que especialistas em spec pra agentes usam resume bem: sub-especificar deixa espaço demais pra interpretação, sobre-especificar borra a linha entre especificação e código

Nível 1 e Nível 2: o que é inegociável e o que é do modelo

A saída pro dilema é parar de tratar a spec como um documento só e enxergar duas camadas, uma rígida e outra flexível

Nível 1 é intenção e contrato, e é inegociável. Nível 2 é implementação interna, e você deixa pro modelo

A regra prática que sai dessa tabela: rigor total no que é observável de fora, liberdade total no que é detalhe de dentro

Spec no nível de pseudocódigo faz o humano "programar em inglês", e programar em inglês é o pior dos dois mundos: nem tem a precisão da linguagem, nem tem a criatividade do modelo

O que ter em mãos antes de escrever a spec

Antes de abrir o arquivo, três coisas precisam estar decididas na sua cabeça, senão a spec vira brainstorm:

1. O contrato da tarefa: entradas, saídas e restrições. Se você não consegue dizer o que entra e o que sai, ainda não é hora de escrever spec
2. O critério de pronto: como você vai saber que terminou, de forma verificável (não "funcionar bem", e sim algo checável)
3. O agente configurado: com que ferramenta você vai rodar isso

Nesse terceiro ponto vale saber que o Claude Code tem um modo de planejamento em que o agente pesquisa e propõe as mudanças SEM editar arquivos, o plan mode

E existe o Spec Kit, um toolkit de spec-driven development mantido no repositório github/spec-kit, pra quem quer as camadas separadas em arquivos diferentes em vez de um documentão só

Os dois voltam mais pra frente com o passo a passo: o plan mode no passo 5 do processo aqui de baixo, e o Spec Kit na seção sobre separar as camadas em arquivos 🙂

Como calibrar o detalhe da spec pelo risco da tarefa

Addy Osmani tem uma formulação que eu gosto muito: a régua é "spec mais inteligente, não mais longa"

A ideia dele é calibrar o detalhe pela complexidade da tarefa, e não escrever sempre no mesmo nível. Não sub-especificar problema difícil (o agente se perde) nem sobre-especificar tarefa trivial (o agente se enrosca e gasta contexto)

Bora ao processo

1. Classifique a tarefa por risco e complexidade antes de escrever qualquer linha

De um lado, tarefa isolada: centralizar um div não pede PRD nenhum

Do outro, fluxo com estado, erro e integração: um fluxo OAuth com refresh de token e tratamento de erro pede spec detalhada mesmo

Erro comum deste passo: usar o mesmo template pra tudo. O template é confortável e é justamente ele que produz spec sobre-especificada em tarefa trivial

2. Escreva primeiro o Nível 1 e PARE ali quando a tarefa é simples

Contrato, restrições, critério de pronto. Ponto

Se a tarefa é isolada, essa é a spec inteira, e tá tudo certo

Erro comum deste passo: continuar escrevendo por insegurança. Se você já descreveu o que entra, o que sai e como conferir, o resto é palpite de implementação

3. Desça pro Nível 2 só nos pontos de risco real

Risco real é onde o erro é caro ou silencioso: dado que não pode vazar, contrato com sistema externo, estado que não pode dessincronizar

Nesses pontos, detalhe. No resto da mesma tarefa, siga solto

Erro comum deste passo: achar que risco é o mesmo que "parte que eu não entendo". Não é. Parte que você não entende é onde o modelo ajuda mais

4. Corte instrução simultânea redundante

Lembra do ManyIFEval? Dez instruções ao mesmo tempo derrubaram a aderência pra 15% no GPT-4o e 44% no Claude 3.5 Sonnet

Com auto-refinamento iterativo em tempo de inferência esses números sobem pra 31% e 58%, o que é MUITO significativo: revisar em passadas funciona melhor que empilhar tudo de uma vez

Traduzindo pro seu dia: prefira uma spec que cabe numa rodada e uma segunda passada de ajuste, em vez de trinta regras simultâneas esperando que todas sejam obedecidas

Erro comum deste passo: manter a regra "por garantia". Regra que não muda resultado observável só rouba aderência das que importam

5. Valide a spec com o agente ANTES de deixar ele executar

No Claude Code, o plan mode existe pra isso: o agente pesquisa e propõe as mudanças sem editar arquivo

Tem três jeitos de entrar:

• Shift+Tab cicla os modos de permissão até chegar no plan mode
• prefixar o prompt com /plan planeja só aquele turno
• iniciar a sessão já em plano

claude --permission-mode plan

Dentro do plan mode as ferramentas de leitura rodam normalmente e as edições de arquivo NUNCA são auto-aprovadas, mesmo que você tenha regra de allow configurada

Quando você aprova o plano, a sessão sai do modo plano e passa a editar

E tem um detalhe que pouca gente usa: Ctrl+G abre o plano proposto no seu editor de texto padrão, pra você ajustar na mão antes do Claude seguir

É aí que você descobre se a spec ficou vaga: se o plano proposto inventou decisão que você não autorizou, falta contrato no Nível 1

Erro comum deste passo: aprovar o plano no automático, no next, next e finish. O plano é o feedback mais barato que você vai ter sobre o seu próprio texto

Quando separar as camadas em arquivos diferentes

Tem um momento em que o documento único não segura mais: quando princípios do projeto, requisitos, plano técnico e tarefas viram um bolo só e ninguém sabe qual parte é inegociável

O Spec Kit resolve isso separando essas camadas em comandos distintos

A instalação e o bootstrap saem de um comando, que é rodável via uvx, com --integration claude entre as opções de agente:

specify init --integration claude

Os comandos slash ficam instalados na pasta do agente do projeto: .claude/ no caso do Claude Code, .github/prompts/ no caso do Copilot

O fluxo separa assim:

• constitution: princípios do projeto
• specify: o que construir (requisitos e histórias)
• plan: o plano técnico, com a stack
• tasks: a lista de tarefas acionáveis
• implement: a execução

E existem checagens opcionais entre as etapas, com clarify e analyze, sendo que o analyze cruza spec, plano e tarefas atrás de incoerência

Repara que essa separação É a hierarquia de que a gente falou, só que materializada em arquivo: o que é contrato mora num lugar, o plano técnico mora em outro

Quando compensa: tarefa com muita superfície, time com mais de uma pessoa mexendo, projeto onde a mesma decisão precisa valer daqui a três semanas

Quando é sobrecarga: ajuste pontual, script de uma vez só, aquela correção que você já sabe descrever em quatro linhas. Aí montar cerimônia de cinco etapas custa mais caro que o trabalho em si

Esse raciocínio conversa direto com onde parar de detalhar a spec, e se o termo ainda te confunde na hora de buscar material, vale entender por que o termo certo é spec-driven development e não a sopa de siglas que rola por aí

Conclusão

A régua do nível de detalhe da spec cabe em uma frase: rigor no contrato, liberdade na implementação, detalhe proporcional ao risco

Granular demais e você já podia ter escrito o código, vago demais e você fica sem guardrail nenhuma. O meio não é um número mágico de linhas, é uma decisão por camada

O próximo passo é concreto e dá pra fazer hoje: pega a próxima tarefa da tua lista, escreve SÓ o Nível 1 (entradas, saídas, restrições, critério de pronto), roda em plan mode e lê o plano proposto

Se o plano estiver certo, tua spec já estava boa e você economizou duas páginas de texto

Se ele inventou moda em algum ponto, ali é o único lugar onde falta detalhe… e só ali 😀

até o próximo post!