Tutorial de Claude Code: guia completo do zero

Este tutorial de Claude Code reúne os conceitos que realmente mudam seu resultado com a ferramenta: o arquivo Claude.md, janela de contexto, skills, plan mode, worktrees e subagentes. Você vai entender quando usar cada um, com exemplos de um projeto real em produção.

Tutorial de Claude Code: o que a ferramenta faz

O Claude Code é o agente de codificação da Anthropic que roda no terminal e executa tarefas de programação por linha de comando. Ele lê arquivos, edita código, roda comandos e pesquisa na web, tudo a partir de um chat dentro do seu shell. Em abril de 2026, a Fernanda Kipper publicou uma live de quase 2h20 mostrando como o time dela usa a ferramenta no dia a dia, e este artigo condensa os pontos que tendem a durar mais que as novidades semanais.

Você abre o Claude Code digitando claude no terminal, dentro da pasta do projeto. Tudo que o agente fizer fica restrito àquele diretório. Existe também uma aba de código no app desktop do Claude no time da criadora do conteúdo o uso predominante é o terminal e o plugin dentro da IDE, com Cursor como editor principal.

A conclusão prática da live: a ferramenta entrega mesmo, mas só quando você entende como ela consome contexto. Os próximos blocos seguem a ordem do tutorial de Claude Code original, do arquivo de configuração até múltiplos agentes.

Claude.md: a hierarquia de contexto do projeto

O Claude.md é um arquivo Markdown que armazena regras, diretrizes e informações do projeto, injetadas no contexto do modelo a cada novo chat. Ele funciona como documentação viva: no exemplo da live, descreve a stack do projeto, cores primárias e o propósito da aplicação antes de qualquer tarefa começar.

Existem três níveis de arquivo, e cada um resolve um problema diferente:

Janela de contexto e o comando /compact

A janela de contexto é a memória do chat: prompts, arquivos lidos, outputs e planos acumulam tokens até o limite. A Anthropic ampliaram o contexto dos modelos deles para 200.000 tokens, valor citado na live como o marco que mudou o uso para código; por comparação, o Gemini chegou à casa de 2 milhões de tokens. Na demonstração, um chat recém-aberto já consumia cerca de 7.000 tokens com Claude.md, memórias e descrições de skills antes do primeiro prompt.

Quando a janela enche, o Claude Code pede o comando /compact, que resume o histórico e recomeça com um contexto novo. Depois da compactação:

• o Claude.md do projeto e do usuário é reinjetado;
• regras de diretório são perdidas até você acessar a pasta de novo;
• descrições de skills invocadas voltam com limite de 5.000 tokens por skill e 25.000 no total, descartando as mais antigas primeiro;
• hooks, por serem scripts, não ocupam a janela.

A lição prática é simples: abra chat novo por tarefa e evite arrastar contexto morto. É o que a apresentadora faz para economizar tokens, e é o hábito que mais reduz o custo mensal.

Tools, skills e Superpowers: como o agente ganha poder

Tools são integrações com o sistema operacional que transformam o modelo de chat em agente: ler arquivo, editar, rodar bash, buscar padrões com glob e grep. Elas são chamadas automaticamente e você raramente precisa pensar nelas. A lista completa está na referência oficial de tools.

Skills são outra coisa: instruções reutilizáveis. Uma skill é uma pasta com um SKILL.md cuja descrição no cabeçalho diz ao modelo quando acioná-la. No projeto do exemplo, a skill de testes A/B carrega a metodologia, a ferramenta usada e guias de referência sempre que alguém pede um teste desse tipo. Skills funcionam em nível de projeto (compartilhadas com o time) ou de usuário (só na sua máquina).

O Superpowers é um pacote de skills focadas em metodologia de desenvolvimento — brainstorm, TDD, debugging — que começou como projeto comunitário e ganhou página oficial de plugin. Instalar é um comando no terminal, e a skill de brainstorm costuma ser acionada sozinha quando você pede ajuda para pensar em features.

Um alerta repetido na live: skill consome tokens. Cada invocação injeta o corpo inteiro da instrução no contexto. Crie skills para tarefas detalhadas e recorrentes, não para perfumaria de uma vez só. E cuidado com o excesso: com centenas de skills baixadas da internet, o próprio modelo confunde qual usar, o que apareceu na prática quando uma skill de security review disparou no lugar do agente de CTO esperado.

Plan mode ou modo direto: quando planejar vale tokens

São dois modos de executar tarefas, e a escolha muda o resultado. O quadro abaixo resume:

Aspecto	Modo direto	Plan mode
Fluxo	Executa na hora	Analisa, tira dúvidas e escreve um plano
Custo de tokens	Menor por tarefa	Alto na fase de leitura de arquivos
Risco	Retrabalho em tarefas complexas	Retrabalho evitado antes de codar
Melhor uso	Ajustes simples e pontuais	Refatorações, features grandes, mudanças em front e back

No plan mode, o agente explora os arquivos, pergunta o que não entendeu e gera um plano que você revisa. Corrigir o plano custa pouco; corrigir código errado depois de implementado custa tokens e tempo. Para trocar um título de página, modo direto resolve. Para refatorar um módulo de pagamentos, planeje antes. O comando /effort complementa: esforço low para tarefas simples como traduções, high para pesquisas — lembrando que a escolha vira padrão dos próximos chats.

Worktrees e subagentes: paralelismo sem conflito

Rodar tarefas ao mesmo tempo exige escolher entre paralelismo de file system e paralelismo de contexto. São mecanismos diferentes com resultados diferentes no Git:

Critério	Worktrees	Subagentes
Nível de isolamento	File system (cópia do repositório)	Contexto (threads dentro da sessão pai)
Resultado final	Branches separadas, PRs separadas	Consolidação em uma única entrega
Melhor cenário	Features independentes, várias implementações paralelas	Tarefa grande dividida em frentes que convergem
Origem	Conceito clássico do Git worktree	Task tool nativa do Claude Code

Com claude --worktree nome, o agente trabalha numa cópia completa do repositório dentro da pasta .claude/worktrees. Dois agentes podem mexer no mesmo arquivo sem conflito, porque fisicamente são arquivos diferentes. Ao terminar, você comita, abre o PR e encerra a worktree. Subagentes, por outro lado, rodam dentro do chat pai, cada um com janela de contexto própria: um pesquisa back end, outro mexe no front, outro documenta, e só o resultado volta para a sessão principal. Você define modelo e tools por subagente em arquivos Markdown na pasta .claude/agents, limitando tools para reduzir o system prompt.

Dois cuidados práticos da experiência do time: agentes paralelos consomem RAM — três chats abertos travaram um MacBook Pro com 16 GB durante a live — e uma worktree antiga podia abrir na branch atual sem avisar. Em 2026 a ferramenta já cria uma branch automática com nome aleatório quando nenhuma é informada, mas conferir a branch antes de comitar continua sendo boa prática.

Modelos, planos e limites: o que esperar de custo

O Claude Code roda nos modelos da Anthropic, trocáveis com /model: Opus para tarefas complexas, Sonnet para o dia a dia, Haiku para respostas rápidas. No relato de experiência, o Sonnet atendeu quase 100% das tarefas, com Opus reservado para integrações mais elaboradas e refatorações difíceis. Quem conta essa vivência no vídeo é a Fernanda Kipper, do canal Dev Doido do canal do youtube, junto com o time que mantém um portal de cursos gratuitos e um ERP para agências.

Sobre planos, o relato é de experiência própria, não de benchmark: o plano Pro estourou em horas de uso intenso, e o time migrou para o Max 20x. O contexto de custo é real — dois desenvolvedores construíram uma aplicação completa em um mês e meio usando IA, o que justifica o gasto, mas modelos alternativos mais baratos já aparecem na conversa como candidatos a teste. Trate esses números como relato datado de 2026, sujeito a mudança de preços e limites pela Anthropic material de estudo sobre o fluxo está em crazystack.com.br.

FAQ sobre o Claude Code

• O Claude.md substitui documentação do projeto?

Ele complementa, não substitui. O arquivo carrega regras e contexto essenciais para o agente; a documentação completa continua útil para o time e para quem chega novo.

• Skills consomem tokens mesmo sem serem usadas?

Sem uso, só a descrição ocupa espaço no carregamento inicial. Quando o modelo aciona a skill, o corpo inteiro da instrução entra no contexto e passa a consumir tokens.

• Worktree e branch são a mesma coisa?

Não. A worktree é uma cópia de trabalho do repositório em outra pasta, e ela está associada a uma branch. É um recurso do Git que o Claude Code aproveitou para isolar agentes.

• Posso usar skills em outras ferramentas de IA?

Sim. O formato de pasta com SKILL.md é aceito por editores como o Cursor, e repositórios públicos na internet distribuem pacotes de skills prontas.

• Vale assinar o plano mais barato para começar?

Depende da intensidade de uso. No relato da live, uso pesado estourou o plano de entrada rapidamente; quem usa com moderação pode começar pequeno e subir depois.

• Como evitar commits acidentais na branch principal com worktrees?

Sempre informe um nome de branch ao criar a worktree e confira com git branch antes de comitar. Versões recentes criam branch automática, mas conferir custa dois segundos.

• Subagentes economizam contexto de verdade?

Sim, porque cada subagente tem janela própria e devolve apenas o resultado à sessão pai. Em tarefas grandes, isso evita compactações frequentes e perda de detalhes.

• O que fazer quando o modelo não chama a skill ou o agente certo?

Invoque explicitamente pelo nome. Excesso de skills e agentes com sobreposição de propósito confunde o roteamento automático; enxugue o que não usa.

• O Claude Code funciona só no terminal?

Hoje não: existe aba de código no app desktop do Claude plugins para editores. O terminal continua sendo o caminho mais comum, mas não é mais o único.

Transforme suas lives técnicas em artigos

Uma live de 2h20 como essa guarda meses de aprendizado sobre contexto, skills e agentes paralelos — conhecimento que merece existir em texto pesquisável, e não só em vídeo. Se você também ensina em lives e tutoriais, o Skala Blog transforma sua gravação em artigo: você cola a URL do YouTube, a transcrição é gerada e o artigo sai estruturado, pronto para revisar e publicar.

Source video