Quando escrever spec atrapalha no Claude Code (e quando ela salva o trabalho)?

Fala aí, beleza? Existe um momento exato em que a spec para de ajudar e começa a atrapalhar: quando você abre um documento de especificação pra trocar a cor de um botão 😅

De um lado tem a turma do spec-driven development dizendo que sem documento tudo vira vibe coding malfeito

Do outro tem quem só digita o pedido na caixa e segue a vida

E a discussão costuma ser tratada como religião, quando na real é dosagem. Bora colocar os dois lados na mesa e sair daqui com um corte simples pra decidir em 10 segundos qual usar na PRÓXIMA tarefa que tu abrir

O que conta como "escrever spec" no Claude Code

Antes de brigar sobre spec sim ou spec não, vale separar do que a gente tá falando

Porque "escrever spec" virou nome pra três coisas bem diferentes, com custos bem diferentes

Nível 1: o pedido direto

Você descreve a tarefa, o Claude vai lá e faz

Custo de processo antes de codar: zero

Nível 2: o plan mode

O plan mode do Claude Code é somente leitura: ele lê arquivos, roda comandos de exploração e propõe as mudanças sem aplicar nada

As edições ficam bloqueadas até você aprovar o plano

Dá pra entrar nele de várias formas oficiais: o comando /plan, ciclar os modos com Shift+Tab no CLI, o seletor de modo no VS Code e no Desktop, ou já abrir a sessão dentro dele:

claude --permission-mode plan

E quais modos existem, afinal? São estes: default (Manual), acceptEdits, plan, auto e dontAsk

Guarda esses nomes, porque eles voltam lá na tabela do post 🙂

Nível 3: o toolkit completo de spec-driven development

Aqui a coisa fica formal de verdade

O Spec Kit é um toolkit de spec-driven development mantido pelo GitHub, no repositório github/spec-kit, com comandos core /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks e /speckit.implement

Ele se integra a mais de 30 agentes de código, então não é brinquedo de nicho

E tem também o OpenSpec, repositório Fission-AI/OpenSpec, que se apresenta como um tracker leve, em contraste com o Spec Kit como toolkit completo pra construir do zero

Se você já usou linter, CI e template de pull request, a pegada é a mesma: processo que te protege de você mesmo, e que cobra pedágio em toda passagem

O custo cresce nessa ordem, do nível 1 pro nível 3. Segura essa ideia

Quando a spec só atrapalha: os casos em que ela custa mais do que economiza

Tem tarefa que morre de burocracia antes de nascer

Um guia público sobre Claude Code e spec-driven development chega a recomendar pular a spec em casos específicos: correção de bug de arquivo único, mudança de formatação e CRUD bem entendido que um único prompt resolve

O argumento é direto: escrever spec nesses casos custa mais do que economiza

E eu acrescento um quarto caso, que é o mais subestimado:

• Exploração. Quando você ainda não sabe o que quer descobrir, escrever spec é chutar o resultado antes de olhar o terreno

Especificar um destino que você ainda não conhece é o jeito mais rápido de amarrar o agente na sua hipótese errada

E se der ruim sem documento nenhum?

Essa é a pergunta certa, e a resposta não é "reza"

O /rewind volta código e conversa para um checkpoint

O /clear começa uma tarefa nova mantendo a memória do projeto

Essa dupla é a rede de segurança que substitui o documento em tarefa curta. Se o pedido direto deu errado, tu rebobina e pede de novo com mais contexto, e ainda assim sai mais barato que ter escrito três seções de spec pra mudar um arquivo

E não, o incômodo não é só teu

Esse desconforto aparece no próprio repositório do Spec Kit, em público

A Issue #442 pede um fluxo de debug pós-implementação

A Discussion #1784 acusa o Spec Kit de gerar "ilusão de trabalho"

E a Issue #2673 pede comandos mesclados pra simplificar o fluxo

Ou seja: quem usa o toolkit completo também sente o peso quando a tarefa é pequena. Não é frescura tua

Quando a spec salva o trabalho

Agora o outro lado, porque tem tarefa em que pular o planejamento é jogar dinheiro fora

O guia oficial de boas práticas da Anthropic recomenda o fluxo explorar, planejar, codar, commitar

E avisa uma coisa importante: sem as etapas de pesquisa e planejamento, o Claude tende a pular direto pra escrever a solução

Sacou o risco? Ele te entrega código lindo pro problema errado

Os casos em que vale pagar o pedágio:

• Problemas que exigem raciocínio prévio, não digitação
• Escopo que atravessa vários arquivos
• Tarefa em que "pronto" é ambíguo, e cada pessoa da conversa entende uma coisa

E isso é mais comum do que parece: na pesquisa da Anthropic sobre uso real do Claude Code, cerca de 14% das sessões são justamente planejar ou entender sistemas, contra cerca de 56% de escrever, corrigir, testar ou orquestrar código, cerca de 17% de operar software e cerca de 13% de análise ou texto

Dá pra comprar raciocínio sem abrir documento

Essa parte é MUITO subestimada

Existe uma escala de palavras que aumenta o orçamento de raciocínio estendido no Claude Code: "think" < "think hard" < "think harder" < "ultrathink"

É o meio-termo mais barato que existe: você não escreve spec nenhuma, só pede mais pensamento antes da resposta

E se você quiser revisar de verdade antes de liberar as edições, o plan mode entrega isso bonitinho: no VS Code o plano abre como documento Markdown completo, com comentário inline, então dá pra marcar o ponto errado direto no texto antes de o Claude começar

Se o teu caso pede o processo completo mesmo, eu já detalhei aqui como escrever a spec antes de implementar sem virar burocracia

O caso em que a spec deixa de ser sobre você

Tem uma situação em que o documento não é sobre organizar a sua cabeça: é sobre alinhar mais de uma

Quando mais gente mexe no mesmo código, a spec vira o combinado do que é "pronto", e não a preferência de quem digitou o prompt

Aí o processo entra numa conta maior, junto com assentos e custo por dev, porque processo compartilhado só existe se o time inteiro estiver na mesma ferramenta

O que eu vi na prática montando um time de especialistas no Claude Code

Eu rodei do zero o GStack, um framework que transforma o Claude Code numa espécie de equipe de especialistas, e gravei o processo inteiro

No vídeo abaixo tu vê o fluxo completo, do comando de partida até o wireframe da interface, com meus comentários em cada etapa:

Já começo pelo que me incomodou: a instalação não é aquele next, next e finish dos plugins e das skills

Tu precisa pegar os comandos no repositório e colar dentro do próprio Claude Code, numa pasta em branco

Depois disso, o fluxo começa por um comando de partida que já cria um arquivo de instruções e abre uma sequência de perguntas antes de qualquer linha de código

E é aqui que mora a parte boa e a parte chata, juntinhas

A parte boa: o questionário me confrontou de verdade. Ele quis saber por que alguém usaria minha rede social em vez de Twitter ou Instagram, e como eu ia monetizar uma coisa que é gratuita

Ideia ruim é desmontada nesse processo, sem dó

A parte chata: uma parte das perguntas não mudava nada no que ia ser construído (objetivo, estágio do produto), e eu respondi só pra seguir adiante

Depois do questionário ainda vieram ciclos de refinamento da ideia antes da aprovação final. E quando cheguei na hora de escolher entre as três abordagens sugeridas, o produto JÁ tinha mudado de foco em relação ao que eu descrevi no começo

Outra coisa que achei massa: antes de programar qualquer coisa, o fluxo gerou um wireframe da interface pra eu aprovar ou pedir mudança. Isso é exatamente o tipo de checkpoint que economiza retrabalho em tarefa grande

Aí veio o meu pecado, e eu confesso ele no vídeo: aprovei o documento de design sem ler tudo

O certo era abrir os arquivos gerados na pasta do framework e ler antes de aprovar. Falei isso na hora, e continua valendo pra ti

E olha, não é preguiça isolada minha, não

A própria Anthropic conta que os usuários aprovam 93% dos prompts de permissão, e chama isso de fadiga de aprovação. Foi um dos motivos pro auto mode existir, com um classificador de transcrição rodando no Sonnet 4.6 avaliando cada ação antes de executar, em duas etapas, em vez de te perguntar toda vez

Agora junta as duas coisas: quanto mais material o processo gera pra você aprovar, mais o "aprovar" vira reflexo

Spec que ninguém lê não é garantia de nada, é só um arquivo bonito no repo

Outras anotações da rodada:

• Recusei a etapa de segunda opinião, porque ela dependia de outra ferramenta instalada na máquina que eu não tinha, e ia dar erro
• Neguei a telemetria, mas deixei ligadas a proatividade e as regras de roteamento de skills, porque o próprio fluxo recomendava
• Liberei a varredura dos outros projetos da máquina pro framework aprender padrões, que era um passo opcional
• Mesmo eu escrevendo em português, o fluxo continuou respondendo em inglês. Imagino que dê pra pedir isso logo no começo
• E deixei uma pergunta em aberto durante a gravação: isso consome muito token?

Minha conclusão depois de rodar: o ganho é dar começo, meio e fim ao projeto e cortar o vibe coding malfeito que termina em bug ou projeto invadido

O preço é passar por um questionário longo, com perguntas que não mudam o resultado, e ter disciplina de ler tudo antes de aprovar, senão o produto sai diferente do que tu pediu

Pedido direto, plan mode ou spec completa: qual usar em cada tarefa

Critério	Pedido direto	Plan mode	Spec completa (toolkit)
Custo de tempo antes de codar	Zero: você descreve e ele já executa	Baixo: ele lê, pesquisa e escreve o plano sem tocar no código	Alto: constitution, specify, plan, tasks e só então implement
Tipo de tarefa em que rende	Bug de arquivo único, formatação e CRUD bem entendido que um prompt resolve	Escopo que atravessa arquivos e tarefa em que "pronto" é ambíguo	Projeto do zero, com várias etapas e mais gente envolvida
O que você revisa	O diff, direto	O plano antes da edição (no VS Code ele abre como Markdown com comentário inline)	Os documentos de cada etapa, e só depois o código
Se der errado	/rewind volta código e conversa pro checkpoint, /clear abre tarefa nova mantendo a memória do projeto	Você reprova o plano antes de qualquer edição, porque o modo é somente leitura	Você descobre tarde, porque o erro pode estar num documento que você aprovou lá atrás
Modo ou ferramenta	default (Manual), acceptEdits, auto ou dontAsk	plan, via /plan, Shift+Tab ou claude --permission-mode plan	Spec Kit como toolkit completo, ou OpenSpec como tracker leve

O corte simples para decidir em 10 segundos

O corte é este, e cabe em duas linhas:

Se você consegue escrever o critério de "pronto" em UMA frase, e a mudança cabe em poucos arquivos, peça direto

Se você trava na frase, o problema não é o Claude, é o escopo. Aí vale planejar antes

Por que esse corte funciona? Porque ele devolve pra ti a parte que sempre foi tua

A Anthropic analisou cerca de 400 mil sessões interativas de cerca de 235 mil pessoas, entre outubro de 2025 e abril de 2026

Nessas sessões, as pessoas tomam cerca de 70% das decisões de planejamento (o que fazer, o que conta como pronto), e o Claude toma cerca de 80% das decisões de execução (quais arquivos mudar, que código escrever, que comandos rodar)

A divisão de trabalho já é essa, com ou sem documento. A spec é UMA forma de entregar a tua parte, não a única

E tem outro achado que me pegou: quanto maior o domínio da pessoa sobre o assunto, mais trabalho o Claude faz por instrução. E uma noção funcional do domínio já captura a maior parte do ganho

Repara que não é habilidade de escrever código, é entender o assunto. Quem entende o problema escreve o critério de pronto em uma frase, e é por isso que o corte funciona

O contra-argumento, porque seria sacanagem esconder

Existe uma crítica publicada bem direta à regra de "pular spec em mudança pequena"

O argumento é o seguinte: se o teu fluxo de spec é pesado a ponto de você pulá-lo em mudanças pequenas, você perde o benefício justamente onde mudanças pequenas têm escopo pouco claro

E eu acho isso honesto demais pra ignorar

A leitura que eu faço é que ele não derruba o corte, ele ataca o PESO do processo. Se a tua spec fosse barata, você não precisaria escolher entre ter processo e ter velocidade

É por isso que o plan mode e a escala think, think hard, think harder, ultrathink importam tanto nessa conversa: são as formas baratas de ter planejamento sem virar cerimônia

Conclusão: quanto processo o problema aguenta?

A pergunta nunca foi "spec sim ou spec não"

A pergunta é quanto processo o problema aguenta antes de o processo custar mais que o problema

Tarefa curta com critério claro: pedido direto, com /rewind como rede

Tarefa ambígua ou que atravessa arquivos: plan mode antes de liberar edição, e leia o plano de verdade

Projeto do zero, com mais gente e várias etapas: aí sim o toolkit completo se paga

Meu próximo passo sugerido é bem concreto: roda a tua próxima tarefa curta no pedido direto e a próxima tarefa ambígua no plan mode, na mesma semana, e compara o retrabalho de cada uma

E tem um sinal interessante no meio disso tudo: as sessões dedicadas a consertar código quebrado caíram de 33% em outubro de 2025 para 19% em abril de 2026

O trabalho tá migrando de conserto pra construção. E construção é exatamente onde planejar antes começa a valer o pedágio…

Me conta nos comentários qual foi o teu corte, se tu já tem um. Até o próximo post! 😀

Perguntas frequentes

Plan mode e Spec Kit são a mesma coisa no Claude Code?

Não. O plan mode é nativo do Claude Code e só de leitura: ele lê arquivos, propõe mudanças e trava as edições até você aprovar o plano. Já o Spec Kit é um toolkit à parte, mantido pelo GitHub no repositório github/spec-kit, com comandos próprios como /speckit.specify e /speckit.plan. São dois níveis diferentes de formalidade na hora de decidir se vale escrever spec no Claude Code antes de codar.

Quais são as formas de entrar no plan mode do Claude Code?

Dá pra usar o comando /plan, ciclar os modos com Shift+Tab no CLI, escolher pelo seletor de modo no VS Code ou no Desktop, ou já abrir a sessão direto nele com claude –permission-mode plan. Qualquer uma dessas formas trava as edições até você aprovar o plano.

Quais modos de permissão existem no Claude Code além do plan?

Além do plan, são quatro: default (Manual), acceptEdits, auto e dontAsk. Cada um muda o quanto o Claude pede aprovação antes de agir, do mais manual ao mais autônomo.

O Spec Kit funciona com outro agente de código, não só o Claude Code?

Funciona sim. O Spec Kit se integra a mais de 30 agentes de código, então o fluxo /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks e /speckit.implement não é exclusivo do Claude Code.

Existe alternativa mais leve ao Spec Kit pra mudança pequena em projeto que já existe?

Existe o OpenSpec, no repositório Fission-AI/OpenSpec. Ele se apresenta como um tracker leve, em contraste com o Spec Kit, que é posicionado como toolkit completo pra construir do zero.

Como aumentar o raciocínio do Claude Code sem escrever spec nenhuma?

Usando a escala de palavras que aumenta o orçamento de raciocínio estendido: think, think hard, think harder e ultrathink. É o meio-termo mais barato: você pede mais pensamento antes da resposta sem abrir documento nenhum.