Como escrever um bom prompt para o Claude Code (e o que muda em relação a conversar com um chat de IA)

Falar com um chat de IA é pedir um texto

Falar com o Claude Code é autorizar alguém a mexer nos seus arquivos

Parece detalhe, mas muda tudo na hora de escrever o pedido

No chat, se a resposta veio ruim, você lê, descarta e pergunta de novo, custo zero

No agente, o pedido vago vira arquivo editado, comando rodado e retrabalho pra desfazer

E não é opinião: a documentação oficial descreve o trabalho do Claude Code em três fases que se misturam, reunir contexto, agir e verificar resultados, com uso de ferramentas em todas elas (buscar arquivos, editar, rodar testes)

Ou seja, tu não está pedindo uma resposta, tu está abrindo um processo

Bora ver como escrever pra esse processo dar certo? 🙂

Prompt de chat x pedido para agente: o que muda na prática

Antes de reescrever qualquer prompt, vale enxergar a diferença lado a lado

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 na última linha, porque é a mais cara

Um pedido sem limite não trava o agente, ele age assim mesmo

Só que agindo no palpite dele

O que preparar antes de escrever o pedido:

Tem coisa que melhora TODO pedido futuro sem você reescrever uma linha

São duas: a memória do projeto e os modos de permissão

CLAUDE.md na raiz do projeto:

O CLAUDE.md é um arquivo markdown na raiz do projeto que o Claude Code lê no início de cada sessão

É ali que moram padrões de código, decisões de arquitetura, bibliotecas preferidas e checklist de revisão

Pra criar, roda o /init, que gera um CLAUDE.md inicial pro projeto

Depois o /memory lista e abre os arquivos de memória (CLAUDE.md, CLAUDE.local.md) pra você refinar

Quer uma regra que é só sua e não deve ir pro repositório? Rodando o /init e escolhendo a opção pessoal, o CLAUDE.local.md entra no .gitignore

Se você quiser ir mais fundo no que vale colocar e o que só polui, tem um guia sobre o que escrever no CLAUDE.md aqui no blog

Pensa nisso como contexto que você não precisa repetir em cada prompt

Os modos de permissão:

Os modos de permissão controlam a frequência com que ele para pra pedir aprovação

Você cicla entre eles com Shift+Tab no CLI (ou pelo seletor de modo no VS Code, no Desktop e no claude.ai)

• Manual: revisa toda ação, é o modo mais conservador
• Accept Edits: auto-aprova edições de arquivo e um conjunto fixo de comandos de filesystem (mkdir, touch, rm, mv, cp, sed) pra caminhos dentro do diretório de trabalho, o resto continua perguntando
• Auto: roda sem os prompts de permissão de rotina, com um modelo classificador separado revisando as ações antes de executarem, bloqueando o que escapa do que foi pedido, mira infraestrutura não reconhecida ou parece dirigido por conteúdo hostil que ele leu
• Plan: lê arquivos, roda comandos de shell pra explorar e escreve um plano, sem editar o código-fonte

Guarda esse último, porque ele é peça central do próximo tópico

Como escrever um pedido executável em 5 passos

A régua aqui é simples: o pedido tem que ser executável e verificável sem você no meio

1. Declare o objetivo e o resultado esperado, não a tarefa genérica

O agente não adivinha o "pronto" que você tem na cabeça

Ele precisa saber qual estado do sistema conta como sucesso

Objetivo: o endpoint POST /login deve devolver 401 quando a senha
estiver errada, em vez de 500
Resultado esperado: teste novo cobrindo o caso e a suíte inteira verde

O erro comum deste passo: escrever "melhore o login", que é objetivo pra humano, não pra agente

2. Aponte os arquivos com @ em vez de descrever onde o código está

A documentação oficial recomenda referenciar arquivos com @ justamente porque ele lê o arquivo antes de responder

Descrever caminho em prosa ("lá na pasta de serviços, naquele arquivo de autenticação") gasta turno de busca e ainda pode achar o arquivo errado

Ajuste @src/auth/login.ts e o teste em @tests/auth/login.test.ts

O erro comum deste passo: apontar a pasta inteira quando você já sabe o arquivo

3. Delimite o escopo: o que pode mudar e o que fica fora

Essa é a peça que mais gente esquece, e a que mais dói

Escopo aberto não deixa o agente parado, deixa ele criativo

Pode mudar: @src/auth/login.ts e @tests/auth/login.test.ts
Não mexer em: schema do banco, rotas fora de /auth, dependências do package.json

O erro comum deste passo: dizer só o que pode mudar e esquecer o "não mexer", que é onde mora o estrago silencioso

4. Dê um critério de pronto que ele mesmo rode

A recomendação oficial é dar ao Claude um check que ele consiga executar: testes, build ou um screenshot pra comparar

Aí o ciclo fecha sozinho: ele faz o trabalho, roda o check, lê o resultado e itera até passar

Sem isso, quem roda o check é você, e o loop de verificação some

Critério de pronto: npm test -- tests/auth passa, e npm run build
não quebra

O erro comum deste passo: dar um critério que só você consegue avaliar ("tem que ficar bonito", "tem que ficar rápido")

5. Peça evidência, não a afirmação de sucesso

"Pronto, implementado e testado!" não é evidência, é resumo

A documentação oficial recomenda pedir a saída do teste, o comando rodado e o que ele retornou, ou um screenshot do resultado

No final, cole a saída do comando de teste e diga exatamente qual
comando você rodou

O erro comum deste passo: aceitar o relatório em prosa e descobrir o problema três pedidos depois

E antes de tudo isso: separe planejar de implementar

A documentação oficial recomenda separar pesquisa e planejamento da implementação pra não resolver o problema errado, pedindo primeiro um plano de implementação detalhado

O modo Plan existe exatamente pra isso: ele lê arquivos, roda comandos de exploração e escreve um plano, sem tocar no código-fonte

Você sai do modo Plan aprovando o plano ou apertando Shift+Tab, e a partir dali ele codifica verificando contra o próprio plano que você aprovou

Quando a tarefa é grande, vale ir além do plano da sessão e escrever a spec antes de implementar, que é o mesmo princípio levado a sério

Antes e depois: 4 pedidos vagos reescritos

Agora a parte prática

Mesma intenção, texto diferente, resultado MUITO diferente

1. Bug reportado sem repro:

Antes:

O login tá dando erro pra alguns usuários, resolve aí

O que isso provoca: ele sai caçando o que pode ser "erro", lê meio projeto e começa a mudar coisa por precaução

Depois:

Objetivo: POST /login com senha errada devolve 500 e deveria devolver 401
Repro: rodar npm test -- tests/auth/login.test.ts, o caso "senha invalida" falha
Pode mudar: @src/auth/login.ts e @tests/auth/login.test.ts
Não mexer em: middleware de sessão e schema do banco
Pronto quando: npm test -- tests/auth passa
Me mostre a saída do teste no final

A peça que mudou o jogo aqui foi o repro: sem ele o agente inventa a própria hipótese

2. Refatoração ampla:

Antes:

Refatora esse código, tá muito bagunçado

O que isso provoca: renomeação em massa, arquivo movido de lugar, e um diff que ninguém consegue revisar

Depois:

Entre em modo Plan e escreva um plano pra extrair a validacao de
formulario de @src/checkout/CheckoutForm.tsx pra um modulo separado
Regra: comportamento identico, nenhuma mudanca de API publica
Nao renomeie nada fora de @src/checkout/
Pronto quando: npm test -- checkout passa e npm run build nao quebra
Nao escreva codigo antes de eu aprovar o plano

A peça que mudou o jogo: a fase de plano antes do código, com "comportamento idêntico" como limite duro

3. Feature nova:

Antes:

Cria uma tela de perfil do usuario

O que isso provoca: ele escolhe stack, escolhe estrutura de pasta, escolhe biblioteca, tudo no gosto dele

Depois:

Objetivo: tela de perfil em /perfil mostrando nome, email e avatar do
usuario logado, com botao de salvar nome
Stack: a mesma ja usada em @src/pages/settings.tsx, sem dependencia nova
Arquivos novos ficam em src/pages/ e src/components/perfil/
Nao mexer em: rotas existentes, layout global
Pronto quando: npm run build passa e o teste novo em
tests/perfil.test.ts cobre salvar nome com sucesso e com nome vazio
Me diga qual comando rodou e cole o retorno

A peça que mudou o jogo: a stack e a estrutura de pastas fechadas por VOCÊ, não pelo agente

4. Ajuste de layout:

Antes:

Deixa o card mais bonito

O que isso provoca: saída genérica de IA, porque "bonito" não é critério, é sensação

Depois:

Objetivo: no card de @src/components/PlanCard.tsx, alinhar o preco a
esquerda, aumentar o espacamento interno e deixar o botao ocupando a
largura total do card
Use os tokens de espacamento ja definidos em @src/styles/tokens.css,
nao invente valores novos
Nao mexer em: cores e tipografia
Pronto quando: voce rodar o projeto, tirar um screenshot do card e
comparar com o estado anterior, descrevendo o que mudou

A peça que mudou o jogo: trocar "bonito" por um check que ele consegue rodar e comparar

Quando o pedido falha: 3 sintomas e como corrigir o texto

Se você já usa o Claude Code, aposto que reconhece pelo menos um destes 👇

Sintoma 1: ele mexeu em mais coisa do que devia

Causa no pedido: escopo aberto

Você disse o que queria e não disse onde aquilo termina

Correção: liste os arquivos que podem mudar e os que ficam fora, com @ nos que importam

E ajuste o modo enquanto isso: o Manual revisa toda ação, e o Accept Edits auto-aprova edições e mkdir, touch, rm, mv, cp e sed dentro do diretório de trabalho, mas continua perguntando no resto

Como prevenir: escreva o "não mexer em" ANTES do "faça", vira hábito rápido

Sintoma 2: ele disse que está pronto e não estava

Causa no pedido: faltou critério verificável

Sem check executável, "pronto" é a opinião dele sobre o próprio trabalho

Correção: peça evidência (saída do teste, comando rodado e retorno, screenshot) em vez de aceitar a afirmação de sucesso

Como prevenir: todo pedido termina com uma linha de critério de pronto, sem exceção

Sintoma 3: ele resolveu o problema errado

Causa no pedido: faltou fase de planejamento, ele foi direto pro código

Correção: separe pesquisa e planejamento da implementação e peça o plano detalhado primeiro, usando o modo Plan, que lê arquivos e explora sem editar o código-fonte

Depois, pra não deixar o autor ser o juiz do próprio trabalho, existe a verificação por segunda opinião: um subagente de verificação ou um modelo novo tentando REFUTAR o resultado

Quem fez não deveria ser quem aprova, isso vale pra IA como vale pra gente

Como prevenir: tarefa nova começa com /clear, que reseta a conversa pra um contexto vazio e mantém a memória do projeto

E fica tranquilo que a conversa anterior continua em disco e pode ser retomada pelo session ID, você não perdeu nada

O que o escopo aberto custou na prática

Essa parte não é teoria, é sessão gravada

No vídeo abaixo eu testo outro agente de código (não é o Claude Code), e a lição sobre PEDIDO é a mesma, porque o problema não é o modelo, é o texto que a gente escreve

No primeiro projeto eu pedi uma landing page com requisitos explícitos: arquivos separados, sem dependências externas, hero com headline, subheadline e botão de CTA, seção de features com quatro cards, seção "como funciona" e tabela de planos

Antes de pedir, eu já tinha criado a estrutura de pastas na mão em vez de deixar o agente decidir onde colocar cada coisa

O começo dela, já com um HTML feito, consumiu 2% da cota do modelo mais rápido

Aí veio o retrabalho: foram 2 tentativas de retomar com aquele modelo, as duas caindo por conexão, até eu trocar de modelo

Quando terminei a mesma landing page com o outro modelo, a cota fechou em 94%

Uma landing page 😅

E olha o veredito honesto: o visual saiu com aquela cara padrão de IA, e a culpa é do meu pedido, porque eu não fui específico em nada de design

No segundo dos 2 projetos da sessão eu mudei o jeito de pedir

Comecei uma conversa nova em vez de continuar no mesmo chat, e escrevi um pedido bem mais longo pra um mini blog full stack: projeto inteiro funcionando de uma vez, estrutura de pastas definida, arquivos bem separados (não tudo em um arquivo só), stack fechada por mim, descrição do banco, do backend e do frontend, e um arquivo final explicando como rodar o backend e abrir o frontend

Escolhi de propósito uma stack simples no frontend (HTML, CSS e JS puro) pra facilitar o trabalho do modelo, e tentei em one shot só pra ver se o pedido aguentava

O agente devolveu uma lista de progresso com tudo que tinha que fazer antes de sair executando

Depois eu abri o projeto no VS Code e testei na mão: criei conta, a autenticação funcionou, escrevi e publiquei um post, vi ele na home e comentei, com os dados persistindo

Só que ele parou na última etapa, com 29% de cota diária restante, e eu tive que concluir manualmente

A leitura que eu tiro disso é direta: o custo aparece ANTES da qualidade

Pedido sem limite e sem critério de pronto não entrega errado logo de cara, ele entrega caro primeiro, e errado depois

Na tela você acompanha os dois pedidos do começo ao fim, o momento em que a cota derrete e o teste manual do projeto full stack

Conclusão

A régua de um bom prompt para Claude Code cabe em quatro peças

Objetivo (qual estado do sistema conta como sucesso), escopo (o que pode e o que não pode mudar), critério de pronto que ele mesmo rode e evidência do resultado no final

O resto é consequência: apontar arquivo com @ em vez de descrever caminho, e separar planejar de implementar pra não resolver o problema errado

Próximo passo concreto, e é rapidinho: roda o /init no seu projeto pra criar o CLAUDE.md, e escreve o próximo pedido dentro do modo Plan

Lê o plano, aprova, e só então deixa ele codificar

Faz o teste no seu próximo bug e me conta se o retrabalho não caiu 😀

até o próximo post!