Começando com o Claude Code em 2026: do setup ao primeiro commit

O que o Claude Code de fato é

O Claude Code não é uma interface de chat. É um agente de linha de comando que lê seu sistema de arquivos, executa comandos bash, edita arquivos e itera sobre a própria saída até alcançar o objetivo descrito. Você o inicia num diretório de projeto, passa uma tarefa e ele resolve o problema passo a passo — lê o código existente, faz mudanças, roda testes e volta atrás caso algo falhe.

A consequência prática: o Claude Code rende em problemas reais e bem delimitados, dentro de bases de código reais. Pedir "me ajuda no meu projeto" gera deriva. Pedir "adicione validação de entrada na função createUser em src/api/users.ts e atualize os testes correspondentes" gera resultado.

Passo 1 — Instalar

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

Confirme que a instalação deu certo:

claude --version
# → claude-code 1.x.x

Se aparecer erro de permissão no macOS ou Linux, a solução padrão é ajustar a propriedade do diretório global do npm em vez de rodar npm com sudo. A documentação da Anthropic cobre isso na seção de pré-requisitos. No Windows, abrir o terminal como administrador resolve a maioria dos casos, mas o caminho via WSL2 é mais confiável para uso agêntico pesado.

Passo 2 — Autenticar

claude login

Esse comando abre uma janela do navegador para o OAuth. Concluído o fluxo, as credenciais ficam armazenadas em ~/.claude/ e você só precisa repetir o passo se trocar de conta.

Se você usa chave de API direta — por exemplo, em ambiente de CI ou numa máquina sem navegador — defina a variável de ambiente:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

A assinatura Claude Pro inclui uma franquia mensal de tokens que cobre uso individual moderado. Se você roda Claude Code em bases grandes, escreve testes em volume ou usa o agente em loops, é provável que bata o limite do Pro e precise complementar com créditos de API. O console da Anthropic mostra seu consumo em tempo real — confira depois das primeiras sessões para calibrar.

Passo 3 — Escrever seu CLAUDE.md

Um CLAUDE.md mínimo, mas eficaz, cobre cinco coisas:

# Projeto: [nome]

## Stack
- Runtime: Node 20, TypeScript 5.3
- Framework: Next.js 14 (App Router)
- Banco: PostgreSQL via Prisma
- Testes: Vitest, rodar com `npm test`

## Comandos
- Servidor de dev: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint` — corrigir antes do commit
- Migrar: `npx prisma migrate dev`

## Regras
- Toda nova rota de API vai em src/app/api/
- Zod para toda validação de entrada — nada de req.body cru
- Nunca toque no diretório /legacy/
- Não remova chamadas console.error em handlers de erro

## Não faça
- npm install de pacotes sem perguntar antes
- Modificar arquivos .env
- Rodar migrações de banco sem confirmação

A seção "Não faça" é a que mais gente pula na primeira passada — e é justamente a que evita os erros caros. Se há arquivos que o Claude jamais deve tocar, nomeie. Se há comandos que ele não pode rodar de forma autônoma, diga isso de forma explícita.

Para um tratamento mais profundo da estrutura do CLAUDE.md, leia nosso post sobre como escrever um CLAUDE.md que de fato funciona. O Septim Starter (US$ 9) traz um template testado em campo para cinco tipos de projeto comuns — Next.js, Python Flask, Rails, Go e Node puro — para você não começar do papel em branco.

Passo 4 — Dar uma tarefa real

cd ~/projects/my-app
claude

No prompt, dê uma tarefa específica o suficiente para ter um critério claro de conclusão. Boas primeiras tarefas para iniciantes:

• Adicionar um rate limiter na rota /api/login — 5 tentativas por minuto por IP, retornando 429 quando exceder
• Escrever testes unitários para todas as funções em src/lib/date-utils.ts — meta de 90% de cobertura por branch
• Refatorar src/components/UserTable.tsx para usar React Query no lugar de chamadas fetch cruas

O Claude Code vai ler os arquivos relevantes, propor mudanças e pedir permissão antes de gravar em disco ou rodar comandos. Na configuração padrão, ele confirma antes de qualquer escrita — esse é o modo certo para aprender. Você pode afrouxar ou apertar essas permissões em ~/.claude/settings.json depois que entender o comportamento da ferramenta.

O que acontece durante o loop agêntico

Uma tarefa típica do Claude Code passa por este ciclo:

1. Ler os arquivos-fonte relevantes para entender a estrutura atual
2. Propor um plano de implementação e listar os arquivos que serão tocados
3. Escrever as mudanças arquivo por arquivo, com explicação
4. Rodar a suíte de testes (se configurada no CLAUDE.md) e iterar nas falhas
5. Reportar a conclusão e listar todos os arquivos alterados

Em tarefas diretas — adicionar um campo num formulário, escrever uma função utilitária pequena, corrigir um erro de tipo — isso roda em menos de dois minutos. Em tarefas maiores (refatorar um módulo, implementar uma feature ponta a ponta), planeje 5 a 15 minutos e algumas rodadas de iteração.

Passo 5 — Conferir os custos

O console da Anthropic em console.anthropic.com mostra seu consumo de tokens detalhado por modelo e por dia. Depois das duas ou três primeiras sessões, abra o painel para entender sua taxa de queima antes de começar a usar o Claude Code em tarefas mais longas.

Os três padrões que disparam custo inesperado:

• Arquivos grandes no contexto. Se o Claude Code lê um arquivo de 10.000 linhas para responder a uma pergunta sobre uma única função, você pagou por 10.000 linhas em tokens de entrada. Aponte para arquivos específicos em vez de fazer perguntas amplas sobre a base inteira.
• Reconstrução repetida de contexto. Cada nova mensagem na sessão reenvia o histórico inteiro da conversa. Sessões longas saem caras. Abra sessões novas para tarefas não relacionadas em vez de continuar a mesma sessão o dia todo.
• Spawn de subagentes. O Claude Code consegue disparar subagentes para trabalho paralelo. Cada subagente carrega seu próprio contexto. Se você está rodando vários, o custo escala junto. O guia Tokenocalypse cobre isso em detalhe — veja o detalhamento de custo por subagente.

Uma tarefa de programação bem delimitada custa, em geral, US$ 0,05 a US$ 0,40 em créditos de API, dependendo do tamanho dos arquivos e da complexidade. Uma sessão em que você pede para o Claude Code entender a base inteira antes de fazer qualquer coisa pode passar dos US$ 5. O CLAUDE.md que você escreveu no passo 3 reduz bastante esse segundo padrão — contexto pré-fornecido substitui tokens gastos em exploração.

Erros comuns na primeira sessão

Pedir ao Claude Code para "olhar meu projeto e dizer o que está errado"

Isso queima a janela de contexto numa caça pela sorte. A saída costuma ser um code review genérico que pode até identificar problemas reais, mas a um custo de tokens significativo. Use Septim Drills (US$ 29) para exercícios estruturados de revisão, ou aponte o Claude Code para um arquivo específico com uma pergunta específica.

Não ler o plano antes de aprovar

O Claude Code propõe um plano antes de executar. Leia. Em tarefas complexas, o plano às vezes inclui passos que você não autorizaria — derrubar uma tabela, remover uma camada de cache, mexer num arquivo que você expressamente excluiu. Pegar isso na fase de plano não custa nada. Pegar depois das escritas é um git revert.

Rodar sem controle de versão

O Claude Code escreve em disco. Use só em repositórios com a árvore de trabalho limpa para conseguir rodar git diff em cada mudança e git checkout . em qualquer coisa que você discorde. Se ainda não tem git, inicialize um repositório antes de abrir sua primeira sessão.

Pular o CLAUDE.md

Sem CLAUDE.md, o Claude Code infere o contexto do projeto explorando arquivos. Essa inferência custa tokens e costuma errar em convenções, comandos proibidos e runners de teste. Os 20 minutos investidos no CLAUDE.md no passo 3 se pagam só na primeira semana de uso.

Para onde ir depois

Depois de concluir algumas tarefas com sucesso, o passo natural é estender o Claude Code com servidores MCP — integrações que dão acesso a ferramentas externas como banco de dados, GitHub ou navegador. Veja o tutorial de servidor MCP para um passo a passo prático.

Se você está rodando o Claude Code em um time e quer configurar revisão automatizada de PR, o guia de setup de PR review cobre a configuração da GitHub Action ponta a ponta.

Para gestão de custos em escala — depois da fase iniciante, com Claude Code no dia a dia — leia o guia de monitoramento de custos e o post sobre gerenciamento de contexto.