Como usar o Claude Code do zero
Tutorial em português, conferido na documentação oficial em 14 de outubro de 2026: instalar, fazer login, abrir o primeiro projeto, escrever o CLAUDE.md e dominar os comandos que você vai usar todo dia.

Para usar o Claude Code, instale pelo comando oficial do seu sistema, rode claude dentro da pasta do projeto, faça login com um plano Pro ou Max, crie o CLAUDE.md com /init e peça tarefas em português.
Este é um guia de como usar Claude Code para quem nunca abriu a ferramenta. Tudo aqui foi conferido na documentação oficial da Anthropic em 14 de outubro de 2026. Comando que muda de versão para versão foi checado na fonte, não tirado da memória.
O que é o Claude Code
O Claude Code é a ferramenta de programação com agente da Anthropic. Segundo a documentação, ele lê o seu código, edita arquivos, roda comandos e se integra às suas ferramentas de desenvolvimento. A diferença para um chat comum está nas mãos: em vez de devolver um trecho para você copiar, ele abre o arquivo, altera, executa o teste e lê o erro sozinho.
Ele roda em vários lugares: no terminal (a versão mais completa), em extensões para VS Code e JetBrains, num aplicativo de desktop e no navegador, em claude.ai/code. Este tutorial de Claude Code foca no terminal, porque é onde todos os recursos aparecem.
O que você precisa antes de instalar
- Sistema: macOS 13 ou mais novo, Windows 10 versão 1809 ou mais novo, Ubuntu 20.04+, Debian 10+ ou Alpine 3.19+.
- Máquina: 4 GB de RAM ou mais, processador x64 ou ARM64 e internet.
- Conta paga: a documentação diz que o Claude Code exige plano Pro, Max, Team, Enterprise ou conta do Console. O plano gratuito do claude.ai não dá acesso. Os valores atualizados estão no guia de preço do Claude Code em reais.
- No Windows, recomendado: o Git for Windows. Sem ele, o Claude Code usa o PowerShell para rodar comandos. Com ele, usa o Git Bash.
Como instalar o Claude Code no Windows, Mac e Linux
O método recomendado pela Anthropic é a instalação nativa, que se atualiza sozinha em segundo plano. Abra o terminal e cole o comando do seu sistema.
macOS, Linux e WSL
curl -fsSL https://claude.ai/install.sh | bash
Windows (PowerShell)
Se o prompt começa com PS C:\, você está no PowerShell:
irm https://claude.ai/install.ps1 | iex
Windows (CMD)
Se o prompt mostra só C:\, sem o PS, é o CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Não precisa abrir como administrador. Prefere gerenciador de pacotes? Existem alternativas oficiais, com uma ressalva: elas não se atualizam sozinhas por padrão.
brew install --cask claude-code
winget install Anthropic.ClaudeCode
npm install -g @anthropic-ai/claude-code
O pacote do npm pede Node.js 22 ou mais novo, e a documentação avisa para nunca usar sudo npm install -g.
Confirme que instalou
Feche o terminal, abra um novo e rode:
claude --version
claude doctor
O primeiro mostra a versão. O segundo faz um diagnóstico da instalação e das configurações sem abrir sessão.
Login e primeiro projeto
Entre na pasta do projeto e chame o Claude Code:
cd caminho/do/seu-projeto
claude
Na primeira vez, ele abre o navegador para você entrar na conta da Anthropic. Depois disso, a sessão interativa abre no terminal. Para trocar de conta mais tarde, use /logout e /login.
Não comece pedindo código. Comece pedindo entendimento:
o que esse projeto faz? quais pastas importam e como eu rodo ele?
Ele lê os arquivos e responde. Só depois peça a primeira mudança, pequena e verificável: "corrige o erro que aparece quando rodo npm test e roda os testes de novo no final". Pedido com critério de pronto rende muito mais que "melhora o código".
Três atalhos que valem decorar no primeiro dia: @ seguido do nome menciona um arquivo; ! no começo da linha roda um comando de terminal direto; Esc interrompe o Claude no meio da tarefa sem perder o que ele já fez.
O que é o CLAUDE.md e como escrever o seu
O CLAUDE.md é um arquivo de texto que o Claude Code lê no começo de toda sessão. É ali que mora o que ele não consegue adivinhar lendo o código: comando de build, padrão de nome, regra do time, o que nunca fazer.
Rode /init e ele gera um primeiro rascunho analisando o projeto. Se o arquivo já existir, ele sugere melhorias em vez de sobrescrever. Os lugares onde o arquivo pode ficar:
| Arquivo | Vale para | Vai para o Git? |
|---|---|---|
./CLAUDE.md ou ./.claude/CLAUDE.md | Todo mundo que trabalha no projeto | Sim |
./CLAUDE.local.md | Só você, só neste projeto | Não (coloque no .gitignore) |
~/.claude/CLAUDE.md | Só você, em todos os projetos | Não |
A documentação de memória recomenda manter cada CLAUDE.md abaixo de 200 linhas. Arquivo longo gasta contexto e faz o Claude ignorar regras. Para cada linha, pergunte: "se eu tirar isso, ele erra?". Se não erra, corte. Instrução que só vale às vezes vira skill, e o guia de skills do Claude Code mostra como criar uma.
Um exemplo enxuto:
# Projeto
- Site em Astro. Rodar com npm run dev, testar com npm test.
- Textos do site em português do Brasil, sem travessão.
# Regras
- Nunca editar arquivos dentro de dist/.
- Antes de dizer que terminou, rodar npm run build e mostrar o resultado.
Dá para importar outro arquivo com @caminho/do/arquivo.md. O /memory abre os CLAUDE.md para edição e liga ou desliga a memória automática, em que o próprio Claude anota o que aprendeu com as suas correções.
Comandos do Claude Code mais úteis
Digite / dentro da sessão para ver a lista completa. Estes são os comandos do Claude Code que você vai usar na prática, com base na referência oficial de comandos:
| Comando | O que faz | Quando usar |
|---|---|---|
/init | Cria o CLAUDE.md analisando o projeto | Primeira sessão em qualquer pasta |
/clear | Começa conversa nova com contexto vazio | Ao trocar de tarefa |
/compact | Resume a conversa para liberar espaço | Sessão longa na mesma tarefa |
/context | Mostra quanto do contexto está ocupado | Quando ele começa a esquecer coisas |
/model | Troca o modelo de IA | Tarefa simples (modelo rápido) ou difícil (modelo forte) |
/plan | Entra no modo de planejamento | Mudança grande, antes de mexer em arquivo |
/permissions | Gerencia o que pode rodar sem perguntar | Liberar comandos seguros, bloquear perigosos |
/rewind | Volta conversa e código a um ponto anterior | Quando a última mudança piorou tudo |
/resume | Retoma uma conversa anterior | Continuar o trabalho de ontem |
/usage | Mostra custo da sessão e limites do plano | Acompanhar consumo (o /cost é atalho dele) |
/mcp | Gerencia conexões com servidores MCP | Ligar ferramentas externas |
/doctor | Diagnostica instalação, configuração e CLAUDE.md | Algo estranho aconteceu |
/btw | Pergunta paralela que não entra no histórico | Tirar dúvida rápida sem poluir a sessão |
Os comandos de barra também podem ser seus: um arquivo em .claude/skills/nome/SKILL.md vira /nome. E o MCP conecta o Claude Code a Notion, Figma, banco de dados e outras ferramentas, assunto do guia de MCP no Claude Code.
Modos de permissão: quanto o Claude pode fazer sem perguntar
O modo de permissão define o que roda sem a sua aprovação. Você alterna entre eles com Shift+Tab durante a sessão ou escolhe na largada com claude --permission-mode nome-do-modo.
| Modo | O que roda sem perguntar | Para quê |
|---|---|---|
Manual (default) | Só leitura | Aprovar cada ação, trabalho sensível |
acceptEdits | Leitura, edição de arquivos e comandos simples de pasta | Iterar num código que você está revisando |
plan | Leitura; edição só depois de você aprovar o plano | Explorar antes de mudar |
auto | Tudo, com um segundo modelo checando o que é arriscado | Tarefas longas sem ficar clicando em "sim" |
dontAsk | Só ferramentas pré-aprovadas; o resto é negado | Scripts e CI |
bypassPermissions | Tudo, sem checagem | Só em contêiner ou máquina virtual isolada |
Atenção a uma mudança recente: segundo a página de modos de permissão, a partir da versão 2.1.283 o modo auto é o ponto de partida padrão nas sessões de terminal e VS Code. Se você prefere aprovar tudo enquanto aprende, comece com claude --permission-mode default. Regras de bloqueio criadas em /permissions valem em qualquer modo.
Boas práticas que a própria Anthropic recomenda
- Dê um jeito de ele conferir o trabalho. Teste, build, print para comparar. A página de boas práticas diz que essa é a diferença entre uma sessão que você vigia e uma que você pode deixar rodando.
- Explore, planeje, depois programe. Para mudança que mexe em vários arquivos, use o modo plan primeiro. Se dá para descrever a mudança em uma frase, pule o plano.
- Seja específico. Diga qual arquivo, qual cenário e como saber que ficou pronto.
- Cuide do contexto. A janela de contexto enche rápido e o desempenho cai quando ela está cheia. Use
/clearentre tarefas sem relação. - Corrija cedo. Viu que ele foi para o lado errado?
Escna hora e redirecione.
Erros comuns de quem está começando
| Erro | O que acontece | Como resolver |
|---|---|---|
| "claude" não é reconhecido logo depois de instalar | O terminal antigo não enxerga o novo PATH | Feche e abra outro terminal; se continuar, rode claude doctor |
| "The token '&&' is not a valid statement separator" | Você colou o comando do CMD no PowerShell | Use o comando com irm |
| "'irm' is not recognized" | Você colou o comando do PowerShell no CMD | Use o comando com curl e install.cmd |
| Tentar entrar com o plano gratuito | O plano gratuito não inclui o Claude Code | Assinar Pro ou Max, ou usar conta do Console |
| Uma sessão para tudo | Contexto cheio de assunto misturado, respostas piores | /clear a cada tarefa nova |
| Corrigir a mesma coisa três vezes | O histórico fica cheio de tentativas erradas | Depois de duas correções, /clear e um pedido melhor |
| CLAUDE.md gigante | Regras importantes se perdem no meio | Ficar abaixo de 200 linhas e podar sempre |
| Confiar sem verificar | Código que parece certo e quebra no caso extremo | Pedir para ele rodar o teste e mostrar a saída |
Um último cuidado: o /rewind só desfaz o que o Claude alterou pelas ferramentas de arquivo dele. O que rodou por comando de terminal não volta. Git continua obrigatório.
Ainda escolhendo ferramenta? A comparação Claude Code vs Cursor mostra quando cada uma faz mais sentido.
Do tutorial ao trabalho de verdade: onde entra o kntriaOS
Tudo o que você viu aqui (CLAUDE.md, comandos de barra, hooks, agente revisor) é matéria-prima. Montar isso para produzir marketing de vários clientes leva tempo. O kntriaOS: agência de marketing no Claude Code é essa montagem pronta: um CLAUDE.md com as regras lidas em toda sessão, 14 comandos (do /novo-cliente ao /aprender), 14 guias, dois hooks (um carrega o cérebro ao abrir a sessão, outro checa a qualidade a cada arquivo escrito) e o agente revisor-entrega, que aprova ou reprova antes do cliente ver.
Você cadastra cada cliente uma vez, com voz, cores e produto, e passa a pedir carrossel em PNG, calendário do mês, proposta e site na voz daquela empresa. Custa R$ 29,90 por mês e roda dentro do seu Claude Code, que exige uma assinatura Pro ou Max contratada por você, à parte. Quer ver um caso prático? O guia de como criar carrossel com IA mostra o caminho do código, o mesmo que o comando /criar-carrossel usa. E se a sua empresa precisa de IA em outro processo, a kntrIA também faz marketing digital com IA e projetos sob medida.
Perguntas frequentes
Claude Code é de graça?
Não. A documentação oficial informa que o plano gratuito do claude.ai não inclui o Claude Code. Ele exige plano Pro, Max, Team, Enterprise ou uma conta do Console com cobrança por uso de API.
Preciso saber programar para usar o Claude Code?
Ajuda, mas não é obrigatório. Você conversa em português e ele lê arquivos, escreve código e roda comandos. O que você precisa é saber abrir um terminal, ler o que ele propõe e conferir o resultado.
Qual comando instala o Claude Code no Windows?
No PowerShell, o comando oficial é irm https://claude.ai/install.ps1 | iex. O CMD tem um comando próprio, e o WinGet também funciona com winget install Anthropic.ClaudeCode.
O Claude Code funciona em português?
Funciona. Você pode escrever os pedidos e o CLAUDE.md em português, e ele responde no mesmo idioma. Os nomes dos comandos de barra continuam em inglês, como /init e /clear.
Qual a diferença entre /clear e /compact?
O /clear começa uma conversa nova com o contexto vazio. O /compact mantém a mesma conversa, mas resume o que já aconteceu para liberar espaço.
Como desfazer uma alteração que o Claude Code fez?
Aperte Esc duas vezes com o campo vazio ou rode /rewind para voltar a um ponto anterior da conversa e do código. Isso só cobre edições feitas pelas ferramentas de arquivo do Claude, então mantenha o Git em dia.
Continue no assunto
Quer pular a parte de montar tudo do zero?
O kntriaOS chega com CLAUDE.md, 14 comandos, hooks e um agente revisor prontos para produzir marketing para vários clientes. Você instala, cadastra o cliente e produz no mesmo dia.