Decorei os comandos do Claude Code e travei: como dar o primeiro passo com segurança

Numa sexta à noite, recebi uma mensagem de um colega mais novo no Slack: “Cara, eu decorei todos os comandos do Claude Code, mas não faço ideia do que digitar em seguida. Travei.” Ele sabe de cor o /init, o /clear, o claude -p. Mesmo assim, quando abre o próprio repositório, os dedos congelam.

E olha, isso não é falta de capacidade. A tabela de comandos é só uma lista com “o nome das ferramentas”. Ela não diz o que pedir primeiro, até onde delegar e como conferir o resultado. Por isso tem gente que, quanto mais decora, menos consegue agir.

Este artigo é sobre exatamente isso: como dar o menor primeiro passo possível para sair desse “decorei tudo, mas travei”.

Pontos principais

• Você trava mesmo sabendo os comandos porque faltam quatro decisões: o que liberar, quais arquivos não tocar, como voltar atrás e como conferir.
• O primeiro resultado pode ser minúsculo: “ajustar só um parágrafo” ou “explicar o sentido de um teste que falha”.
• Antes de delegar, peça ao Claude para “devolver só o plano, sem editar”. Isso derruba os acidentes drasticamente.
• Para conferir, defina antes um comando objetivo como git diff, em vez de confiar no olho humano.
• Quando pegar confiança, promova ao automático só as operações que você já comprovou serem seguras.

Por que você trava mesmo decorando a tabela

A lista de comandos é como uma “tabela de placas de trânsito” num mapa. Você pode saber o nome de todas as placas, mas, se não definir o destino e onde virar, o carro não sai do lugar.

Quem trava não está sem conhecimento. Está sem o hábito de colocar estes quatro pontos em palavras:

• Quais arquivos deixar o Claude ler e quais ele não pode tocar.
• O quão pequena cortar a primeira mudança.
• Qual é a condição que define “deu certo” (o que olhar para saber que foi sucesso).
• Como voltar ao estado anterior quando der errado.

Eu também comecei mandando “deixa esse projeto bonito aí” e travei na frente de um diff com 30 arquivos alterados. Diff que não dá para ler não dá para conferir. E mudança que você não consegue conferir é assustadora demais para aceitar. Por isso o certo, no início, é começar de um jeito quase ridículo de tão pequeno.

O primeiro passo pode ser bem pequeno

Quando ouvimos “resultado”, logo imaginamos uma grande funcionalidade nova. Mas, no começo, este nível já basta:

• Deixar a introdução do README mais legível em apenas 3 linhas.
• Acrescentar uma única frase ao aviso no rodapé de um artigo.
• Fazer o Claude explicar o sentido de um teste que está falhando, “sem corrigir”.

O terceiro é o que mais recomendo. Como não muda uma linha de código sequer, não tem como quebrar nada. E mesmo assim você sente, de verdade, aquele primeiro gostinho de “fiz o Claude Code ler o meu repositório e recebi uma resposta”. Quem está travado deveria começar movendo os dedos justamente por aqui.

O que delegar e o que você decide

Separe desde o início, de forma clara, o que entregar ao Claude Code e qual decisão você mantém na mão. Se rodar com tudo nebuloso, ele costuma avançar até onde deveria ser decisão sua.

Situação	Delegar ao Claude Code	Você decide
Definir o escopo	Buscar e sugerir arquivos candidatos	A decisão final do que pode tocar
Edição	Rascunho do texto e do código	Se vai aceitar ou não
Conferência	Rodar testes e resumir o diff	Se pode publicar
Operações perigosas	Sugerir o procedimento, até aí	Executar exclusão, deploy em produção, cobrança

O ponto está na coluna da direita. Exclusão, deploy em produção, operações que mexem com dinheiro e ações difíceis de desfazer, como git push --force, ficam todas fixadas em “quem aperta é você”, no início. Só o que você mesmo comprovou ser seguro vai depois para a coluna da esquerda. Manter essa ordem já reduz muito o número de noites em que você sua frio na madrugada.

Peça primeiro “só o plano”

O truque é não mandar editar de cara. No primeiro pedido, não deixe mexer em nada: faça apenas descrever o plano. Você pode colar o prompt abaixo do jeito que está.

Vou te pedir uma única mudança pequena. Ainda NÃO edite nada.
Primeiro, devolva em tópicos os quatro pontos a seguir:

1. Arquivo que será alterado (apenas um)
2. Arquivos que não serão tocados (nunca toque em .env, autenticação ou cobrança)
3. O que será mudado (não altere o comportamento, ajuste só o texto)
4. O comando que eu vou usar para conferir depois (ex.: git diff)

Só comece a editar depois que eu der o OK a esses quatro pontos.

Olhe os quatro pontos que voltarem. Se o arquivo a alterar estiver reduzido a um só e houver até o comando de conferência, a granularidade do pedido está certa. Por outro lado, se a resposta for algo como “vou revisar o repositório inteiro”, é sinal de que o pedido ainda está amplo demais. Estreite o escopo e peça de novo no mesmo formato.

Se sentir dificuldade em escrever o pedido, o design de prompts do Claude Code e como escrever o CLAUDE.md servem de base. Entregar as regras do projeto antes eleva a qualidade do plano em um nível.

Checklist do primeiro passo, copie e cole

Escrever os quatro pontos da cabeça em um arquivo toda vez é chato. Por isso deixo aqui um script pequeno que, só de responder, gera o seu “bilhete do primeiro passo”. Funciona se você tiver Node.js.

// first-win.mjs — gera, em 1 minuto, o bilhete do seu primeiro passo
// uso: node first-win.mjs

const plan = {
  objetivo: "Concluir com segurança uma pequena mudança no Claude Code",
  arquivosAlterados: ["README.md"],           // reduza a um só
  arquivosNaoTocados: [".env", "autenticação", "cobrança", "DB de produção"],
  primeiroComando: "git status --short",       // confere o estado atual
  oQueMudar: "Deixar a introdução mais legível em 3 linhas. Não muda o comportamento",
  comoConferir: "git diff -- README.md",       // o diff cabe na sua leitura?
  comoReverter: "git checkout -- README.md",   // se der ruim, refaça na hora
};

// Verificação: o arquivo a alterar está reduzido a um só?
if (plan.arquivosAlterados.length !== 1) {
  console.error("⚠ No início, reduza os arquivos alterados a apenas um");
  process.exit(1);
}

console.log("=== Bilhete do primeiro passo ===");
for (const [chave, valor] of Object.entries(plan)) {
  const texto = Array.isArray(valor) ? valor.join(", ") : valor;
  console.log(`${chave}: ${texto}`);
}
console.log("\nCole este bilhete no Claude Code e peça 'devolva o plano antes de editar'");

Executar é só isso:

node first-win.mjs

Cole o bilhete que sair direto no Claude Code e use junto com o prompt “devolva só o plano” lá de cima. Como o script trava já na primeira linha quando os arquivos a alterar passam de um, ele também serve de freio quando bate aquela vontade de fazer demais.

Três usos que funcionaram de verdade

Aqui vão três exemplos que eu e gente ao meu redor escolhemos como “primeiro passo” e que realmente nos fizeram avançar.

1. Ajustar a introdução do README. Para quem chegou procurando os comandos, deixe só as 3 primeiras linhas mais simples. A conferência se resolve só com git diff, então você sente no menor tempo possível que consegue ler o diff. É aqui que vem a confiança.

2. Acrescentar uma frase ao aviso no rodapé. Em um trecho com explicação rasa, adicione uma única frase e confira, abrindo a URL pública, se o link de destino está vivo. Como é mudança só de texto, não há risco de quebrar código.

3. Fazer explicar o sentido de um teste que falha. Aqui não deixe corrigir. Peça só três coisas: “o sentido do erro”, “os arquivos que parecem relacionados” e “o próximo lugar que a pessoa deve olhar”. É um treino para levantar a hipótese da causa sem tocar uma linha de código.

O que esses três têm em comum é que a conferência termina em um comando e, se falhar, dá para reverter em um segundo. Se você não é da área técnica, vale ler junto o uso do Claude Code para quem não é engenheiro; fica mais fácil escolher um primeiro passo na parte de texto.

Armadilhas comuns e como corrigir

Armadilha 1: pedir “melhore este repositório” logo depois de ver a tabela. O escopo fica largo demais e o diff que volta deixa de ser legível. A correção é simples: estreite até “1 arquivo, 1 parágrafo”. Quanto mais estreito, mais garantido fica o primeiro resultado.

Armadilha 2: deixar a forma de conferir para depois. Se você roda sem decidir o que olhar para saber que deu certo, mesmo um resultado convincente não diz se pode ser aceito. Escreva no pedido, desde o começo, o comando de conferência, como o git diff.

Armadilha 3: delegar uma operação perigosa de cara. Automatizar exclusão de arquivos ou deploy em produção desde o início leva a acidentes irreversíveis. No começo, fixe tudo em “quem aperta é você” e promova ao automático só o que você comprovou ser seguro.

Perguntas frequentes

P. Quantos comandos preciso decorar antes de começar? R. Três já bastam: /init, /clear e o git diff para conferir as mudanças. O resto você pesquisa na hora em que o caso aparecer. Mexer aos poucos antes de decorar acaba fixando o aprendizado mais rápido.

P. Qual tarefa é a mais indicada para o primeiro passo? R. Fazer o Claude “apenas explicar” o sentido de um teste que falha. Como não muda código, não há como quebrar, e mesmo assim você sente o gosto de fazê-lo ler o repositório. O fluxo básico também está resumido no guia de introdução.

P. Pedi o plano, mas ele já começa a editar. R. Coloque “ainda NÃO edite nada” logo no início do prompt e, no fim, acrescente “aguarde o meu OK”. Se mesmo assim ele avançar, costuma ser porque o escopo da mudança está nebuloso; limite, citando pelo nome, a um único arquivo a alterar.

P. Conferir com o olho humano não basta? R. Em dia corrido, sempre desanda. Decida antes uma conferência objetiva, como contagem de caracteres, diff ou resultado dos testes (passou ou falhou), e os deslizes diminuem. O truque é concentrar o julgamento humano apenas em “aceitar ou não”.

P. Quando pegar prática, qual é o próximo passo? R. Estenda o mesmo “bilhete do primeiro passo” a uma tarefa um pouco maior. Mesmo que os comandos de conferência aumentem, não mude o princípio de que quem segura a operação perigosa é a pessoa. Para acelerar o trabalho, vale ver as dicas para ganhar produtividade.

O que eu confirmei na prática

Com o colega lá do começo, fiz primeiro o passo de “deixar explicar só o sentido de um teste que falha”. Sem tocar no código. O que voltou foi o nome do arquivo com a causa e o lugar da função para olhar em seguida. Ele disse “isso eu consigo” e, no mesmo dia, avançou até o ajuste de 3 linhas no README.

Eu mesmo, depois que parei de delegar tudo e passei a encaixar o “devolva só o plano”, praticamente zerei o tempo travado na frente de um diff ilegível. Só peço o que cabe na conferência com git diff e a operação perigosa quem aperta sou eu. Manter essas duas coisas torna o primeiro passo surpreendentemente leve de dar. Você não precisa decorar todos os comandos. Mexa pequeno e confirme o quanto dá para reverter. Começar daí já é o suficiente.

Quem quer avançar um nível no aprendizado pode ver a lista de materiais; quem quer conversar sobre como levar isso ao trabalho da empresa, dê uma olhada em treinamento e consultoria. Para o comportamento detalhado dos comandos, a documentação oficial é a fonte primária mais confiável.