Claude Code: Tutorial Completo em Português - Do Terminal ao Projeto Funcionando [2026]

Se existe uma ferramenta que mudou radicalmente como construímos software na Marfin, essa ferramenta é o Claude Code.

Não estamos falando de um copiloto que sugere linhas de código enquanto você digita. Estamos falando de um agente completo que vive no terminal, entende seu projeto inteiro, executa tarefas complexas em múltiplos arquivos, roda testes, corrige bugs e faz commit. Tudo isso enquanto você descreve o que quer em linguagem natural.

Em abril de 2026, a Anthropic lançou o Opus 4.7 com uma taxa de 87,6% no SWE-bench, o benchmark mais respeitado para avaliar a capacidade de IAs em resolver problemas reais de engenharia de software. Para contextualizar: isso significa que o Claude Code resolve quase 9 em cada 10 issues de repositórios open-source de forma autônoma. Nenhuma outra ferramenta chega perto.

Neste tutorial, vamos te mostrar como instalar, configurar e usar o Claude Code do zero. Vamos construir um projeto real juntos, mostrar os recursos avançados que a maioria das pessoas nem sabe que existe, e explicar exatamente quando usar o Claude Code versus o Cursor AI (spoiler: a resposta é "os dois").

O que é o Claude Code

Claude Code é a ferramenta de coding agêntico da Anthropic. Diferente de IDEs com IA como Cursor ou Windsurf, o Claude Code opera direto no terminal. Não precisa de editor gráfico, não precisa de extensão, não precisa de nada além de um terminal e uma conta na Anthropic.

O conceito por trás é simples, mas poderoso: você abre o terminal na pasta do seu projeto, digita claude, e começa a conversar. O Claude Code lê toda a estrutura do seu projeto, entende as relações entre arquivos, dependências, configurações e arquitetura. A partir daí, ele planeja, executa e verifica as mudanças automaticamente.

O fluxo de trabalho é fundamentalmente diferente de qualquer outra ferramenta. Em um IDE tradicional com IA, você escreve código e a IA sugere completions. No Cursor, você descreve o que quer e a IA gera código que você revisa no editor. No Claude Code, você define o objetivo e o agente resolve sozinho: ele planeja a abordagem, modifica os arquivos necessários, roda os testes, encontra erros, corrige e entrega o resultado final. O ciclo completo é Plan, Execute, Verify, Report.

A janela de contexto de 1 milhão de tokens é outro diferencial brutal. Isso significa que o Claude Code consegue manter em memória milhares de arquivos de código fonte simultaneamente. Projetos inteiros, monorepos, documentações completas. Nada de ficar selecionando manualmente quais arquivos a IA deve ler.

Por que o Claude Code é nossa ferramenta #1

Na Marfin, testamos praticamente todas as ferramentas de vibe coding do mercado. Usamos o Cursor diariamente para construir. Usamos o V0 da Vercel para gerar interfaces React. Testamos Bolt.new, Lovable, Replit, Windsurf.

O Claude Code se destaca por um motivo específico: ele é o melhor para tarefas que exigem autonomia e profundidade. Refatorar um módulo inteiro, migrar uma base de dados, implementar uma feature complexa que toca 15 arquivos diferentes, gerar suítes de testes, debugar um problema que ninguém consegue achar. Essas tarefas que normalmente levam horas ou dias, o Claude Code resolve em minutos.

Nosso workflow padrão combina as duas ferramentas: Cursor para escrever código novo, iterar rapidamente em componentes específicos e fazer edições pontuais. Claude Code para as tarefas pesadas que exigem visão do projeto inteiro e execução autônoma.

Como instalar o Claude Code

A instalação é rápida. Existem dois métodos.

Método 1: Instalador nativo (recomendado)

O instalador nativo é o método que a Anthropic testa e suporta oficialmente. Não precisa de Node.js, não precisa de npm, e atualiza automaticamente em background.

No macOS, abra o terminal e rode:

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

No Linux (Ubuntu 20.04+ ou Debian 10+):

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

No Windows, você precisa do WSL (Windows Subsystem for Linux) instalado. Dentro do WSL, rode o mesmo comando do Linux.

Método 2: npm

Se você já tem Node.js 18+ instalado e prefere gerenciar via npm:

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

Requisitos de sistema

O Claude Code roda em macOS 13.0 (Ventura) ou superior, Ubuntu 20.04+ ou Debian 10+, e Windows 10 (versão 1809+) com WSL. Precisa de pelo menos 4 GB de RAM, mas a Anthropic recomenda 8 GB para projetos maiores.

Autenticação

Na primeira vez que você rodar o comando claude, o terminal vai abrir seu navegador para autenticação. Faça login na sua conta Anthropic, autorize o CLI, e pronto. O token fica salvo localmente e você não precisa autenticar de novo.

Importante: o plano gratuito do Claude não inclui o Claude Code. Você precisa de pelo menos o plano Pro (US$ 20/mês).

Primeiros passos: seu primeiro projeto com Claude Code

Vamos construir algo real. Vamos criar uma API REST completa com Node.js, Express e SQLite para gerenciar uma lista de tarefas.

Passo 1: Iniciar o projeto

Abra o terminal, crie uma pasta e inicie o Claude Code:

mkdir todo-api && cd todo-api
claude

O Claude Code vai iniciar e mostrar um prompt interativo. Agora é só conversar.

Passo 2: Descrever o que você quer

Digite no prompt:

Crie uma API REST completa com Node.js e Express para gerenciar tarefas (todos).
Use SQLite como banco de dados. Inclua:
- CRUD completo (criar, listar, atualizar, deletar tarefas)
- Validação de inputs
- Tratamento de erros
- Testes com Jest
- Package.json com scripts de dev e test

O Claude Code vai:

Analisar o que você pediu
Criar um plano de implementação
Gerar todos os arquivos necessários (package.json, server.js, rotas, models, testes)
Instalar as dependências rodando npm install
Rodar os testes para verificar se tudo funciona
Reportar o resultado final

Tudo isso sem você tocar em uma linha de código.

Passo 3: Iterar

O projeto está rodando, mas você quer adicionar autenticação. Digite:

Adicione autenticação JWT. Crie rotas de registro e login.
Proteja as rotas de tarefas para exigir token válido.
Cada usuário só pode ver suas próprias tarefas.

O Claude Code vai entender o contexto do projeto existente, modificar os arquivos necessários, criar os novos, atualizar os testes e verificar que nada quebrou.

Passo 4: Deploy

Adicione um Dockerfile e docker-compose.yml para produção.
Configure variáveis de ambiente para JWT_SECRET e DATABASE_URL.

Em poucos minutos, você tem uma API completa, testada e containerizada, pronta para deploy.

CLAUDE.md: o arquivo que muda tudo

O CLAUDE.md é o recurso mais subestimado do Claude Code. É um arquivo markdown que fica na raiz do seu projeto e funciona como um manual de instruções que o Claude lê automaticamente no início de cada sessão.

Pense nele como o onboarding que você daria a um desenvolvedor novo entrando no projeto. Aqui você coloca:

# Projeto: Todo API

## Stack
- Node.js 20 + Express
- SQLite via better-sqlite3
- Jest para testes
- Docker para deploy

## Convenções
- Use async/await, nunca callbacks
- Nomes de variáveis em camelCase
- Responses sempre no formato { data, error, message }
- Testes devem cobrir happy path e edge cases

## Comandos
- `npm run dev` - servidor de desenvolvimento
- `npm test` - rodar testes
- `npm run lint` - verificar estilo

## Arquitetura
- /src/routes - rotas Express
- /src/models - acesso ao banco
- /src/middleware - auth, validation, error handling
- /tests - testes Jest espelhando a estrutura de /src

Com um bom CLAUDE.md, o Claude Code gera código que segue exatamente as convenções do seu projeto desde a primeira interação. Sem explicações repetidas, sem correções de estilo.

Em projetos grandes, você pode colocar CLAUDE.md adicionais em subdiretórios para dar instruções específicas para cada parte do codebase.

Recursos avançados que fazem a diferença

Sub-agentes

O Claude Code pode criar sub-agentes para executar tarefas em paralelo. Imagine que você pede: "refatore todos os componentes React para usar hooks ao invés de classes". O Claude Code pode criar sub-agentes especializados, cada um cuidando de um grupo de componentes simultaneamente. O resultado chega muito mais rápido.

MCP Servers (Model Context Protocol)

MCP é o protocolo que permite conectar o Claude Code a ferramentas externas. Banco de dados, APIs, serviços de deploy, ferramentas de monitoramento. Você configura os servidores MCP no arquivo de settings e o Claude Code ganha acesso a essas ferramentas como se fossem nativas.

Exemplo prático: conecte o MCP do Supabase e o Claude Code consegue criar tabelas, modificar schemas e rodar queries diretamente no seu banco de produção ou staging. Conecte o MCP do GitHub e ele cria branches, abre PRs e resolve issues automaticamente.

A configuração dos MCP servers fica no arquivo de settings do Claude Code:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Hooks

Hooks são comandos que executam automaticamente em pontos específicos do ciclo do Claude Code. Eles ficam configurados no settings.json como blocos JSON (não são módulos JavaScript).

Exemplos de uso:

PreToolUse: Rodar lint antes de qualquer mudança de arquivo
PostToolUse: Logar todas as ações para auditoria
Notification: Enviar notificação no Slack quando uma tarefa longa termina

Os hooks servem como guardrails. Você pode criar hooks que impedem o Claude Code de modificar certos arquivos, que exigem aprovação para operações destrutivas, ou que verificam se o código gerado passa nos padrões da equipe.

Slash commands

O Claude Code tem comandos rápidos que agilizam o workflow:

/clear - Limpa o contexto e começa uma conversa nova (faça isso frequentemente para evitar drift)
/compact - Compacta o contexto mantendo as informações essenciais
/cost - Mostra quanto você gastou na sessão
/memory - Gerencia memórias persistentes entre sessões
/review - Faz review do código atual
/pr - Cria um pull request com descrição gerada automaticamente

Claude Code vs. Cursor AI: quando usar cada um

Essa é a pergunta que mais recebemos. A resposta não é "um ou outro", é "os dois, para coisas diferentes".

O Cursor é imbatível para escrever código novo linha por linha. O tab completion do Cursor prevê não só a próxima linha, mas as próximas 5 a 10 linhas baseadas no contexto. Para criar componentes, iterar em UI, fazer edições cirúrgicas em arquivos específicos, o Cursor é mais rápido e mais ergonômico.

O Claude Code é superior para tarefas autônomas e complexas. Refatorações que tocam dezenas de arquivos, geração de suítes de testes completas, debugging de problemas difíceis, migrações de banco de dados, implementação de features que exigem coordenação entre múltiplas camadas da aplicação. São situações onde você quer definir o objetivo e deixar o agente trabalhar.

Outra diferença fundamental: modelo. O Cursor suporta múltiplos modelos (Claude, GPT-5, Gemini, seu próprio modelo Composer). O Claude Code usa exclusivamente os modelos da Anthropic (Sonnet 4.6 e Opus 4.6/4.7). Para nós, isso é uma vantagem, porque o Opus 4.7 é o melhor modelo de código disponível atualmente.

Na prática, nosso dia a dia na Marfin funciona assim: abrimos o Cursor para trabalhar nos arquivos do projeto com o editor visual. Quando surge uma tarefa pesada (implementar um módulo novo, refatorar algo grande, resolver um bug complexo), alternamos para o Claude Code no terminal. Os dois compartilham o mesmo diretório do projeto, então as mudanças feitas em um são visíveis no outro instantaneamente.

Para uma análise detalhada das diferenças entre IDEs com IA, leia nosso comparativo entre Replit, Cursor e Windsurf.

Planos e preços em 2026

O Claude Code está disponível em diferentes planos.

O Pro custa US$ 20/mês e funciona bem para a maioria dos desenvolvedores individuais. Dá acesso ao Claude Code no terminal, web e desktop, com Sonnet 4.6 e Opus 4.6. Para uso casual a moderado, é mais que suficiente.

O Max 5x custa US$ 100/mês e é para quem bate os limites do Pro regularmente. Aumenta significativamente os limites de uso e dá prioridade no processamento.

O Max 20x custa US$ 200/mês, para uso intensivo.

Para times, existe o Claude for Teams e o Claude for Enterprise, com gerenciamento centralizado, SSO, e controles administrativos.

Também é possível usar via API, pagando por token sem mínimo mensal. O Sonnet 4.6 cobra US$ 3 por milhão de tokens de input e US$ 15 por milhão de tokens de output. O Opus sai mais caro, mas para tarefas críticas, o custo se paga pela qualidade.

10 dicas para tirar o máximo do Claude Code

1. Comece cada sessão com /clear. Contexto residual de tarefas anteriores causa drift e respostas menos precisas. Sessão nova, contexto limpo.

2. Escreva um CLAUDE.md robusto. Quanto mais contexto você der sobre convenções, stack e arquitetura, melhor o código gerado. Invista tempo nisso uma vez e colha os benefícios para sempre.

3. Seja específico nos prompts. Em vez de "melhore esse código", diga "refatore o módulo de autenticação para usar refresh tokens com rotação automática, mantendo backward compatibility com os tokens existentes". Contexto e especificidade fazem toda a diferença.

4. Use sub-agentes para tarefas paralelas. Se precisa atualizar 20 componentes, deixe o Claude Code paralelisar o trabalho.

5. Conecte MCP servers relevantes. Banco de dados, ferramentas de deploy, APIs internas. Quanto mais acesso o Claude Code tem, mais autônomo ele fica.

6. Configure hooks de segurança. Proteja arquivos sensíveis, exija aprovação para operações destrutivas, configure logs de auditoria.

7. Combine com Cursor. Não é um ou outro. Use o Claude Code para as tarefas pesadas e o Cursor para edição rápida.

8. Revise sempre. O Claude Code é impressionante, mas não é infalível. Revise o código gerado, especialmente em lógica de negócio crítica.

9. Use o modo compact para sessões longas. Se uma sessão ficou longa, use /compact para manter o contexto relevante sem perder informações importantes.

10. Itere em partes. Para features complexas, divida em sub-tarefas. "Primeiro, crie o schema do banco. Depois, crie as rotas. Depois, os testes." Cada iteração com verificação é melhor que um prompt gigante.

O futuro do coding com IA

O Claude Code representa um paradigma novo: o desenvolvedor como arquiteto e revisor, não como digitador de código. Com 87,6% no SWE-bench, estamos num ponto onde a IA resolve a maioria dos problemas de engenharia de software de forma autônoma.

Isso não significa que programadores ficaram obsoletos. Significa que o que define um bom desenvolvedor mudou. Hoje, as habilidades mais valiosas são: saber definir problemas com clareza, arquitetar soluções de alto nível, revisar código com olho crítico e entender as limitações da IA para saber quando intervir.

Na Marfin, o Claude Code nos permitiu entregar mais rápido, com menos bugs e com uma equipe menor do que seria necessário de outra forma. Se você trabalha com código em qualquer nível, do founder que faz vibe coding para marketing ao desenvolvedor sênior que mantém sistemas complexos, o Claude Code vai mudar como você trabalha.

Abra o terminal. Digite claude. E comece a construir.

Leia também: