Claude Code no macOS: instalação com Homebrew e primeira leitura

Este tutorial mostra como instalar o Claude Code (abre em nova aba) no macOS com Homebrew já configurado e conferir a primeira leitura de uma cópia de projeto. O objetivo é obter um mapa de arquivos, um resumo apoiado em trechos e dúvidas abertas. O exercício é didático e não foi executado; pedir que a ferramenta não edite arquivos nem rode comandos não é uma trava técnica. Você precisará conferir as permissões e eventuais alterações.⁠​‌​​‌​​‌​‌​​​​​‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌​​‌‌​​​‌​​‌‌‌​​‌​​‌‌‌‌‌​​​‌‌​​​‌​​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌​​‌‌​​‌‌​​​‌‌​‌​​​​‌‌​‌‌​​‌‌​​‌‌​​​‌​‌‌​‌​‌‌​​‌​​​​‌‌​​‌​​​‌‌‌​​‌​‌‌​​‌‌​​​‌​‌‌​‌​​‌‌​‌​​​​‌‌​‌‌‌​‌‌​​‌​​​‌‌​​‌‌​​​‌​‌‌​‌​​‌‌‌​​‌​​‌‌​‌‌​​​‌‌‌​​‌​​‌‌​​‌​​​‌​‌‌​‌​‌‌​​‌‌​​​‌‌​‌​​​‌‌​​‌​​​​‌‌‌​​​​​‌‌​​​​​​‌‌​​‌‌​‌‌​​‌‌​​‌‌​​​‌‌​​‌‌​​​​​​‌‌‌​​‌​​‌‌​​​‌​​‌‌​‌​‌⁠

Pré-requisitos

A forma como o Claude Code interage com o ambiente local determina o que você precisa preparar antes de digitar o primeiro comando. Segundo a documentação do repositório, o uso da ferramenta envolve a coleta de feedback, o que inclui dados de uso (como aceitação ou rejeição de código), dados das conversas associadas e relatos enviados pelo usuário. A Anthropic declara aplicar salvaguardas de privacidade, como períodos limitados de retenção para informações sensíveis, acesso restrito a dados de sessão e políticas contra o uso desse feedback para treinar modelos, mas o envio de contexto da conversa para processamento externo ainda ocorre. Por causa desse fluxo de dados, o teste inicial nunca deve apontar para um repositório com segredos industriais, chaves de acesso ou dados pessoais.

Passo a passo

1. Instale o Claude Code via Homebrew

Se você já utilizou pacotes da Anthropic em JavaScript, atenção à mudança de rota: a instalação global via npm (npm install -g @anthropic-ai/claude-code) está oficialmente depreciada. No cenário com Homebrew já configurado no macOS, execute no terminal:

brew install --cask claude-code

Aguarde a instalação terminar antes de abrir o Claude Code. Se o Homebrew indicar uma falha, consulte a documentação oficial de setup vinculada no README antes de continuar.

2. Prepare a pasta do exercício didático

Para que você entenda exatamente o que cobrar na primeira leitura, vamos montar um exercício didático e não executado. Em vez de abrir um sistema em produção com centenas de dependências, use uma cópia isolada de um projeto mínimo.

Considere a seguinte estrutura fictícia de dois arquivos dentro de uma pasta chamada validador-pedido (criada apenas para ilustrar este exercício):⁠​‌​​‌​​‌​‌​​​​​‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌​​‌‌​​​‌​​‌‌‌​​‌​​‌‌‌‌‌​​​‌‌​​​‌​​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌​​‌‌​​‌‌​​​‌‌​‌​​​​‌‌​‌‌​​‌‌​​‌‌​​​‌​‌‌​‌​‌‌​​‌​​​​‌‌​​‌​​​‌‌‌​​‌​‌‌​​‌‌​​​‌​‌‌​‌​​‌‌​‌​​​​‌‌​‌‌‌​‌‌​​‌​​​‌‌​​‌‌​​​‌​‌‌​‌​​‌‌‌​​‌​​‌‌​‌‌​​​‌‌‌​​‌​​‌‌​​‌​​​‌​‌‌​‌​‌‌​​‌‌​​​‌‌​‌​​​‌‌​​‌​​​​‌‌‌​​​​​‌‌​​​​​​‌‌​​‌‌​‌‌​​‌‌​​‌‌​​​‌‌​​‌‌​​​​​​‌‌‌​​‌​​‌‌​​​‌​​‌‌​‌​‌⁠

• Arquivo 1 (README.md):

# Validador de Pedido
Verifica se o valor total atinge o mínimo para despacho.

• Arquivo 2 (validador.py):

LIMITE_MINIMO = 50.0

def pode_despachar(total, cupom_ativo):
    if cupom_ativo:
        return total >= 0
    return total >= LIMITE_MINIMO

3. Inicie o Claude Code na pasta escolhida e envie o prompt de leitura

Pelo terminal do macOS, navegue até o diretório da cópia que você separou para o teste e inicie a ferramenta com o comando documentado:

claude

Assim que a sessão interativa estiver pronta para receber instruções no terminal, utilize o prompt estruturado abaixo. Substitua as variáveis conforme a cópia do projeto que você escolheu:

Faça uma leitura inicial da pasta [pasta], cujo foco é [objetivo]. Responda entregando apenas três seções: 1) Mapa de arquivos: liste exclusivamente os caminhos de arquivos que existem de fato neste diretório; 2) Resumo apoiado em evidências: explique o que o código faz citando trechos literais curtos entre aspas copiados dos arquivos lidos; 3) Dúvidas abertas: aponte regras de negócio ambíguas ou casos de borda que não estão claros no código. Instrução de controle: não edite arquivos, não crie novos arquivos e não execute comandos no sistema.

A instrução para não editar arquivos nem executar comandos orienta o exercício, mas não é uma trava técnica. Não autorize ações fora da leitura proposta; confira eventuais alterações.

4. Exemplo de saída esperada (ilustrativo e não executado)

Para a estrutura fictícia de dois arquivos mostrada no Passo 2, uma resposta adequada ao prompt deve se parecer com o exemplo esperado abaixo (trata-se de uma ilustração didática do formato esperado, e não do resultado de um teste executado):

1) Mapa de arquivos:
- ./README.md
- ./validador.py

2) Resumo apoiado em evidências:
O projeto valida se um pedido atinge o valor mínimo para envio, conforme descrito em "Verifica se o valor total atinge o mínimo para despacho." (README.md). No código principal, a constante fixa o piso em "LIMITE_MINIMO = 50.0" (validador.py) e a função "def pode_despachar(total, cupom_ativo):" libera qualquer pedido não negativo quando há cupom (trechos literais: "if cupom_ativo:" e "return total >= 0").

3) Dúvidas abertas:
- O parâmetro `total` aceita valores nulos ou tipos não numéricos sem tratamento de exceção?
- Qualquer cupom ativo isenta o pedido do `LIMITE_MINIMO`, mesmo que o valor final seja zero?

Como verificar

Depois que o Claude Code devolver a resposta no seu terminal, faça a auditoria em três frentes antes de considerar a instalação aprovada para o seu fluxo:⁠​‌​​‌​​‌​‌​​​​​‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌​​‌‌​​​‌​​‌‌‌​​‌​​‌‌‌‌‌​​​‌‌​​​‌​​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌​​‌‌​​‌‌​​​‌‌​‌​​​​‌‌​‌‌​​‌‌​​‌‌​​​‌​‌‌​‌​‌‌​​‌​​​​‌‌​​‌​​​‌‌‌​​‌​‌‌​​‌‌​​​‌​‌‌​‌​​‌‌​‌​​​​‌‌​‌‌‌​‌‌​​‌​​​‌‌​​‌‌​​​‌​‌‌​‌​​‌‌‌​​‌​​‌‌​‌‌​​​‌‌‌​​‌​​‌‌​​‌​​​‌​‌‌​‌​‌‌​​‌‌​​​‌‌​‌​​​‌‌​​‌​​​​‌‌‌​​​​​‌‌​​​​​​‌‌​​‌‌​‌‌​​‌‌​​‌‌​​​‌‌​​‌‌​​​​​​‌‌‌​​‌​​‌‌​​​‌​​‌‌​‌​‌⁠

1. Conferência de caminhos e trechos literais: abra os arquivos originais no seu editor de código (IDE, o ambiente integrado de desenvolvimento que você utiliza no dia a dia) e confirme se todos os caminhos listados no item 1 existem de fato. Verifique se os trechos entre aspas no item 2 são cópias exatas do seu código, sem linhas inventadas.
2. Inspeção de integridade no editor: verifique na árvore de arquivos do seu editor e no painel de controle de versão se nenhum arquivo existente sofreu alteração de horário de modificação ou de conteúdo, e se nenhum arquivo temporário foi criado na pasta. Não autorize ações fora da leitura proposta; confira eventuais alterações.
3. Registro de versão e ambiente: como o documento principal do repositório não fixa um número de versão estático no texto nem detalha flags de consulta de versão, anote no registro da sua equipe a versão exata do pacote exibida pelo Homebrew no momento da instalação, junto com a versão do seu macOS e o emulador de terminal utilizado.

Erros comuns

• Instalar pelo comando depreciado do npm: rodar npm install -g @anthropic-ai/claude-code por hábito de outros pacotes JavaScript instala uma distribuição marcada como depreciada pela própria Anthropic. Neste tutorial, use brew install --cask claude-code.
• Executar claude na pasta raiz do usuário: se você esquecer de entrar na pasta da cópia do projeto antes de digitar claude, a ferramenta tomará o diretório atual como base de contexto, o que pode expor pastas pessoais ou outros repositórios da máquina.
• Confiar na restrição do prompt como trava de segurança: tratar a frase "não edite arquivos" como garantia de sistema operacional leva a descuidos na supervisão do terminal. Não autorize ações fora da leitura proposta e trabalhe sobre uma cópia descartável no primeiro uso.
• Acionar o comando /bug com código sigiloso na tela: a documentação informa que o comando /bug serve para relatar problemas diretamente de dentro do Claude Code (além da opção de abrir uma issue no GitHub), mas lembra que o envio de feedback inclui dados de uso e dados da conversa associada.

Checklist de verificação final

• [ ] As condições de acesso, autenticação e política de dados foram conferidas nos links oficiais indicados pelo repositório antes do uso.
• [ ] A instalação foi feita com brew install --cask claude-code, descartando o método depreciado via npm.
• [ ] A versão instalada pelo Homebrew e os dados do ambiente macOS foram registrados para controle da equipe.
• [ ] O comando claude foi executado exclusivamente dentro de uma cópia isolada de um projeto pequeno e compartilhável.
• [ ] Todos os caminhos de arquivos e trechos citados na resposta conferem linha por linha com os arquivos reais do diretório.
• [ ] A conferência no editor de código após encerrar a sessão confirmou que o número de arquivos modificados ou criados na pasta do projeto é 0.