Spec ou prompt gigante: qual a diferença na prática no Claude Code?

Fala aí, beleza? Aquele prompt de 40 linhas escrito de uma tacada, enter, e torcer pra IA acertar: todo mundo já fez isso hoje de manhã 😀

O contexto que você precisa entregar é o mesmo nos dois casos: o que construir, quais arquivos mexer, quais regras seguir, o que NÃO fazer

A diferença entre despejar tudo num prompt gigante e manter uma spec no Claude Code, ou seja, um documento que a sessão consulta, quase não aparece na primeira sessão

Ela aparece na segunda

Quando o histórico foi compactado, quando você deu /clear, quando outra pessoa do time abriu o repo e perguntou "o que ficou combinado aqui mesmo?"

Bora comparar item a item?

Prompt gigante x spec em arquivo: comparação item a item

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Repara que quase toda linha da coluna do meio depende de uma coisa só: a conversa continuar viva do jeito que você deixou

E conversa é justamente a parte volátil

Um detalhe que pega muita gente no subagente: a janela de contexto dele começa zerada, e o único conteúdo que passa do pai pra ele é a string de prompt da ferramenta Agent

Caminho de arquivo, mensagem de erro, decisão que vocês tomaram: tudo isso precisa ir escrito ali

A auto memory da conversa principal também não é carregada no subagente

A exceção é o fork, que herda a conversa inteira

"E o CLAUDE.md?" O CLAUDE.md é o caso especial: ele é lido no início de toda sessão, sem você pedir, seguindo a hierarquia de diretórios (o do diretório de trabalho e o de cada diretório pai carregam no launch, enquanto o de um subdiretório só entra sob demanda, quando o Claude lê arquivos daquela pasta)

Já o SPEC.md a doc não descreve como carregamento automático, então aponte pra ele no seu prompt: "leia SPEC.md e siga"

O que acontece quando a conversa se perde no meio da tarefa

O sintoma você já viu: no meio de uma tarefa longa o Claude volta propondo uma abordagem que vocês descartaram meia hora atrás

Ou esquece aquela regra que você combinou lá no começo, na terceira linha do prompt inicial

A causa não é má vontade: ao se aproximar dos limites de contexto, o Claude Code resume o histórico da conversa pra caber na janela

O que só existia dentro do prompt vira resumo do prompt

E resumo perde detalhe, é o trabalho dele perder detalhe 🙂

A solução passa por comandos que já estão no seu terminal:

• /context mostra a quebra ao vivo do uso por categoria, incluindo quais arquivos CLAUDE.md e de auto memory carregaram
• /compact aceita instrução, tipo /compact Focus on the API changes
• /autocompact aceita uma contagem de tokens, tipo /autocompact 500k, pra definir quão cheio o contexto fica antes do passe automático
• /clear reseta o contexto pra uma tarefa nova, mantendo a memória do projeto
• Esc + Esc ou /rewind deixa escolher um checkpoint de mensagem e usar Summarize from here ou Summarize up to here, resumindo só um trecho

Tome cuidado com uma coisa no /rewind: o checkpointing não rastreia arquivos modificados por comandos bash, só edições feitas pelas ferramentas de edição de arquivo do Claude

Os checkpoints são salvos junto com a conversa, então ele continua funcionando depois de retomar a sessão

Mas a prevenção de verdade é outra: o que precisa sobreviver mora em arquivo, não no histórico

Spec, CLAUDE.md, checklist

E mesmo em arquivo tem régua: na auto memory, as primeiras 200 linhas ou os primeiros 25 KB do índice MEMORY.md, o que vier primeiro, carregam no início de cada conversa

O que passa disso não é carregado no início da sessão

Ou seja, índice enxuto, detalhe no arquivo certo

Como montar a spec que a sessão consulta, passo a passo

O roteiro abaixo é basicamente o que a documentação de boas práticas recomenda pra features maiores

1. Comece com um prompt mínimo e peça a entrevista. Em vez de escrever a feature inteira, peça pro Claude te entrevistar usando a ferramenta AskUserQuestion sobre implementação técnica, UI/UX, casos de borda, preocupações e tradeoffs

Quero adicionar autenticação neste projeto.
Antes de escrever qualquer coisa, me entreviste com AskUserQuestion
sobre implementação técnica, UI/UX, casos de borda e tradeoffs.

O erro comum deste passo é já despejar tudo no primeiro prompt: aí não sobra pergunta pra fazer, e as decisões que você não tomou de propósito são tomadas por você

2. Peça a spec completa em SPEC.md. As specs mais úteis são autocontidas: nomeiam os arquivos e as interfaces envolvidos, dizem o que está fora de escopo e terminam com um passo de verificação ponta a ponta

O erro comum aqui é escrever só o caminho feliz e esquecer o "fora de escopo"

Essa parte é a que mais me salva, e conto o porquê lá embaixo

3. Revise no plan mode antes de qualquer edição. Aperte Shift+Tab até a barra de status mostrar o plan mode ligado, ou prefixe o prompt com /plan

Nesse modo o Claude lê arquivos e propõe um plano, sem editar nada até você aprovar

Ctrl+G abre o plano proposto no seu editor de texto padrão pra você editar direto antes dele seguir, e Shift+Tab de novo sai sem aprovar

O erro comum deste passo é aprovar no automático, sem ler: plan mode que você não lê é só um enter a mais

4. Transforme a execução em checklist. Pra tarefas grandes com muitos passos, peça ao Claude pra usar um arquivo Markdown como checklist e rascunho de trabalho, resolvendo item por item, verificando e marcando cada um

O erro comum é confiar na memória da conversa pra saber onde parou, exatamente o que a compactação come primeiro

5. Separe o que é regra permanente do que é tarefa. Regra de projeto vai pro CLAUDE.md, tarefa vai pra spec

O erro comum deste passo é o clássico: quebrar o CLAUDE.md gigante em vários imports @path achando que economiza contexto

Não economiza

Dividir em imports ajuda na ORGANIZAÇÃO, mas os arquivos importados carregam no launch do mesmo jeito, como explica a documentação de memória

Quando o prompt gigante basta e quando a spec paga a conta

Nem tudo merece documento, senão vira burocracia

• Bug isolado, correção de uma linha: prompt, sem cerimônia. Escrever spec pra isso é mais lento que o próprio fix
• Feature que vai levar várias sessões: spec mais checklist. É aqui que a compactação te encontra, e é aqui que o arquivo devolve o investimento
• Trabalho que outra pessoa do time revisa antes de rodar: spec versionada, dentro do repo em .claude/ (ou na raiz, no caso dos arquivos que moram lá). Pull request de spec é uma conversa muito melhor que pull request de código gerado às cegas
• Regra que vale pra todo dia e todo projeto: CLAUDE.md, e a versão global em ~/.claude/. A doc é bem específica sobre o que colocar: comandos bash que o Claude não teria como adivinhar, regras de estilo que fogem do padrão, instruções de teste e o test runner preferido, etiqueta do repositório (nome de branch, convenção de PR) e decisões de arquitetura específicas do projeto
• Preferência sua que não deve ir pro git: CLAUDE.local.md na raiz do projeto, que carrega junto com o CLAUDE.md e é tratado da mesma forma
• Delegação pra subagente: spec, sempre. Nada da conversa do pai viaja junto, lembra?

Herdou um repo com um CLAUDE.md que mais atrapalha que ajuda? Dá pra excluir arquivos CLAUDE.md do carregamento com claudeMdExcludes, que pode ser configurado em qualquer camada de settings: user, project, local ou managed policy

E se você ainda tá montando o fluxo completo de um projeto, vale começar por essa camada de arquivos antes de sair pedindo feature

(a diferença entre Claude Code e o Claude Desktop é outra conversa, mas tudo que tá aqui é sobre o Claude Code no terminal)

O que rodar o mesmo prompt em ferramentas diferentes me ensinou sobre especificar

Esse papo de spec não nasceu de teoria pra mim, nasceu de comparar ferramenta

No vídeo abaixo eu monto o mesmo app em duas ferramentas diferentes e, antes de mandar QUALQUER prompt, eu criei um arquivo markdown de referência do projeto nas duas

Esse arquivo descreve a análise do projeto, a stack utilizada, as regras que o projeto tem que seguir e os comandos que precisam rodar

Pra comparação ser justa eu copiei o mesmo arquivo de uma ferramenta pra outra, em vez de deixar cada uma gerar o seu

Aí tem o detalhe que virou vício meu: num vídeo anterior comparando ferramentas, senti que as IDEs passavam do escopo pedido e entregavam recurso além do combinado

Desde então eu coloco um bloco fixo de restrição no fim de todo prompt, dizendo explicitamente o que NÃO criar (sem upload, sem formulário, nada além da autenticação e da tela de boas-vindas)

E esse bloco é exatamente o "fora de escopo" que eu prometi explicar lá no passo 2

O porquê é simples: o que você não escreve não fica em branco, fica no chute da ferramenta

Tudo que ficou implícito vira decisão dela, e aí você gasta revisando (ou apagando) coisa que ninguém pediu justamente o tempo que a spec ia te economizar

Escrever duas linhas do que NÃO fazer é mais barato que revisar dez arquivos que não deviam existir, e ainda te dá um critério objetivo pra dizer "isso aqui passou do combinado" sem virar discussão de gosto

E o prompt termina pedindo pra ferramenta rodar o projeto e confirmar que login e registro funcionam, ou seja, o critério de aceite entra escrito no pedido

Ir além do pedido não é automaticamente ruim, olha: se a IA adiciona algo que eu já queria, é ganho, se adiciona algo fora de contexto, é problema

Por isso eu prefiro delimitar

O plano de teste foi fatiado em 5 prompts idênticos aplicados nas duas ferramentas, cada um com escopo fechado (setup e autenticação, upload de PDF, integração com IA, dashboard, landing page e polimento), em vez de um pedido único gigante

E eu uso sempre o modo de planejamento, evito o modo rápido, porque na minha experiência o modo rápido faz as coisas de forma atropelada

Gosto de ferramenta que separa claramente a fase de planejar da fase de executar, porque consigo enxergar o que tá acontecendo em cada etapa

Sobre cota: durante os testes e a gravação do curso, o consumo do plano Pro de uma das ferramentas não chegou nem a 50%

O aprendizado transferível pro Claude Code é esse: o que tornou a comparação possível foi a instrução estar escrita ANTES e ser idêntica

Instrução fixada em texto vira resultado comparável e repetível

Que é exatamente o argumento da spec, só que aplicado a você mesmo daqui a três dias, na sessão seguinte

No vídeo você vê o mesmo prompt caindo em ferramentas diferentes, com o mesmo arquivo de referência dos dois lados

Eu já entrava com uma leve tendência por causa da tabela comparativa, mas as duas ficaram bem pareadas, e deixei o veredito pra depois de comparar o código gerado

Ah, e vale o aviso: tenho muito mais vivência com uma das ferramentas do que com a outra, e isso pesa na minha opinião

Veredito: qual das duas abordagens vence na prática

Sem ficar em cima do muro: pra qualquer coisa que passe de uma sessão, a spec ganha

E não é achismo meu, a própria doc coloca a régua: o tempo investido em deixar a spec precisa rende mais do que o tempo gasto acompanhando a implementação

Faz sentido, né? Acompanhar implementação é caro e não deixa rastro, spec precisa é barata e fica no repo

Mas o custo do outro lado é real também

Escrever spec pra ajustar um texto de botão é burocracia pura, atrasa e ainda te dá a falsa sensação de rigor

A linha de corte que eu uso é essa: se a tarefa cabe numa sessão, prompt resolve, se ela vai precisar de uma segunda sessão, escreve a spec

E tem o teste do colega: se você não conseguiria mandar esse prompt pra outra pessoa do time revisar antes de rodar, ele já deveria ser arquivo

Conclusão

Recapitulando o que muda de verdade: prompt gigante vive no histórico, e histórico é resumido quando o contexto aperta e some no /clear

Spec vive em arquivo, é revisável, versionável, reaproveitável e é a única forma de o contexto chegar num subagente, que começa do zero

E não esquece do "fora de escopo": é a linha que impede a ferramenta de preencher sozinha o que você não escreveu

Seu próximo passo, bem concreto: pega aquela tarefa que já falhou uma vez

Manda o prompt mínimo pedindo a entrevista com AskUserQuestion, deixa a spec sair em SPEC.md, salva no repo

Na sessão seguinte, roda /context e confere o que realmente carregou

Aí você vai ver a diferença com os próprios olhos, e não porque um post te contou 😀

Me conta nos comentários: hoje você tá no time do prompt gigante ou já mantém spec no projeto?

até o próximo post!