Claude Code do zero: da instalação ao primeiro commit em 30 minutos

Digite claude no terminal e aperte Enter.

Dá para perceber que alguma coisa começa a rodar só com isso. Mas quando eu fiz isso pela primeira vez, o que apareceu na tela foi um “faça login”, e eu travei ali por uns cinco minutos. Login onde? Vai custar dinheiro? Ele vai ler todo o meu código? No fim daquele dia, fechei tudo sem ter mudado uma única linha.

Hoje eu entendo que a primeira barreira não era a instalação nem o inglês — era “o que eu peço depois que isso abre”. Então, neste artigo, vamos atravessar essa parte pelo caminho mais curto. Instalação → login no navegador → primeiro prompt → primeiro commit, tudo isso em 30 minutos. E os três pontos onde eu tropecei no meio (autorizar permissões, a conversa ficando pesada e a primeira linha do CLAUDE.md) eu já deixo aqui antes, para você não cair neles.

A intenção de busca é simples: “como começar com Claude Code”, “como usar para iniciantes”. Vou responder exatamente isso, sem rodeios.

Pontos principais

• A instalação é um comando do instalador oficial. No macOS/Linux é curl ... | bash; no Windows, irm ... | iex. Quem prefere instalar via Node.js usa npm i -g @anthropic-ai/claude-code (Node 18 ou superior).
• A autenticação é pelo navegador. Ao iniciar o claude, você é levado ao login. É preciso uma assinatura Claude Pro/Max ou uma conta do Console (o plano gratuito do Claude.ai não serve).
• Nos primeiros 30 minutos, não deixe ele editar nada. Acostume-se na ordem: fazer ler → fazer explicar → revisar apenas um arquivo.
• A meta é chegar até o primeiro commit. Crie já no primeiro dia o hábito de conferir o diff com seus próprios olhos antes de commitar.
• As três minas que iniciantes costumam pisar: não autorizar tudo de uma vez / comprimir a conversa quando ela ficar pesada / escrever uma linha no CLAUDE.md dizendo como rodar os testes.

Vamos por partes. Só vou colocar comandos que funcionam copiando e colando.

Primeiro, a visão geral: o mapa dos 30 minutos

Antes de entrar nos passos detalhados, deixa eu te mostrar o mapa até a meta. Assim fica mais difícil se perder.

Tempo	O que fazer	Objetivo
0–5 min	Instalar + login no navegador	Deixar o claude pronto para iniciar
5–10 min	Criar uma branch de prática	Montar uma base à qual você consegue voltar se errar
10–20 min	Fazer ler e explicar	Entender “com base em quê ele responde”
20–25 min	Pedir uma única mudança pequena	Vivenciar o fluxo editar → conferir o diff
25–30 min	Primeiro commit	Criar o hábito de confirmar com seu próprio julgamento

O ponto-chave é não fazer uma refatoração grande no primeiro dia. Pedidos do tipo “deixa esse projeto bonito” podem esperar até você pegar prática. No começo, pequeno e dentro de um escopo ao qual você consegue voltar.

Passo 1: Instalar (0–3 min)

Até pouco tempo atrás, “instalar pelo npm” era o padrão, mas a primeira opção oficial hoje é o instalador dedicado. Ele entra sem você se preocupar se tem ou não Node.js.

No macOS / Linux / WSL, é este aqui.

curl -fsSL https://claude.ai/install.sh | bash

No PowerShell do Windows, é este.

irm https://claude.ai/install.ps1 | iex

Quem prefere gerenciar via Node.js continua instalando pelo npm, como sempre. É preciso Node.js 18 ou superior.

npm install -g @anthropic-ai/claude-code

Confirme se instalou. Se aparecer o número da versão, está tudo certo.

claude --version

Se aparecer command not found aqui, o claude doctor te diz qual é a causa.

claude doctor

Só um aviso. Mesmo que apareça um erro de permissão, não saia rodando sudo npm install -g por reflexo. A própria documentação oficial diz para evitar isso, porque “leva a problemas de permissão e riscos de segurança”. Sem pânico: seguir as instruções do claude doctor é mais rápido.

Passo 2: Fazer login no navegador (3–5 min)

Instalado, é só iniciar.

claude

Na primeira vez, ele te leva automaticamente à tela de login. O navegador abre e você só precisa entrar seguindo as instruções da tela. Uma vez feito isso, as credenciais ficam salvas e ele não pergunta de novo.

Aqui o iniciante costuma travar em “afinal, qual conta?”. Organizando, é assim.

• Assinatura Claude Pro / Max / Team / Enterprise … se você está começando por conta própria, é a forma mais tranquila (recomendado).
• Anthropic Console (API, créditos pré-pagos) … para quem quer operar com chave de API ou centralizar o controle de custos.
• Amazon Bedrock / Google Vertex AI / Microsoft Foundry … quando a política de nuvem da empresa já está definida.

Um ponto de atenção. No plano gratuito do Claude.ai não dá para usar o Claude Code. Muita gente sofre com “não consigo logar” sem saber disso, então deixo registrado de cara.

Se você quiser trocar de conta, é só digitar /login em uma sessão já aberta para reautenticar.

Passo 3: Criar um lugar ao qual você consegue voltar se errar (5–10 min)

Esta parte é discreta, mas importante. Não saia brincando direto no repositório de produção. Abra um repositório pequeno de prática ou um projeto pessoal que não faz mal se quebrar.

Se for testar no código do trabalho, sempre crie uma branch de trabalho.

git status
git switch -c try-claude-code

A razão de olhar o git status primeiro é não arrastar junto alterações não commitadas. Se você usar sem saber direito qual era o estado anterior, depois fica impossível distinguir “esse diff foi a IA? ou foi eu?”. Isso, eu mesmo fiz no primeiro dia, de verdade.

Inicie o Claude Code nessa pasta.

cd /path/to/your/project
claude

Ao iniciar, aparece no topo a versão, o modelo em uso e o diretório de trabalho. Com /help você vê a lista de comandos.

Passo 4: Primeiro, só “faça ele ler” (10–20 min)

A partir daqui é pra valer. Mas ainda não vamos deixar ele editar. No começo, faça ele ler e explicar. Só isso já te dá a sensação de “com base em quê o Claude Code está respondendo”.

No modo interativo, basta falar em português natural. Não precisa de sintaxe complicada.

Leia apenas o README.md e o package.json e me explique, em português, qual é o objetivo deste projeto e como iniciá-lo

O ponto é restringir o escopo com o “apenas”. Se, ainda como iniciante, você deixar ele começar a ler um monte de arquivos, fica impossível rastrear de onde veio a resposta. Isso se liga diretamente ao problema de “a conversa ficar pesada” que vou explicar mais adiante.

Quando pegar prática, peça uma revisão de um único arquivo.

Leia apenas o src/utils/date.ts e aponte, em no máximo 3 itens, pontos que podem virar bug. Ainda não edite nada

Acrescentar “ainda não edite nada” evita que revisão e implementação se misturem. Primeiro o treino de ler as sugestões; mexer no código vem depois.

A propósito, quando você quer só rodar rapidinho uma investigação ou uma tarefa de rotina, sem entrar no modo interativo, o one-shot é prático. Com o -p, ele devolve o resultado e encerra.

claude -p "Execute git log --oneline -10 e resuma em português o conteúdo das mudanças"

Minha forma de dividir é simples: implementação que exige tentativa e erro no modo interativo; pesquisa e resumo no one-shot. No começo, basta decorar esses dois.

Passo 5: A primeira mudança pequena (20–25 min)

Depois do treino de leitura, finalmente deixamos ele editar. No começo, na unidade “1 arquivo, 1 função”.

No modo interativo, peça assim.

Adicione um teste unitário para a função getUserById em src/api/users.ts. Siga o estilo dos testes que já existem

Aqui o Claude Code sempre vai perguntar “posso aplicar essa mudança?”. Ele não reescreve arquivos por conta própria. Olhe o diff proposto e, se concordar, aprove. Esse é o mecanismo de segurança padrão.

A primeira mina está aqui. Achando chato apertar Enter a cada confirmação, eu logo passei para o modo “autoriza tudo”. Resultado: até arquivos que eu não tinha pedido foram “organizados de quebra”, e eu fiquei branco. A lição: no começo, aprovar um por um acaba sendo o mais rápido. Quando quiser ajustar as permissões com mais cuidado, siga para o artigo dedicado mais abaixo.

Depois de aceitar a mudança, sempre confira o diff com seus próprios olhos.

git diff
npm test

“Parece que funcionou” e “ficou só com o diff que eu queria” são coisas diferentes. Trate diff e teste como um par.

Passo 6: O primeiro commit (25–30 min)

Você conferiu o diff e os testes passaram. Chegando até aqui, a meta está logo ali.

O commit também dá para pedir em linguagem natural.

Confira o conteúdo das mudanças e faça o commit com uma mensagem clara

O Claude Code lê o git diff, pensa na mensagem e, antes de commitar, pede confirmação mais uma vez. Claro, você também pode digitar à mão.

git add src/api/users.ts
git commit -m "test: adiciona teste unitário de getUserById"

Com isso, você completou uma volta do “instalar → logar → fazer ler → mudar algo pequeno → conferir o diff e commitar”. Em 30 minutos, você rodou com as próprias mãos o loop mínimo do Claude Code. No primeiro dia, isso já basta. Pode fechar de cabeça erguida.

Funciona copiando e colando: um script que junta os 30 minutos num só

Como é chato lembrar dos comandos toda vez, eu mantenho um script de shell que “começa uma sessão de prática com segurança”. Ele cria a branch e já dispara o pedido de leitura, de uma vez. Não precisa de Node.js, roda só com bash.

#!/usr/bin/env bash
# start-claude-practice.sh — começa a praticar Claude Code com segurança
set -euo pipefail

# 1) Verificar se não sobraram alterações não commitadas (evita arrastá-las junto)
if [ -n "$(git status --porcelain)" ]; then
  echo "⚠ Há alterações não commitadas. Faça commit ou stash antes."
  git status --short
  exit 1
fi

# 2) Criar a branch de prática (com data; se já existir, só troca para ela)
BRANCH="try-claude-$(date +%Y%m%d)"
git switch -c "$BRANCH" 2>/dev/null || git switch "$BRANCH"
echo "✅ Trabalhando na branch $BRANCH"

# 3) Primeiro, executar como one-shot um pedido só de "leitura"
claude -p "Se houver README, leia o README; se não, leia os arquivos principais
e explique em português, em 3 linhas, o objetivo deste projeto, como iniciá-lo
e qual arquivo ler em seguida. Não edite absolutamente nada."

O uso é só isto.

chmod +x start-claude-practice.sh
./start-claude-practice.sh

Ao executar, se houver alterações não commitadas ele para; se não houver, cria a branch de prática e mostra um resumo do projeto. É o “evitar arrastar alterações junto”, o “criar um lugar ao qual voltar” e o “primeiro fazer ler”, tudo em um único script. Eu queria ter entregado isso para mim mesmo no primeiro dia.

As três coisas em que eu tropecei no começo

Daqui em diante são as coisas que dificilmente entram num passo a passo, mas que doem mais quando você cai nelas logo no primeiro dia.

1. Autorizar tudo desde o início

Como já escrevi, achar a confirmação chata e deixar “tudo OK” causa acidente. No começo, o seguro é usar com escrita e commit pedindo confirmação a cada vez, e delete e force push proibidos. Você consegue definir isso no .claude/settings.json, assim.

{
  "permissions": {
    "allow": ["Read(**)", "Grep(**)", "Bash(npm test*)", "Bash(git status*)", "Bash(git diff*)"],
    "ask": ["Write(**)", "Edit(**)", "Bash(git commit*)", "Bash(git push*)"],
    "deny": ["Bash(rm -rf*)", "Bash(git push --force*)"]
  }
}

“Leitura e teste automáticos, escrita e commit com confirmação, delete perigoso proibido.” Só com esse esquema de três níveis você evita quase todos os acidentes. As operações que você passou a conhecer e considerar seguras, promova depois para o allow. Os detalhes do desenho eu reuni no guia de configuração de permissões do Claude Code; se for ajustar a sério, vá por ali.

2. A conversa fica pesada (pressão de contexto)

Conforme você usa, a partir de um certo ponto fica tudo lento de repente. Isso não é defeito: é sinal de que a conversa ficou longa e o “contexto” que o Claude Code carrega inflou demais. É como a bancada da cozinha enquanto você cozinha, que vai ficando coberta de pratos usados.

Há duas saídas. Quando chegar a um ponto de pausa, comprima a conversa ou zere tudo.

/compact

/clear

O /compact comprime preservando os pontos principais; o /clear reseta por inteiro. Quando você sentir “há pouco estava rápido, e agora…”, não hesite em usar uma das duas. Aquele “restringir o escopo de leitura” do começo também faz efeito aqui. Quanto menos arquivos desnecessários ele lê, menos a bancada bagunça. Para diagnosticar a lentidão, o guia de otimização de velocidade do Claude Code é detalhado.

3. Não escrever a primeira linha do CLAUDE.md

Esta é da categoria “ainda bem que eu fiz”. O Claude Code lê automaticamente o CLAUDE.md na raiz do projeto. Se você escrever ali as informações do projeto, não precisa explicá-las toda vez.

O que eu lamento é não ter escrito isso no começo. Acabei tendo que explicar “este projeto é em TypeScript, os testes rodam com npm test” em toda conversa. A única linha que você deve escrever primeiro é esta.

## Comandos mais usados
- Testes: npm test
- Servidor de desenvolvimento: npm run dev

Se você escrever só “como rodar os testes”, o Claude Code já tenta rodar os testes sozinho depois de mudar algo. Por outro lado, escrever um CLAUDE.md enorme logo de cara faz com que, dessa vez, as instruções sejam menos seguidas. O que escrever e o que não escrever — essa linha divisória eu separei no boas práticas de CLAUDE.md.

O próximo passo: de tarefas avulsas para “delegar”

Quando você se acostumar com o loop de 30 minutos, o próximo estágio é sair da “instrução avulsa” e passar a “delegar um trabalho razoavelmente fechado”. Mas, mesmo assim, não pule direto para o totalmente automático.

A ordem é sempre a mesma. (1) restringir bem o escopo de leitura → (2) deixar claro a meta (o que entregar) → (3) deixar a verificação a cargo de comandos sempre que possível → (4) operações perigosas, no começo, todas “perguntando ao humano”. Essa ideia de preparar o “andaime” da IA eu reuni em detalhes em como montar o andaime (harness) para delegar trabalho à IA. Ler isso depois da introdução muda a paisagem de uma vez.

A forma de dar instruções, quando você pega o jeito, também muda os resultados. São só três dicas.

1. Escreva o nome do arquivo (de preferência o número da linha) — reduz o esforço de exploração.
2. Descreva o comportamento esperado de forma concreta — “do jeito certo” não funciona.
3. Acrescente as restrições — “siga o padrão existente”, “não toque em outros arquivos”.

Adicione, na função login de src/api/auth.ts, um tratamento que retorna 400 quando a senha estiver vazia.
Para a mensagem de erro, siga o padrão de src/utils/errors.ts. Não toque em outros arquivos

Perguntas frequentes

P. Dá para usar de graça? R. O próprio Claude Code não funciona no plano gratuito do Claude.ai. É preciso uma assinatura como Claude Pro / Max, ou uma conta do Console com créditos pré-pagos. Quem se preocupa com custo, escrevi como definir o orçamento no guia de gestão de custos do Claude Code/API.

P. No Windows funciona igual ao Mac? R. Funciona. Só muda a instalação, que vira irm https://claude.ai/install.ps1 | iex (PowerShell); a inicialização e o uso são iguais. Ter o Git Bash instalado deixa a execução de alguns comandos mais tranquila.

P. Preciso de chave de API? R. Para começar por conta própria, não. Iniciar o claude e logar pelo navegador é o mais tranquilo. A configuração que trata a chave de API por variável de ambiente pode esperar até a política de autenticação da equipe ou o ambiente de nuvem estarem definidos.

P. Ele não faz upload de todo o meu código? R. O Claude Code lê apenas os arquivos necessários, a cada momento. Você não precisa entregar tudo manualmente, e a regra básica é não colar .env, chaves de produção ou dados de clientes. O mínimo em segurança eu reuni em medidas de segurança do Claude Code.

P. Sinto que o modelo padrão é pesado/caro. R. Para tarefas simples, dá para trocar para um modelo mais leve durante a sessão. Com /model você escolhe o modelo, então dividir assim — pesquisa no modelo leve, implementação difícil no modelo mais potente — deixa tudo mais confortável.

Conclusão: dar uma volta no “loop mínimo” em 30 minutos

A forma de começar com Claude Code, no fundo, é uma linha só. Instalar → logar no navegador → fazer ler → mudar algo pequeno → ver o diff e commitar. Se você rodar esse loop de 30 minutos uma vez com as próprias mãos, o “não sei por onde começar” desaparece.

O que é fácil de estragar no primeiro dia são só três coisas: não autorizar tudo, comprimir a conversa quando ficar pesada e escrever uma linha no CLAUDE.md sobre como rodar os testes. Se você evitar isso, a primeira experiência fica bem mais suave.

Este site (claudecode-lab.com) roda todos os dias com Claude Code — a geração de artigos, a tradução e o deploy. Eu, que no começo duvidava “isso é mesmo possível?”, afirmo. Você também, hoje: primeiro, 30 minutos. Digite claude e vá até o primeiro commit.

Se travar de novo, dá para escolher por onde seguir conforme o tipo de travamento. Se quiser ter à mão os comandos e as formas seguras de pedir, a cheat sheet do Claude Code é gratuita; se quiser arrumar de uma vez configurações e operação, a lista de materiais é o atalho.

Os procedimentos mais recentes você também confere no Claude Code Quickstart oficial (em inglês). Instalação e autenticação podem ser atualizadas, então, na dúvida, consulte a fonte primária.

O resultado de eu ter testado, na prática, o que apresentei neste artigo

Eu pedi para um conhecido, engenheiro de front-end (sem familiaridade com CLI), testar esse loop de 30 minutos ao meu lado. O que mais fez diferença foi o “no começo, não deixe ele editar”. Quando você pula a etapa de fazer ler e explicar, a pessoa trava diante da primeira sugestão de edição. Já quem passou por explicação → revisão de um arquivo chegou ao primeiro commit em pouco menos de 30 minutos, de verdade.

Outra coisa que senti na pele foi o efeito da “linha de teste” no CLAUDE.md. Com ela escrita, depois de uma mudança o Claude Code roda npm test por conta própria, percebe sozinho a falha e começa a corrigir. Sem ela, eu fico tendo que dizer “testa aí” toda vez. A diferença de meras duas linhas reduziu visivelmente o número de idas e vindas depois. Antes de sair procurando um modelo mais inteligente, ajeite um andaime — mesmo na introdução, no fim das contas é aí que mais surte efeito.