Claude Code do zero: o guia completo para iniciantes em 2026 (sem jargão, sem desastre)

Se a ideia de deixar uma inteligência artificial mexer no seu código dá um frio na barriga, você está no lugar certo. Muita gente trava no começo por medo de apagar um arquivo, expor uma chave ou aprovar uma mudança sem entender. Este guia existe para tirar esse medo com um caminho simples e seguro.

Aqui você vai entender o que é o Claude Code em linguagem normal, como instalar e entrar com sua conta, o que fazer nos primeiros 30 minutos, como deixar o arquivo CLAUDE.md pequeno e as permissões travadas, e quais erros evitar. No fim, você segue para quatro guias curtos, um para cada etapa.

Pense neste texto como um mapa. Você lê de cima a baixo uma vez para perder o medo, depois volta aos trechos que precisa na hora de agir. Cada seção termina com o link para o satélite que aprofunda aquele passo, então você nunca fica sem próximo movimento.

roteiro dos primeiros 30 minutos

Claude Code é um agente que trabalha dentro do terminal e ajuda você a lidar com código por conversa. Ele lê arquivos, propõe edições e roda comandos, mas pede sua aprovação antes de executar ações que mudam algo. Essa é a diferença central para guardar: nada acontece por trás dos seus olhos, você revisa antes de aceitar. A definição funcional e os comandos essenciais estão no guia oficial de início rápido.

Para quem serve? Para quem estuda programação, para quem programa em outra área e quer ajuda com tarefas repetitivas, e para quem já programa e quer delegar ajustes pequenos com revisão. Se você nunca abriu o terminal, este pilar ainda serve, porque a ordem foi pensada para você não pular etapas. Se você já usa outra ferramenta de IA para código, serve também para entender onde o Claude Code se encaixa.

Para quem não serve neste momento? Para quem quer só completar linhas enquanto digita, sem conversar com o projeto. Para esse uso existe autocomplete no editor, que é outro tipo de ajuda. O Claude Code brilha quando você descreve um objetivo e revisa o plano antes da execução.

O que ele faz no seu dia a dia

Na rotina, o fluxo é sempre parecido. Você descreve o objetivo em uma frase, ele localiza os arquivos ligados ao pedido, mostra o que entendeu e propõe uma mudança. Você lê a proposta, pede ajuste se algo parece fora do lugar e só então autoriza a execução. Depois, você revisa o diff e decide se mantém, ajusta ou desfaz. Esse ciclo de pedir, revisar e confirmar vale para tarefas pequenas, como ajustar um texto, e para tarefas médias, como organizar uma função em partes mais claras.

O ponto que traz calma é a aprovação explícita. Leitura e explicação vêm primeiro, edição e comando vêm depois, com você no meio de cada decisão que altera arquivos. Quando o pedido está vago, o melhor movimento é pedir para ele explicar antes de mudar, porque explicação não altera nada e já mostra se o contexto está certo.

Onde o Claude Code pode rodar

O mesmo agente aparece em várias superfícies, e isso confunde no início. Pense assim: o motor é um só, a porta de entrada muda. As superfícies documentadas são CLI, VS Code, JetBrains, app desktop, web, Slack e integração com CI, conforme o resumo em português publicado em 14/jul/2026 no guia sobre o que é Claude Code.

Na prática de iniciante, comece pelo terminal, que é a CLI. Depois que o fluxo fica confortável, faz sentido usar dentro do VS Code ou JetBrains para ver diffs com mais conforto. Desktop, web e Slack ajudam a conversar ou acompanhar, e CI serve para automação em equipe. Você não precisa configurar tudo agora. Escolha uma porta e aprenda bem o básico.

Se você quer uma comparação direta com outras ferramentas antes de continuar, guarde este atalho para depois da leitura do básico: Claude Code vs Cursor vs Copilot.

Instalar o Claude Code é usar o canal normal do seu sistema, sem atalhos estranhos. No Linux e macOS o caminho nativo usa curl, no Windows usa irm no PowerShell, no macOS também existe a opção brew cask, no Windows existe winget, e em qualquer sistema funciona via npm desde que o Node esteja na versão 22 ou superior. O requisito de memória é simples: 4GB no mínimo e 8GB recomendados para trabalhar com conforto. Todos esses caminhos e requisitos estão descritos no guia oficial de início rápido.

Depois de instalar, vem o login. Você pode entrar com assinaturas Pro, Max, Team ou Enterprise, ou com acesso via Console e Bedrock em cenários de empresa e nuvem. O ponto que evita frustração: o plano gratuito não inclui o Claude Code, então se você está no free e recebe bloqueio, não é erro de instalação, é limite do plano. Esse aviso aparece de forma clara no guia sobre o que é Claude Code, publicado em 14/jul/2026.

Uma ordem calma para instalar

Primeiro, confirme o Node se você escolheu npm, com versão 22 ou maior. Segundo, rode apenas um método de instalação, o do seu sistema, sem misturar curl com npm na mesma tentativa. Terceiro, abra um terminal novo e rode o comando principal para confirmar que o programa responde. Quarto, faça login com a conta que tem direito de uso. Se algo falhar, o comando de diagnóstico ajuda: /doctor verifica ambiente e aponta o que falta. Essa lista de comandos de base, incluindo /help, /init, /clear, /compact, /model, /permissions, /mcp, /config e /doctor, está no guia oficial de início rápido.

Se o terminal mostrar erro de comando não encontrado após instalar, feche e abra o terminal de novo antes de tentar de novo, porque o caminho do sistema só atualiza na nova sessão. Se o erro for de permissão no Windows, prefira o PowerShell com o método irm e evite misturar com npm na mesma pasta. Se o erro for de versão do Node, atualize para a 22 ou superior e repita a instalação por um único canal. Anote qual método você usou, porque isso facilita pedir ajuda depois.

Vale separar dois conceitos desde já. Instalar é colocar o programa na máquina. Autorizar é dizer o que ele pode fazer no seu projeto. Muita gente mistura os dois e libera tudo logo no primeiro dia por pressa. Não faça isso. Instale, entre com a conta certa e deixe as permissões no modo mais cuidadoso, que vamos ver adiante. Essa separação simples já reduz a maior parte do estresse de iniciante.

Para o passo a passo por sistema, com os comandos exatos de Windows, Mac e Linux, siga o satélite de instalação: como instalar no Windows Mac e Linux.

Preço e login em uma frase cada

Preço: se sua conta é gratuita, planeje migrar para um plano com direito ou usar Console e Bedrock da sua empresa, porque o free não libera o agente. Login: use Pro ou Max para uso individual, Team ou Enterprise para time, Console ou Bedrock para nuvem e integrações. Quando o login expira ou troca de máquina, entre de novo e rode /doctor para confirmar que está tudo certo.

Os primeiros 30 minutos devem ser uma prática guiada, não uma reforma no seu projeto real. A regra de ouro é criar um branch separado só para treinar, com um repositório git ativo. Assim, qualquer sugestão pode ser vista no diff e desfeita sem drama. Esse cuidado com branch de prática e o ciclo ler, explicar, mudar, revisar diff e fazer commit aparece no roteiro de 30 minutos publicado em 08/abr/2026 no guia de primeiros passos e no loop prático de 27/abr/2026 no guia completo para começar.

Comece com comandos que só leem e explicam. Use /help para ver a ajuda, /model para confirmar o modelo ativo, e peça algo como explique a estrutura desta pasta. Depois peça uma mudança minúscula, como renomear uma variável ou ajustar um texto. Revise o diff com calma, linha por linha, e só então faça commit. Esse ritmo parece lento, mas é ele que cria confiança rápido.

Como pedir bem desde a primeira conversa

Pedidos bons têm três partes curtas: onde, o que e como conferir. Onde é a pasta ou o arquivo, o que é a mudança desejada em uma frase, e como conferir é o teste ou a leitura que prova que funcionou. Por exemplo: nesta pasta, explique quais arquivos cuidam de login, sem alterar nada. Ou: neste arquivo, ajuste este texto e mostre o diff antes de finalizar. Quando faltar contexto, o agente vai perguntar, e responder essas perguntas com o nome do arquivo e o resultado esperado economiza uma rodada inteira de correção.

Os comandos que valem seus primeiros dias

Guarde este kit inicial. /help mostra ajuda, /init cria um CLAUDE.md inicial no projeto, /clear limpa o contexto da conversa sem mexer nos arquivos, /compact resume a conversa quando ela fica longa, /model troca ou confirma o modelo, /permissions abre o controle do que pode rodar sem perguntar, /mcp gerencia integrações externas, /config ajusta preferências e /doctor checa o ambiente. A lista completa está no guia oficial de início rápido.

Além deles, existem três formas de rodar que mudam seu controle. O modo normal abre a conversa interativa. O modo one-shot com claude -p executa um pedido único e termina, bom para perguntas fechadas. As flags -c e -r retomam ou continuam uma conversa anterior, o que evita repetir contexto. O uso de one-shot com -p e o cuidado com retomada aparecem no guia completo para começar de 27/abr/2026.

Uma divisão simples para seus 30 minutos

Pense em blocos curtos: 5 minutos para ler a estrutura, 5 para pedir explicações, 7 para fazer uma mudança pequena, 6 para revisar o diff com atenção e 7 para fazer commit e anotar o que aprendeu. Essa divisão é uma sugestão de ritmo, não uma regra oficial. Ela traduz o ciclo recomendado nos dois guias de abril de 2026 em um plano que cabe em meia hora.

Quando terminar esse ciclo uma vez, repita com uma tarefa um pouco maior, ainda no branch de treino. O objetivo não é produzir muito, é aprender a pedir, revisar e desfazer. Para o roteiro detalhado com o que digitar em cada bloco, abra o satélite prático: roteiro dos primeiros 30 minutos.

CLAUDE.md é um arquivo de instruções que fica no seu projeto e diz ao agente como trabalhar ali. A melhor versão inicial é curta: nome do projeto em uma linha, como rodar testes em uma ou duas linhas, e o que nunca fazer. Exemplo de espírito: rode os testes com este comando, não mexa em chaves, peça antes de instalar algo novo. Manter esse arquivo pequeno e com comandos de teste é a recomendação que aparece no tutorial de 28/jan/2026 no tutorial para iniciantes.

Permissões são a segunda metade da segurança. O Claude Code trabalha com três níveis simples: allow libera ações seguras sem perguntar toda hora, ask pede confirmação caso a caso, e deny bloqueia de vez. O modo mais indicado para quem está começando é o permission-mode plan, que planeja antes de executar e pede aprovação nos pontos sensíveis. Esse modo e o uso de permissions em JSON aparecem no guia de primeiros passos de 08/abr/2026.

O que colocar em allow, ask e deny

Pense em camadas. Em allow, deixe só leitura e comandos inofensivos do seu dia a dia, como listar arquivos e rodar a suíte de testes do projeto. Em ask, deixe tudo que muda arquivos, instala dependências ou roda scripts que você ainda não conhece. Em deny, trave sem exceção o arquivo .env e qualquer padrão de chave, além de comandos destrutivos como rm -rf e push com force. Essa lista de deny com .env e comandos de remoção e envio forçado é o padrão seguro citado nos materiais de abril e janeiro de 2026.

Na dúvida, escolha a opção mais restritiva. É mais rápido responder um ask a mais do que recuperar um arquivo apagado ou uma chave exposta. Com o tempo você move um comando de ask para allow quando percebe que ele é repetitivo e seguro no seu contexto. O caminho inverso também vale: se algo deu medo, volte para ask ou deny na hora.

Uma dica simples para não travar: revise permissões uma vez por semana no começo. Abra /permissions, leia a lista em voz alta e pergunte para cada item se ele precisa mesmo rodar sem avisar. Se a resposta for não sei, deixe em ask. Essa revisão de dois minutos mantém o ambiente seguro enquanto seu repertório cresce.

Um modelo mínimo para copiar a ideia

Um CLAUDE.md inicial pode ter quatro blocos curtos: contexto do projeto, comando de teste, estilo de resposta e limites. Contexto diz o que o projeto é em uma frase. Teste diz o comando exato para validar. Estilo pede respostas curtas e diff pequeno por vez. Limites listam o que nunca fazer sem permissão explícita. Rode /init para gerar a base e depois edite para deixar menor, não maior. Arquivo curto é mais fácil de revisar e menos propenso a instruções contraditórias.

Para exemplos prontos e a configuração de permissions em JSON, siga o satélite dedicado: CLAUDE.md e permissões seguras.

A comparação direta ajuda a escolher sem brigar com as ferramentas. Cursor é lembrado pelo autocomplete forte dentro do editor, que completa o que você está digitando. Copilot é lembrado por sugestões de código durante a escrita, também dentro do fluxo de digitação. Claude Code é um agente autônomo que recebe um objetivo, lê o projeto, propõe um plano e executa passos com sua aprovação. Essa distinção entre autocomplete, sugestão e agente autônomo organiza bem a decisão.

Na prática, muita gente não escolhe um só. O combo os dois funciona bem: editor com autocomplete para velocidade de digitação e agente no terminal para tarefas que atravessam arquivos, como entender um módulo, criar uma mudança em vários pontos e preparar um commit para revisão. Essa ideia de combo e as dicas de uso com /cost, /review e /pr aparecem nas 10 dicas publicadas em 16/mai/2026 no tutorial com dicas práticas.

Quando usar cada um

Use autocomplete e sugestão quando você já sabe o que fazer e quer digitar mais rápido, como completar funções e testes simples. Use o agente quando precisa investigar antes de agir, como descobrir onde um erro nasce ou aplicar a mesma mudança em vários arquivos com coerência. Se a tarefa é grande, quebre em pedidos pequenos para o agente em vez de pedir tudo de uma vez. Pedidos menores geram diffs menores, que são mais fáceis de revisar e desfazer.

Para ver cenários lado a lado, com pontos fortes e limites de cada opção, abra o comparativo do cluster: Claude Code vs Cursor vs Copilot.

Errar no começo é normal, mas estes cinco se repetem tanto que vale decorar a correção. Eles aparecem de formas parecidas no tutorial de 28/jan/2026 no tutorial para iniciantes, nos 5 erros do guia de primeiros passos de 08/abr/2026 e nos 3 tropeços do guia completo para começar de 27/abr/2026.

1. Rodar no diretório home em vez do projeto

Abrir o agente na pasta home dá acesso amplo demais e mistura arquivos pessoais com código. A correção é simples: entre na pasta do projeto antes de começar e confirme o caminho com o comando do sistema. Se já abriu no lugar errado, use /clear, feche, entre na pasta certa e recomece. Essa regra evita que uma instrução vaga atinja arquivos fora do escopo.

2. Pedir uma funcionalidade gigante de uma vez

Pedir construa o sistema inteiro gera uma resposta longa, difícil de revisar e fácil de quebrar. Quebre em passos que caibam em um diff legível: primeiro mapear, depois mudar um arquivo, depois testar, depois seguir. Se o plano passar de três passos, peça para dividir. Diffs pequenos protegem seu tempo de revisão.

3. Pular as perguntas que o agente faz

Quando o agente pergunta qual arquivo, qual comportamento esperado ou se pode rodar um comando, ele está pedindo o contexto que falta. Responder com pressa ou mandar fazer de qualquer jeito transfere o risco para você. Responda curto e direto, com o nome do arquivo e o resultado esperado. Boas respostas geram mudanças melhores na primeira tentativa.

4. Trabalhar sem git ou fora de um branch

Sem git não há como comparar, voltar ou provar o que mudou. Antes de qualquer pedido de edição, confirme que o repositório existe e crie um branch de prática ou de tarefa. Revise o diff antes de cada commit e escreva mensagens claras. Se o diff veio grande sem motivo, peça para refazer em partes menores.

5. Autorizar tudo para andar mais rápido

Liberar todos os comandos para evitar confirmações parece produtivo, mas remove a trava que protege .env, chaves e comandos destrutivos. Mantenha permission-mode plan no início, com .env em deny e rm -rf e push com force também em deny. Mova para allow só o que é repetitivo e seguro, como rodar testes. Segurança aqui é velocidade, porque evita retrabalho.

Se você cometeu um desses hoje, não recomece do zero. Volte para o branch, revise o diff, ajuste o CLAUDE.md e rode o próximo pedido menor. O progresso no Claude Code vem de ciclos curtos e revisados, não de um comando heroico.

Um jeito prático de fixar isso é transformar cada erro em uma trava. Errou a pasta? Crie o hábito de confirmar o caminho antes de abrir o agente. Pediu grande demais? Defina que todo pedido passa de três passos precisa ser dividido. Pulou pergunta? Responda primeiro, execute depois. Sem git? Nada de edição antes do branch. Liberou tudo? Volte para plan e refaça a lista de deny. Em uma semana, essas travas viram rotina.

Preciso saber programar para usar o Claude Code?

Não precisa ser profissional, mas ajuda saber o básico de arquivos, pastas e terminal. Se você sabe entrar em uma pasta, listar arquivos e abrir um projeto no editor, já dá para seguir este guia. Comece por leitura e explicação, peça glossário quando um termo travar, e avance para edições pequenas com diff revisado. O vocabulário cresce com o uso, sem pressa.

O plano gratuito inclui o Claude Code?

Não. O plano gratuito não inclui o Claude Code, então o acesso pede Pro, Max, Team, Enterprise, Console ou Bedrock, conforme o resumo publicado em 14/jul/2026 no guia sobre o que é Claude Code. Se você está no free, o bloqueio não é erro de instalação. Verifique o plano da conta, faça login com a conta certa e use /doctor para confirmar o ambiente.

Onde posso usar o Claude Code?

Nas 7 superfícies citadas neste guia: CLI no terminal, VS Code, JetBrains, app desktop, web, Slack e CI para automação. Para começar, use a CLI em um projeto com git. Depois leve o fluxo para o editor que você já usa. A lista aparece no guia sobre o que é Claude Code, 14/jul/2026.

Quais comandos ajudam a revisar e retomar com segurança?

Use /clear para limpar o contexto, /compact para resumir conversas longas, revise sempre o diff antes do commit, e use claude -p para pedidos únicos fechados. Para continuar de onde parou, use -c e -r em vez de repetir tudo. A base desses comandos está no guia oficial de início rápido, com o uso de one-shot detalhado no guia completo para começar de 27/abr/2026.

Claude Code do zero se resume a quatro movimentos: instalar pelo canal do seu sistema, entrar com a conta que tem direito, praticar 30 minutos em branch separado com revisão de diff, e travar CLAUDE.md e permissões antes de acelerar. Com isso, você evita os erros que mais assustam iniciantes e ganha confiança para pedir tarefas maiores em partes pequenas.

Quando bater a dúvida no meio do caminho, volte para a pergunta central de cada etapa. Onde estou? O que quero mudar? Como vou conferir? Se as três respostas couberem em frases curtas, o pedido está pronto. Se alguma resposta está vaga, peça explicação antes de pedir mudança. Esse hábito simples mantém o controle com você do início ao fim.

Siga nesta ordem. Primeiro, o passo a passo por sistema: como instalar no Windows Mac e Linux. Depois, o treino guiado: roteiro dos primeiros 30 minutos. Em seguida, a trava de segurança: CLAUDE.md e permissões seguras. Por fim, a escolha de ferramentas: Claude Code vs Cursor vs Copilot.

• guia oficial de início rápido
• tutorial para iniciantes
• tutorial com dicas práticas
• guia de primeiros passos
• guia sobre o que é Claude Code
• guia completo para começar