Primeiros 30 minutos no Claude Code: ler, explicar e commitar sem quebrar nada

O primeiro contato com o Claude Code trava por um motivo simples: medo de autorizar uma mudança errada no projeto real. Você abre o terminal, pensa em pedir algo e congela na dúvida sobre o que ele vai alterar. Este roteiro resolve isso com uma sessão curta e protegida.

Você vai treinar em branch separada, ler antes de editar, fazer uma mudança mínima, revisar o diff com teste e fechar com commit. Se você ainda não instalou ou não entrou com a conta certa, comece pelo mapa geral em Claude Code do zero. O ciclo ler, explicar, mudar, revisar e commitar segue o roteiro publicado em 08/abr/2026 no guia de primeiros passos e o loop prático publicado em 27/abr/2026 no guia completo para começar.

Nada de edição antes de confirmar o git e abrir uma branch só para treino. A branch de prática isola cada sugestão do seu trabalho real e deixa o diff como prova do que mudou. Esse cuidado aparece como base do roteiro de 08/abr/2026 no guia de primeiros passos e do loop de 27/abr/2026 no guia completo para começar.

Entre na pasta do projeto antes de abrir o agente. Abrir no lugar certo limita o alcance dos comandos e evita que uma instrução vaga atinja arquivos fora do escopo. Se você ainda está na fase de instalação, confira o passo a passo em como instalar no Windows Mac e Linux e volte para cá com claude --version e claude doctor respondendo.

Rode estes dois comandos para preparar o treino:

git status
git checkout -b pratica-30min

O primeiro mostra se há mudanças pendentes que você deve guardar antes de treinar. O segundo cria a branch pratica-30min e já muda para ela. A regra é direta: se o git status mostra sujeira, resolva ou guarde antes de pedir qualquer edição.

Pedido bom tem três partes curtas: onde, o que e como conferir. Onde indica a pasta ou o arquivo. O que descreve a mudança em uma frase. Como conferir diz qual leitura ou teste prova que funcionou. Esse formato reduz idas e voltas porque entrega o contexto que o agente usaria para perguntar de volta.

Use esta estrutura em todos os blocos abaixo. Ela traduz a recomendação de ler e explicar antes de editar do guia de primeiros passos, de 08/abr/2026, para um hábito repetível.

Copie estes dois modelos de leitura para o início:

Liste a estrutura desta pasta sem alterar nada.

Explique o que faz a função getUserById neste arquivo, sem alterar nada.

O detalhe que protege você está no fim de cada frase: sem alterar nada. Essa instrução explícita mantém o agente em modo de leitura e pede apenas explicação. Quando a explicação cita o arquivo e a função certos, o contexto está pronto para uma mudança pequena.

Para mudança, use este modelo:

Neste arquivo, renomeie a variável total para totalUsers e mostre o diff antes de finalizar.

Ele tem onde (neste arquivo), o que (renomeie a variável) e como conferir (mostre o diff). Pedidos assim geram diffs curtos, que são mais fáceis de revisar linha por linha.

A divisão abaixo soma 30 minutos exatos e termina com commit feito. Ela organiza as tarefas curtas do roteiro de 08/abr/2026 no guia de primeiros passos e o loop com primeiro commit do guia de 27/abr/2026 no guia completo para começar. Use os tempos como guia de ritmo, não como cobrança.

Bloco 1, 5 minutos: ler a estrutura sem alterar nada

Leitura primeiro cria o mapa que evita pedidos no escuro. Peça a lista de pastas e a função de um arquivo central, sempre com a trava sem alterar nada. O objetivo do bloco é responder em voz alta: onde estão as entradas do projeto e qual arquivo cuida de qual parte.

Se a resposta cita arquivos que não existem, pare e corrija o caminho antes de seguir. Esse erro simples de contexto responde pela maioria das sugestões fora do lugar. Cinco minutos bem usados aqui economizam quinze na revisão.

Bloco 2, 5 minutos: pedir explicação antes de qualquer edição

Explicação confirma se o agente entendeu o código certo. Peça o papel da função getUserById, quais entradas ela recebe e o que retorna, ainda sem alterar nada. A resposta deve citar nomes reais de arquivos e variáveis do seu projeto.

Só avance quando você conseguir repetir a explicação com suas palavras. Se não consegue explicar, não autorize mudança. Essa pausa curta é o ponto central do roteiro de 08/abr/2026 no guia de primeiros passos: entender antes de alterar.

Bloco 3, 7 minutos: fazer uma mudança minúscula e visível

Mudança pequena gera diff curto e teste rápido. Escolha uma destas duas tarefas para o primeiro treino: renomear uma variável confusa ou criar um teste unitário simples para getUserById. As duas aparecem como exemplos de primeira tarefa segura nos roteiros de abril de 2026.

Para renomear, use o modelo da seção anterior e confira se só o nome mudou. Para teste, use este prompt curto:

Crie um teste unitário simples para getUserById com um caso válido, sem alterar a função.

Se o agente propuser alterar três arquivos de uma vez, peça para refazer em um só. A regra do treino é uma mudança por vez, com diff legível na tela.

Bloco 4, 6 minutos: revisar o diff e rodar o teste

Revisão é onde o treino vira confiança. Rode o diff e leia cada linha adicionada ou removida como se fosse você quem digitou. Pergunte para cada trecho: eu entendo o que esta linha faz e por que ela existe agora.

git diff
npm test

O git diff mostra o que mudou na branch de prática. O npm test roda a suíte do projeto e prova que a mudança não quebrou o básico. Se o teste falha, volte o arquivo e peça de novo em parte menor, ainda na mesma branch. Nenhum erro aqui custa caro porque nada saiu da branch de treino.

Bloco 5, 7 minutos: fazer o primeiro commit com mensagem clara

Commit fecha o ciclo e cria histórico que você pode desfazer. Confira o status, adicione só os arquivos do treino e escreva uma mensagem que diz o que mudou e por quê. Esse fechamento com commit simples segue o loop de 27/abr/2026 no guia completo para começar.

git status
git add src/users.js test/users.test.js
git commit -m "Renomeia total para totalUsers para leitura mais clara"

Troque os caminhos pelos arquivos reais do seu treino e mantenha a mensagem no mesmo formato: verbo no início, o que mudou e o motivo curto. Nos minutos finais, anote em duas linhas o que funcionou no pedido e o que você vai pedir diferente na próxima vez.

O modo one-shot executa um pedido único e termina, sem abrir a conversa interativa. Ele serve para perguntas fechadas com resposta curta, como resumir histórico ou explicar um erro com contexto pronto. Esse uso aparece no guia de 27/abr/2026 no guia completo para começar.

Teste agora na branch de prática com este exemplo literal:

claude -p "Resuma os últimos 5 commits deste repositório em tópicos curtos"

Use a conversa normal quando a tarefa pede mudança em arquivos, porque ela mantém contexto entre perguntas, propostas e ajustes. Use claude -p quando você precisa só de leitura ou resumo e já tem tudo para conferir na tela. Essa separação evita abrir uma sessão longa para uma dúvida que cabe em uma linha.

Para ajuda e retomada, guarde três comandos base descritos no guia oficial de início rápido. O /help mostra a ajuda dentro da sessão. As flags -c e -r retomam ou continuam uma conversa anterior sem repetir todo o contexto. Se a sessão atual travou, prefira recomeçar limpo a arrastar confusão.

Os três erros abaixo se repetem porque parecem atalhos. Cada um tem saída simples e volta para a branch de prática sem perda. A lista reflete os 3 tropeços descritos no guia de 27/abr/2026 no guia completo para começar.

1. Autorizar tudo para andar mais rápido

Liberar todos os comandos remove a pausa que protege arquivos sensíveis e comandos destrutivos. No treino, mantenha a aprovação ligada e responda caso a caso. Autorize sem medo apenas leitura e explicação, e leia com atenção cada pedido de escrita ou execução.

Se você já liberou tudo, volte ao modo cuidadoso e revise a lista de permissões antes do próximo pedido. O detalhe completo dessa trava fica no próximo guia do cluster: CLAUDE.md e permissões seguras.

2. Deixar a conversa pesada sem limpar o contexto

Conversa longa acumula tentativas antigas e o agente começa a misturar pedidos. Os sinais são respostas vagas, arquivos errados e repetição do que já foi corrigido. A correção usa dois comandos base citados no guia oficial de início rápido.

Use /compact para resumir a conversa quando ela ainda tem pontos úteis. Use /clear para limpar tudo e recomeçar quando o contexto já se perdeu. Depois de limpar, repita o pedido curto com onde, o que e como conferir, ainda na branch de prática.

3. Começar sem a primeira linha útil no CLAUDE.md

O CLAUDE.md guarda instruções do projeto para o agente, e a primeira informação útil é como validar o trabalho. Sem o comando de teste ali, cada resposta sugere uma forma diferente de conferir. Com ele, o agente já propõe npm test ou o comando certo do seu projeto.

Para este treino basta uma linha com o comando de teste e uma linha com o que nunca fazer sem permissão. Exemplos de estrutura completa e de permissões ficam no guia seguinte: CLAUDE.md e permissões seguras.

Preciso saber git para os primeiros 30 minutos?

Precisa do básico: status para ver pendências, checkout -b para criar a branch de prática, diff para revisar e commit para registrar. Esse conjunto mínimo aparece como condição do ciclo nos roteiros de 08/abr/2026 no guia de primeiros passos e de 27/abr/2026 no guia completo para começar. Sem ele não há como comparar, voltar ou provar o que mudou.

Qual mudança devo fazer primeiro?

Faça a menor mudança visível: renomear uma variável confusa ou criar um teste unitário simples para getUserById. As duas geram diff curto e teste rápido, o que facilita a revisão do bloco 4. Evite criar funcionalidade nova no primeiro treino, porque ela gera diff longo e difícil de conferir.

Quando devo usar claude -p em vez da conversa normal?

Use claude -p para perguntas fechadas com resposta curta, como o exemplo de resumir os últimos 5 commits com git log como base. Esse padrão one-shot está descrito no guia de 27/abr/2026 no guia completo para começar. Fique na conversa normal para edições, porque ela guarda contexto entre proposta, ajuste e revisão.

O que faço se a conversa ficar confusa?

Use /compact para resumir e manter o fio, ou /clear para limpar e recomeçar do zero, conforme a base de comandos no guia oficial de início rápido. Depois repita o pedido curto com onde, o que e como conferir, ainda na branch pratica-30min. Se o diff já está grande e confuso, descarte a branch e abra outra para repetir o treino.

Você fechou o ciclo completo uma vez: leu, pediu explicação, mudou pouco, revisou o diff com teste e commitou com mensagem clara. Repita o mesmo roteiro com uma tarefa um pouco maior, ainda em branch de treino. O objetivo da segunda rodada é pedir melhor, não produzir mais.

Quando o fluxo de 30 minutos ficar confortável, trave a segurança antes de acelerar. O próximo passo é deixar o CLAUDE.md curto e as permissões no modo cuidadoso: CLAUDE.md e permissões seguras.

• guia de primeiros passos
• guia completo para começar
• guia oficial de início rápido