Primeiro Uso: Executando o Primeiro Exemplo

📚 Navegação da Série: O artigo anterior 06 Plano de Codificação: Planos de Assinatura e Faturamento ajudou você a entender as questões financeiras. Este artigo é para colocar a mão na massa — desde abrir o terminal até executar a primeira tarefa com sucesso, proporcionando o seu primeiro "sucesso".

Irmãos, os artigos anteriores foram todos preparação — instalação concluída, login feito, plano escolhido.

A ferramenta está lá, mas você provavelmente ainda está um pouco inseguro no coração: Como exatamente uso essa coisa? Abro o terminal, e depois?

Para ser sincero, muitas pessoas quando executam o Claude Code pela primeira vez, olham para o cursor por quase um minuto, sem saber o que digitar. Com medo de estragar o código por dizer a coisa errada.

Não fique nervoso. Hoje vamos passar pelo processo mais simples: criar um pequeno projeto com apenas algumas linhas de código, deixar o Claude lê-lo e entendê-lo primeiro, e depois pedir para ele ajudar a alterar uma linha. Em menos de cinco minutos, você terá a sua primeira experiência de sucesso de "o Claude me ajudou a alterar o código e alterou corretamente". Isso é o suficiente — uma vez que você passar pelo processo uma vez, o resto fluirá naturalmente.

Depois de ler este artigo, você obterá:

• Um fluxo de ações completo, desde abrir o terminal até executar a primeira tarefa com sucesso, basta seguir os comandos
• Entender o que é cada parte daquela "tela de boas-vindas" após a inicialização do Claude Code
• Uma prática de nível hello world que funciona e fornece a saída esperada
• Vários lembretes importantes para você "não cair em armadilhas na primeira vez" (como aprovar permissões, como desfazer alterações incorretas)

---

01 Primeiro Crie um "Projeto de Brinquedo"

Conclusão primeiro: No primeiro uso, não use seu projeto oficial para praticar, crie um projeto de brinquedo.

Por que? Porque projetos oficiais têm muitos arquivos e dependências complexas, o Claude passará muito tempo lendo no início e você não conseguirá ver claramente o que ele fez. Um projeto de brinquedo tem apenas dois ou três arquivos, o que ele alterar você entenderá de relance — isso é para aprendizado.

Analogia: Aprender a dirigir primeiro em um espaço vazio. Ninguém entra na rodovia assim que pega a carteira de motorista. Primeiro, encontre um espaço vazio, familiarize-se com o acelerador e o freio, saiba quanto girar o volante para o carro virar. O projeto de brinquedo é o seu espaço vazio — não importa se estragar, basta criar um novo.

Para quem nunca tocou na linha de comando, todos que praticam com o projeto da empresa na primeira vez ficam em pânico — só a rolagem da tela durante os segundos em que o Claude lê os arquivos é o suficiente para suar as palmas das mãos. Mude a abordagem, primeiro crie um pequeno arquivo com três linhas de código, passe por todo o processo em cinco minutos, e a confiança virá imediatamente.

Abra o seu terminal (no Mac é "Terminal / Terminal", no Windows recomenda-se Git Bash ou PowerShell) e digite as seguintes linhas:

mkdir hello-claude
cd hello-claude

O significado destas duas linhas é: criar uma nova pasta chamada hello-claude e, em seguida, entrar nela. mkdir = make directory (criar pasta), cd = change directory (entrar na pasta).

Em seguida, crie o arquivo Python mais simples. Mac / Linux usam:

echo 'def add(a, b):
    return a + b' > main.py

No PowerShell do Windows, escrever várias linhas com echo é um pouco incômodo, você pode usar o Bloco de Notas diretamente para criar um novo main.py, colar as duas linhas abaixo e salvar:

def add(a, b):
    return a + b

💡 Resumo em uma frase: Ao usar o Claude Code pela primeira vez, crie um projeto de brinquedo de duas ou três linhas primeiro como um "campo de prática", se algo der errado, basta reconstruí-lo, sem pânico e sem mãos trêmulas.

---

02 Inicie o Claude, Entenda a Tela de Boas-vindas

O projeto está criado, agora inicie o Claude Code dentro da mesma pasta. Confirme se o seu terminal está atualmente no diretório hello-claude (se você acabou de usar cd para entrar, você ainda está lá), digite:

claude

Atenção: Você deve iniciar o claude no diretório do projeto, não o inicie vazio na área de trabalho ou no diretório principal. Porque o Claude Code trata o diretório onde você está atualmente como a área de trabalho — onde você inicia, é onde ele lê os arquivos. Esta é a primeira armadilha mais comum para iniciantes: iniciar no diretório principal, depois perguntar "o que este projeto faz", o Claude fica confuso, porque o diretório principal não é um projeto.

Analogia: Convidar um mestre de obras para ir à sua casa, você tem que levá-lo primeiro à casa que será reformada. Você não pode ficar gesticulando no portão do condomínio, ele precisa estar dentro da casa para saber qual parede deve ser derrubada e onde passar os fios. Usar cd para entrar no diretório do projeto e depois iniciar o claude, é "levar o mestre para dentro de casa".

Após a inicialização, você verá uma tela de boas-vindas, de acordo com a documentação oficial, ela contém as informações da sua sessão, conversas recentes e as últimas dicas de atualização. Para iniciantes, você só precisa reconhecer três coisas:

O que você vê	O que é	O que você deve fazer
A caixa de entrada / cursor na parte inferior	Onde você fala com o Claude	Digite diretamente, pressione Enter para enviar
/help nas dicas	Ver todos os comandos disponíveis	Digite-o quando esquecer de um comando
/resume nas dicas	Continuar uma conversa anterior	Ignore na primeira vez de uso

A caixa de entrada é o campo de batalha principal. Você não precisa aprender nenhuma sintaxe especial, trate-a como uma caixa de bate-papo que pode ler o seu código — basta fazer seus pedidos em linguagem simples.

Se quiser confirmar que você entrou no lugar certo, primeiro digite a pergunta mais simples:

O que este projeto faz?

O Claude lerá os arquivos no diretório atual (aqui é o main.py) por conta própria e dirá a você o que o projeto faz. Durante todo o processo, você não precisa "alimentá-lo" manualmente com os arquivos — a documentação oficial afirma explicitamente: O Claude Code lerá os arquivos do projeto de forma autônoma conforme necessário, você não precisa adicionar o contexto manualmente.

💡 Resumo em uma frase: Inicie com claude no diretório do projeto, reconheça as duas coisas "caixa de entrada + /help" e você estará pronto para começar; ele lerá os arquivos por conta própria, basta você fazer os pedidos em linguagem simples.

---

03 Deixe o Claude Entender o Código Primeiro

A primeira tarefa real, não é pedir para ele alterar o código, mas pedir para ele explicar o código.

Por que explicar primeiro? Dois motivos: primeiro, para você confirmar que o Claude realmente leu seus arquivos (em vez de estar inventando coisas); segundo, tarefas de explicação têm risco zero — ele apenas lê e fala, não tocará em uma única palavra sua, o mais adequado para o primeiro teste.

Analogia: No primeiro dia de um novo colega, você não joga o módulo principal diretamente para ele refatorar, mas primeiro pede que ele "leia o código e me diga o que esta parte faz". Ao ouvi-lo explicar, você saberá se ele entendeu ou não, e se é confiável. Pedir ao Claude para explicar o código, é essa ação de "primeiro dia de trabalho".

Na caixa de entrada, digite:

Explique o que este arquivo main.py está fazendo, usando uma forma que um iniciante possa entender

Pressione Enter. O Claude lerá o main.py e, em seguida, dará uma explicação em linguagem simples, algo como: Aqui é definida uma função add, que recebe dois parâmetros a e b, e retorna o resultado da soma deles.

Passar por esta etapa com sucesso significa que duas coisas são verdadeiras: O Claude Code está instalado corretamente, o status de login é normal, e ele está realmente lendo seus arquivos reais. Com as fundações firmes, só então você pode pedir a ele para fazer alterações.

Lembre-se das instruções para o Claude Code em três categorias, e você terá uma ideia melhor ao usá-lo no futuro:

Tipo de Instrução	O que faz	Exemplo	Risco
Explicativa	Pede que ele leia e explique a você	"Explique este código"	Risco zero, não altera arquivos
Modificação	Pede que ele altere o código existente	"Refatore esta função"	Alterará arquivos, requer aprovação
Geração	Pede que ele escreva algo novo	"Adicione um caso de teste"	Criará / alterará arquivos, requer aprovação

💡 Resumo em uma frase: Para a primeira tarefa, use o tipo "Explicativa" para testar a água — confirme que ele leu seus arquivos, as fundações estão firmes, e então peça para ele agir.

---

04 Peça ao Claude para Alterar uma Linha de Código (Chave: Ele perguntará primeiro)

Agora chegou o clímax: deixe o Claude realmente alterar o código uma vez.

Continuando a conversa acima, digite diretamente:

Adicione anotações de tipo a esta função e adicione o tratamento básico de erros

Neste momento vem a cena mais crucial — o Claude não mudará o seu arquivo diretamente. Ele irá:

1. Encontrar o arquivo a ser alterado (aqui é o main.py)
2. Mostrar como ele planeja alterar o arquivo, na forma de um diff (comparação de diferenças)
3. Parar e esperar pela sua aprovação
4. Você clica em "Concordar", e ele finalmente salva no disco

Esta é uma regra de ferro repetidamente enfatizada na documentação oficial:

O Claude Code sempre solicita permissão antes de modificar os arquivos. Você pode aprovar alterações individuais ou ativar o modo "Aceitar tudo" para esta sessão.

Analogia: O estagiário pergunta antes de agir. Um estagiário confiável não alterará o código de produção sem o seu consentimento — ele virá com o rascunho alterado: "Chefe, eu quero alterar assim, o que acha?" Você balança a cabeça e só então ele age. O Claude Code por padrão é como este estagiário que "pergunta primeiro antes de agir".

Você verá um prompt pedindo para você escolher, geralmente significando estas opções:

Sua Escolha	Efeito	Quando usar
Concordar / Yes	Aplica esta alteração	Entendeu o diff, acha que não há problema
Concordar, e não perguntar mais nesta sessão	Alterações subsequentes são aplicadas automaticamente	Você já confia nele e quer acelerar
Recusar / No, e dizer o motivo a ele	Não alterar, você pode adicionar requisitos	Há algo no diff que você não deseja

Na primeira vez, é altamente recomendável que você simplesmente escolha "Concordar" honestamente, não tenha pressa em abrir o "Aceitar tudo". Para ser sincero, quando você começa, é mais fácil buscar a conveniência, abrindo a permissão mais frouxa logo no início (o --dangerously-skip-permissions que será discutido nos capítulos seguintes, como o nome sugere "pular permissões perigosamente"), o resultado é que ele altera cinco ou seis arquivos de uma vez sem você olhar com cuidado, e quando você reage, já não consegue distinguir quais alterações você queria e quais ele adicionou por conta própria. A lição é apenas uma: quanto menos familiar você for, mais você deve deixá-lo parar a cada passo.

Uma pequena dica para entender o diff: O vermelho / que começa com - é a linha antiga excluída, o verde / que começa com + é a nova linha adicionada. Seu main.py provavelmente mudará de:

def add(a, b):
    return a + b

Para algo assim (a maneira específica que o Claude escreve pode ser ligeiramente diferente, desde que o significado seja consistente):

def add(a: float, b: float) -> float:
    if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
        raise TypeError("a e b devem ser números")
    return a + b

Anotações de tipo foram adicionadas (a: float) e o tratamento básico de erros também foi adicionado (se não for passado um número, relata um erro). Neste momento, você concluiu sua primeira "alteração de código colaborativa homem-máquina".

💡 Resumo em uma frase: Antes de o Claude alterar um arquivo, ele sempre pergunta primeiro — na primeira vez escolha "Concordar" honestamente, entenda o diff e concorde, não tenha pressa para abrir a automação total.

---

05 O que fazer se alterar errado: Duas "Pílulas de Arrependimento"

O maior medo do iniciante é: E se ele alterar errado, estragar tudo, e eu não conseguir ver, como resolvo a situação?

Não se preocupe, existem duas pílulas de arrependimento, e elas são muito úteis.

A primeira: Diga diretamente na conversa "altere de volta". O Claude se lembra do que fez nesta sessão, se você não estiver satisfeito, diga a ele diretamente em linguagem simples:

Não estou satisfeito com a alteração que você acabou de fazer, altere de volta para o que era antes

Ele reverterá a alteração. Analogia: Dizer a um colega "aquela versão que você acabou de fazer não serve, volte para a anterior" — você não precisa voltar e corrigir linha por linha manualmente.

A segunda: Usar pontos de verificação (Checkpoint) para reverter. Este é o mecanismo de "salvamento de jogo" do Claude Code — ele gravará automaticamente o estado antes de cada edição de arquivo, você pode voltar para ele com um clique.

Analogia: Salvar e carregar em jogos. Você salvou antes da batalha contra o chefe, se perder, não precisa começar tudo de novo, basta carregar para voltar ao ponto de salvamento. Os checkpoints são o salvamento que o Claude faz silenciosamente para você antes de agir.

Como acionar? De acordo com a documentação oficial:

/rewind

Ou quando a caixa de entrada estiver vazia, pressione a tecla Esc duas vezes seguidas, e o menu de reversão aparecerá.

⚠️ Um detalhe (mencionado explicitamente na documentação oficial): se houver texto na caixa de entrada, pressionar Esc duas vezes seguidas limpará o texto, e não abrirá o menu de reversão. Então, para reverter, primeiro certifique-se de que a caixa de entrada esteja vazia.

Há mais uma coisa a esclarecer — checkpoints só podem desfazer as alterações de arquivo feitas pelo Claude por meio de suas ferramentas de edição, e não são equivalentes ao Git. O conselho oficial é muito apropriado:

Trate os checkpoints como "desfazer local", e o Git como "histórico permanente".

Isso significa que os checkpoints são adequados para arrependimentos imediatos, como "ops, este passo quebrou, deixe-me voltar"; o progresso realmente importante, ainda precisa ser salvo usando commits do Git (como usar o Git será abordado em um artigo separado mais tarde).

Pílula de Arrependimento	Como Usar	Cenário Adequado	Limitações
Dizer "altere de volta" na conversa	Digite diretamente para dizer ao Claude	Logo após a alteração, quando há apenas um ou dois pontos de insatisfação	Depende de ele entender o seu significado
Checkpoint /rewind	Digite /rewind ou pressione Esc duas vezes na caixa de entrada vazia	Quer voltar com precisão para um determinado estado	Apenas gerencia os arquivos alterados pelo Claude, não é Git

💡 Resumo em uma frase: Não entre em pânico se algo for alterado de forma incorreta, um "altere de volta" + o checkpoint /rewind servem de garantia; mas para o progresso real, você deve entregá-lo ao Git para salvar.

---

06 Mão na massa: Execute sua primeira tarefa em cinco minutos

Apenas ler não serve. A seguir, vamos encadear as seções anteriores em um processo completo que você pode digitar e obter a saída esperada. Abra o terminal e siga.

Primeiro Passo: Criar o Projeto de Brinquedo (Mac / Linux)

mkdir hello-claude
cd hello-claude
echo 'def add(a, b):
    return a + b' > main.py

Usuários do Windows: digitem mkdir hello-claude e cd hello-claude da mesma forma, crie main.py com o Bloco de Notas e cole as duas linhas de Python.

Expectativa: Existe um arquivo main.py na pasta hello-claude, e o conteúdo são as duas linhas da função add. Você pode digitar ls (no Windows use dir) para confirmar que o arquivo está lá.

Segundo Passo: Iniciar o Claude Code

claude

Expectativa: A tela de boas-vindas aparece, com a caixa de entrada e o cursor na parte inferior. Se você for solicitado a fazer login, significa que as etapas de login anteriores não foram concluídas, volte e repita o processo de login do artigo 02.

Terceiro Passo: Peça para ele explicar o código

Na caixa de entrada, digite:

Explique o que este arquivo main.py está fazendo, usando uma forma que um iniciante possa entender

Expectativa: O Claude lerá main.py e usará uma linguagem simples para dizer que esta é uma função para "somar dois números". Ver que ele descreveu com precisão a função add = sucesso.

Quarto Passo: Peça para ele alterar o código, e aprove

Adicione anotações de tipo a esta função e adicione o tratamento básico de erros

Expectativa: O Claude fornecerá um trecho de diff (linha antiga com - vermelho, nova linha com + verde), e então parará esperando a sua escolha. Depois de entender, escolha "Concordar / Yes".

Quinto Passo: Confirme que a alteração foi aplicada

Saia do Claude (digite exit ou pressione Ctrl+D), volte ao terminal para ver o arquivo:

cat main.py

(No PowerShell do Windows use type main.py)

Expectativa: As anotações de tipo (como a: float) e o tratamento de erros (raise TypeError(...)) apareceram no main.py. Ele corresponde ao diff que você acabou de aprovar = todo o processo funcionou, parabéns!

⚠️ Caso você fique preso em um erro de permissão (como ver Error: EACCES: permission denied no Mac / Linux), a correção específica varia dependendo do cenário, ela será detalhada no artigo de "Problemas Frequentes" mais tarde, apenas saiba que essa armadilha existe por enquanto.

💡 Resumo em uma frase: Siga os cinco passos, executar o processo com sucesso é mais importante do que entendê-lo — obtendo a primeira experiência de sucesso de "o Claude me ajudou a alterar o código e alterou corretamente", o resto fluirá naturalmente.

---

07 Resumo

Neste artigo você fez uma coisa: executou completamente a primeira tarefa do Claude Code — desde a criação do projeto, inicialização, explicação do código, até a alteração do código e aprovação.

Vamos revisar os movimentos centrais:

Passo	Ação	Ponto Chave
Criar projeto	mkdir + cd + criar arquivo	Primeiro use o projeto de brinquedo para praticar
Iniciar	Digite claude no diretório do projeto	Onde você inicia, é lá que ele lê
Explicar	"Explique o arquivo xxx"	Risco zero, primeiro confirme que ele leu o arquivo
Modificar	Use linguagem simples para fazer o pedido	Ele primeiro dá o diff, espera pela sua aprovação e então age
Arrepender-se	"Altere de volta" / /rewind	O checkpoint é um desfazer local, o Git é o histórico permanente

Você agora deve ser capaz de: Abrir o terminal, iniciar o Claude no diretório correto, usar linguagem natural para pedir que ele entenda e altere um trecho de código, entender o diff que ele fornece, e saber como reverter se algo der errado. Este conjunto de ações, é o núcleo mínimo de todo o seu uso subsequente do Claude Code — não importa quão extravagantes sejam os recursos mais tarde, a essência é sempre fazer adições neste loop de "fazer pedido → ver diff → aprovar / reverter".

---

O próximo artigo é o 08 "Integração com VS Code" — O processo de linha de comando está funcionando, mas você provavelmente está mais acostumado a escrever código no editor e consegue ver o diff de forma mais clara. O próximo artigo ensinará como integrar o Claude Code no VS Code, permitindo que ele trabalhe lado a lado com o seu código.

Esta imagem encadeia os cinco passos deste artigo em um fluxo vertical: Criar projeto de brinquedo → Iniciar claude no diretório do projeto → Pedir para ele explicar o código (Verde · Somente leitura, risco zero) → Pedir para ele alterar o código (Destaque Âmbar · Dá o diff primeiro e espera a sua aprovação, ou seja, "pergunta antes de agir") → Usar /rewind para reverter se alterar incorretamente (Destaque Rosa · Pílula de arrependimento "garantida"), os dois destaques são as grades de segurança que os iniciantes devem lembrar com mais atenção.

---

Leitura Recomendada

• Guia de uso do CLAUDE.md: Registre as regras do projeto em sua memória
• Tarefas Paralelas: Faça com que vários Claudes comecem a trabalhar ao mesmo tempo, em vez de fazer fila
• Sistema de Memória (memory): Deixe-o lembrar de você entre as sessões