Depois de instalar e autenticar o Claude Code no capítulo anterior, chegou a hora de usá-lo de verdade. Ao final deste capítulo, você será capaz de abrir uma sessão dentro de um projeto, entender o que a ferramenta faz a cada passo, aprovar ou recusar alterações com segurança, usar os comandos essenciais do dia a dia e retomar uma conversa que ficou pela metade.
Um projeto pequeno para praticar
Para acompanhar os exemplos, vamos usar um projeto minúsculo em Node.js chamado lista-de-tarefas. Ele tem três arquivos: um package.json, um arquivo tarefas.js com funções para adicionar, listar e concluir tarefas, e um arquivo tarefas.test.js com alguns testes. Se preferir, crie algo parecido em qualquer linguagem. A mecânica que vamos aprender é idêntica.
Iniciando a sessão
O Claude Code trabalha sempre a partir da pasta onde foi iniciado. Essa pasta define o que ele enxerga como o projeto. Por isso, o primeiro passo é entrar na raiz do projeto pelo terminal com o comando cd lista-de-tarefas e, em seguida, executar o comando claude, sem nenhum argumento.
Uma tela de boas-vindas aparece com o nome da pasta atual e um campo de texto. Tudo que você digitar nesse campo é enviado como mensagem. Você conversa em linguagem natural, em português mesmo, e ele responde ali no terminal.
Uma observação rápida: na primeira vez em um projeto, é comum ele sugerir o comando /init, que cria um arquivo CLAUDE.md. Por enquanto, ignore essa sugestão. Esse arquivo tem um capítulo inteiro dedicado a ele mais adiante.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
O que acontece por trás de cada resposta
Experimente uma primeira pergunta: o que este projeto faz? Repare que o Claude Code não responde de imediato. Ele anuncia que vai ler alguns arquivos, mostra quais são, e só depois escreve a resposta. Isso revela o funcionamento central da ferramenta: ela age por meio de ferramentas internas. As principais são ler arquivos, buscar texto no projeto, executar comandos no terminal e editar ou criar arquivos.
Ler e buscar são ações seguras e acontecem sem interrupção. Já executar comandos e alterar arquivos são ações que mudam algo, e por isso exigem a sua aprovação. Cada vez que ele quer rodar um comando, como npm test, ou modificar um arquivo, aparece um pedido de confirmação com três opções: aprovar apenas esta vez, aprovar e não perguntar mais para aquela ação, ou recusar. Atenção a essa segunda opção: em geral ela não vale apenas para a sessão atual, ela grava a permissão nas configurações do projeto e continua valendo nas próximas sessões. Use com parcimônia e evite aplicá-la a comandos que apagam arquivos, publicam código ou mexem em ambientes de produção. Se recusar, você pode escrever o motivo, e ele ajusta a abordagem.
Esse comportamento de pedir permissão é o padrão e é o que vamos usar ao longo deste capítulo. As formas de flexibilizar ou restringir essas regras ficam para o capítulo sobre permissões.
Interrompendo e cancelando
Às vezes você percebe no meio do caminho que ele entendeu errado. Pressione a tecla Escape uma vez e a ação atual para imediatamente, mas a conversa continua, e você pode explicar o que realmente queria. Pressionar Escape duas vezes seguidas abre o histórico de mensagens para voltar a um ponto anterior da conversa. Já a combinação Control C cancela o texto que você está digitando e, pressionada duas vezes seguidas, encerra o programa. Guarde a regra: Escape interrompe, Control C encerra.
Os comandos de barra essenciais
Além de mensagens normais, o Claude Code aceita comandos que começam com o caractere barra, chamados slash commands, ou comandos de barra. Eles controlam a ferramenta, não o projeto. Os que você usará desde o primeiro dia são estes:
- /help lista todos os comandos disponíveis e os atalhos de teclado. É a referência rápida para quando você esquecer algo.
- /clear apaga o histórico da conversa e começa do zero, mantendo a sessão aberta na mesma pasta. Use ao trocar de tarefa.
- /compact resume a conversa até aquele ponto em vez de apagá-la. Ele guarda o que importa e libera espaço. Você pode acrescentar uma orientação depois do comando, como pedir que ele mantenha a lista de arquivos alterados.
- /cost mostra quanto a sessão consumiu em tokens e, se você usa chave de API, o valor estimado em dólares. Com assinatura, o valor em dólares não se aplica, e o consumo dentro do plano é consultado por um comando próprio de uso, o /usage, nas versões que o oferecem.
- /config abre um menu de configurações, como tema de cores e notificações. As escolhas são gravadas nos arquivos de configuração do Claude Code, normalmente no arquivo global que fica na sua pasta de usuário, e não necessariamente no settings.json do projeto que você conheceu no capítulo anterior.
- /exit encerra a sessão, com o mesmo efeito de Control C pressionado duas vezes.
Por que /clear e /compact importam tanto? Porque tudo o que foi dito e lido em uma sessão fica na memória de trabalho do modelo, chamada janela de contexto. Ela tem tamanho limitado e, conforme se enche, as respostas ficam mais lentas e menos precisas. Limpar ou compactar com frequência é um hábito simples que melhora a qualidade.
Referenciando arquivos com arroba
O Claude Code é bom em achar arquivos sozinho, mas isso custa tempo e contexto. Quando você já sabe qual arquivo interessa, aponte diretamente digitando arroba seguido do caminho. Ao digitar arroba e as primeiras letras de tarefas, uma lista de sugestões aparece e a tecla Tab completa o nome. Assim, o pedido para explicar a função concluirTarefa em @tarefas.js já chega com o conteúdo do arquivo anexado. Funciona também com pastas: referenciar uma pasta anexa uma visão dos arquivos que ela contém.
Enviando imagens
Você também pode mostrar imagens. Há três formas: arrastar o arquivo da imagem para a janela do terminal, colar da área de transferência com Control V, inclusive no macOS, onde o atalho é Control e não Command, ou simplesmente escrever o caminho do arquivo na mensagem. Vale lembrar que arrastar e soltar depende do terminal que você usa: em alguns é preciso manter Shift pressionado ao arrastar e, em outros, o recurso não funciona, restando colar a imagem ou digitar o caminho. Isso serve para enviar a captura de tela de um erro, o desenho de uma interface ou um diagrama que você quer transformar em código. Nas extensões do VS Code e do JetBrains, apresentadas no capítulo anterior, o processo é o mesmo.
Modo de planejamento e modo de execução
Por padrão, o Claude Code está em modo de execução: ele lê, propõe e, com sua aprovação, altera. Existe outro modo, o modo de planejamento, em que ele só pode ler e pensar. Nele, nada é editado nem executado. O resultado é um plano em texto descrevendo o que ele faria e em que ordem. Você alterna entre os modos pressionando Shift e Tab ao mesmo tempo, e o modo atual aparece indicado logo abaixo do campo de texto. Ao repetir Shift Tab você passa por alguns modos em sequência, incluindo um que aceita edições automaticamente. Por ora, preste atenção apenas aos dois: execução e planejamento. Os demais são explicados no capítulo sobre permissões.
O modo de planejamento é valioso para tarefas com mais de um passo. Você pede, lê o plano, corrige o que discorda e só então volta ao modo de execução e autoriza a implementação. Uma alternativa rápida é escrever na própria mensagem que ele não deve alterar nada ainda e apenas descrever o plano.
O ciclo básico na prática
Agora vamos juntar tudo em um ciclo de quatro passos: pedir, revisar o diff, aprovar ou recusar, e testar. Antes de começar, garanta que o projeto está sob controle de versão e sem alterações pendentes, por exemplo com um git init e um commit inicial: as edições aprovadas são gravadas diretamente nos seus arquivos e a ferramenta não tem um botão de desfazer, então o Git é a sua rede de segurança.
- Pedir. Digite: adicione em @tarefas.js uma função removerTarefa que recebe o identificador e remove a tarefa da lista, lançando um erro se o identificador não existir.
- Revisar o diff. Ele lê o arquivo e propõe uma alteração. Em vez de sobrescrever tudo, mostra um diff, isto é, a comparação entre a versão atual e a proposta: linhas removidas em vermelho, linhas acrescentadas em verde e algumas linhas de contexto ao redor. Leia com atenção. Verifique se a função segue o estilo das vizinhas, se nada foi apagado indevidamente e se o erro é lançado do mesmo jeito que o resto do código faz.
- Aprovar ou recusar. Se estiver bom, aprove. Se não, recuse e diga o motivo, por exemplo pedindo a mesma mensagem de erro usada em concluirTarefa. Ele reformula e apresenta um novo diff. Esse vai e volta curto é normal e sai muito mais barato do que aceitar e consertar depois na mão.
- Testar. Peça que ele rode os testes. Ele solicitará permissão para executar npm test, você aprova, e ele lê a saída. Se algo falhar, ele já propõe a correção. Se quiser também um teste para a função nova, peça agora. A escrita de testes em profundidade fica para outro capítulo, mas o ciclo é o mesmo.
Repita esse ciclo para cada pequena alteração. Pedidos pequenos geram diffs pequenos, e diffs pequenos são fáceis de revisar. Esse é o segredo para manter o controle do código.
Retomando sessões anteriores
Ao fechar o terminal, a conversa não se perde. Ao voltar ao projeto, execute claude --continue, ou a forma curta claude -c, para reabrir a sessão mais recente daquela pasta com todo o histórico. Se você teve várias sessões e quer escolher uma específica, use claude --resume, ou claude -r, que exibe uma lista com data e resumo de cada conversa para você selecionar. Isso é útil quando uma tarefa fica pela metade no fim do dia e você quer continuar exatamente de onde parou.
Recapitulando
Neste capítulo você viu que o Claude Code trabalha a partir da pasta onde é iniciado, age por meio de ferramentas de leitura, busca, execução e edição, e pede aprovação antes de qualquer ação que mude algo. Aprendeu que Escape interrompe uma ação e Control C encerra o programa, conheceu os comandos de barra /help, /clear, /compact, /cost, /config e /exit, e entendeu por que manter a janela de contexto enxuta melhora as respostas. Viu como referenciar arquivos com arroba, enviar imagens, alternar entre o modo de planejamento e o modo de execução com Shift Tab, e retomar sessões com --continue e --resume. Acima de tudo, praticou o ciclo que sustenta todo o resto do livro: pedir, revisar o diff, aprovar ou recusar, e testar.
