Claude Code é a interface de linha de comando oficial da Anthropic, capaz de ler código-fonte, aplicar edições, executar comandos e interagir com o git diretamente no terminal por meio de um diálogo natural em linguagem humana. Não se trata de uma janela separada de webchat onde você precisa copiar o código manualmente, mas sim de um agente autônomo completo que opera diretamente dentro do seu projeto.
Este guia é o ponto de partida para começar rapidamente com o Claude Code. O material está dividido em três blocos lógicos:
- Módulo 1 — Instalação e configuração básica: implantação da CLI, autenticação via API ou OAuth, primeiro uso e visão geral dos arquivos de configuração.
- Módulo 2 — Sessão de trabalho e interação: gerenciamento de contexto, atalhos de teclado, slash commands, modo não interativo e otimização de memória (
/compact). - Módulo 3 — Segurança e modelo de permissões: configuração dos arquivos
settings.json, criação de listas de permissão (allow) e negação (deny) para comandos bash.
Cada módulo é consolidado por um exercício prático de criação, refinamento e finalização de um componente web real em Next.js.
1. O que é o Claude Code e requisitos do sistema
1.1. O que é o Claude Code e suas diferenças em relação ao webchat
O Claude Code integra-se ao seu stack de desenvolvimento diário como um assistente de terminal. Diferentemente de um webchat tradicional, o agente possui um conjunto de ferramentas (Tools):
- Leitura e busca: inspeciona arquivos individuais, encontra ocorrências via expressões regulares (
grep) e navega pela estrutura do projeto (glob). - Modificação de código: gera alterações pontuais nos arquivos através de mecanismos de patch/diff, evitando a reescrita completa de arquivos grandes.
- Execução de comandos do sistema: roda testes, compiladores, linters e comandos git, com capacidade de analisar códigos de retorno e erros de compilação.
1.2. Requisitos do sistema e preparação do ambiente
Antes de instalar, certifique-se da presença dos componentes necessários:
- Sistema operacional: macOS, distribuição Linux moderna ou Windows via subsistema WSL2.
- Ambiente de execução: Node.js versão 18.0 ou superior (verifique com
node -v). - Sistema de controle de versões: Git versão 2.20+ (verifique com
git --version). - Acesso aos modelos da Anthropic: chave de API ativa da Anthropic Console ou conta com plano Claude Max.
2. Instalação e autenticação
2.1. Instalação da CLI via npm e gerenciador de pacotes
O Claude Code é distribuído como um pacote global no registro npm. Execute o comando de instalação no terminal:
Verifique a correção da instalação do binário:
Se o terminal retornar o erro command not found, isso indica que o caminho dos pacotes globais do npm não está presente na variável de ambiente PATH. A solução detalhada é apresentada no bloco de diagnóstico abaixo.
2.2. Autenticação e vinculação da conta Anthropic
São suportados dois métodos de autorização:
Opção 1 — Chave da API Anthropic:
Especifique o token através de uma variável de ambiente:
Para que a chave seja mantida entre reinicializações do terminal, adicione o comando ao arquivo de configuração do seu shell:
Opção 2 — Assinatura Claude Max (OAuth):
Se você utiliza a assinatura Claude Max ($100 ou $200/mês), faça login sem usar uma chave de API separada:
O comando abrirá uma sessão no seu navegador padrão para confirmar o acesso.
3. Primeiro uso e configuração básica
3.1. Primeira execução no projeto e verificação do ambiente
Navegue até o diretório de qualquer um dos seus projetos de código e inicialize o Claude Code:
Após a execução, você entrará em um ambiente de linha de comando interativo. Tente enviar uma consulta básica de teste:
O Claude revisará automaticamente os arquivos package.json, configurações de build e a estrutura de diretórios, formulando em seguida um breve relatório introdutório.
3.2. Configuração básica e resolução de problemas (Troubleshooting)
Os arquivos de configuração estão localizados no diretório ~/.claude/:
~/.claude/settings.json— permissões globais e restrições de acesso às ferramentas.~/.claude/CLAUDE.md— instruções de sistema pessoais do usuário..claude/settings.json— configurações do projeto (fixadas no sistema de controle de versões).CLAUDE.md— instruções a nível de repositório (arquitetura, regras de linting).
| Problema durante a execução | Causa raiz | Solução de engenharia |
|---|---|---|
claude: command not found | Diretório bin do npm não adicionado ao PATH | Adicione o caminho ao shell: export PATH="$(npm config get prefix)/bin:$PATH" |
Erro de autorização 401 Unauthorized | Chave de API inválida ou expirada | Execute claude logout, verifique o valor de ANTHROPIC_API_KEY e repita claude login |
| Inicialização lenta da sessão | Indexação de repositório grande | A primeira execução requer análise da árvore de arquivos; as iterações subsequentes utilizam cache |
4. Prática: criando a primeira aplicação
4.1. Algoritmo passo a passo para implantar o protótipo
O objetivo do primeiro exercício é criar, na prática, um componente cliente mínimo Next.js / React usando o Claude Code:
- Peça ao Claude para criar um novo arquivo de página
app/practice/page.tsx. - Instrua-o a descrever um estado simples de carregamento e um botão para chamar um endpoint de teste.
- Verifique a funcionalidade da interface acessando
http://localhost:3000/practice.
4.2. Template inicial do componente e verificação local
O código base do protótipo:
5. Sessão de trabalho e ciclo de diálogo
5.1. Iniciando uma sessão REPL interativa
Para o desenvolvimento cotidiano, navegue até o diretório de trabalho e ative o loop interativo de leitura-execução (REPL):
O Claude mantém o contexto da conversa durante a sessão, lembrando dos arquivos alterados e dos erros detectados. A comunicação ocorre em linguagem natural, sem sintaxe formalizada.
5.2. Ciclo de diálogo: planejamento, ferramentas e execução
O funcionamento do agente segue um ciclo de cinco etapas:
Um trecho típico de interação:
- Consulta:
Adicione um indicador de carregamento à página do dashboard. - Análise: O Claude lê
app/dashboard/page.tsxe identifica a ausência de tratamento para espera de dados. - Proposta: Criação do componente
loading.tsxe envolvimento do bloco dentro de limitesSuspense. - Resumo: O agente apresenta um diff pontual e aguarda sua aprovação.
6. Atalhos, comandos e modos de operação
6.1. Atalhos de teclado e slash commands para gerenciamento de contexto
A navegação eficiente no terminal baseia-se em abreviações do sistema:
| Combinação | Finalidade |
|---|---|
Enter | Envio da mensagem atual ao agente |
Escape | Cancelamento imediato da geração ativa ou execução de ferramenta |
Ctrl+C | Encerramento correto da sessão do Claude Code |
Up / Down | Navegação pelo histórico anterior de consultas |
Shift+Tab | Alternância entre entrada de linha única e múltiplas linhas |
Comandos internos especiais (slash commands) para controle do ambiente:
/help— lista de diretivas disponíveis./clear— reset da história atual de mensagens./compact— compressão da janela de contexto para economizar tokens sem perder a essência./model— troca rápida do modelo atual (por exemplo, alternar entre Sonnet e Opus)./permissions— verificação das permissões ativas para chamadas de utilitários do sistema.
6.2. Modo não interativo e dicas para trabalho eficaz
Para usar o Claude Code em scripts de automação ou operações únicas, utilize a flag -p (print):
💡 Recomendações para estabilidade:
- Formule requisitos especificamente: em vez de “corrija o formulário”, escreva “adicione debounce ao handler de clique do botão de envio do formulário”.
- Execute
/compactregularmente quando o comprimento do diálogo exceder 30–40 passos.
7. Prática: refinando a aplicação
7.1. Refatoração e melhoria da base de código via Claude
Na segunda parte prática, expandiremos o protótipo criado, instrindo o Claude a aprimorar o tratamento de estados limite e a tipagem.
Envie ao agente a seguinte instrução:
7.2. Expansão de funcionalidades: estilização, tratamento de erros e animação
O código atualizado da página:
8. Modelo de permissões e segurança
8.1. Arquitetura do modelo de permissões e níveis de risco das ferramentas
O sistema de segurança do Claude Code classifica todas as operações disponíveis em duas categorias fundamentais conforme o nível de risco potencial:
| Nível de acesso | Operações disponíveis | Mecanismo de execução |
|---|---|---|
| Seguras (Read-only) | Read, Grep, Glob, listagem de diretórios | Executadas automaticamente sem solicitações ao usuário |
| Potencialmente perigosas | Edit, Write, Bash, exclusão de arquivos, git push | Requerem confirmação explícita antes da execução |
8.2. Mecânica de aprovação e rejeição de ações potencialmente perigosas
Antes de executar uma ação arriscada, o Claude pausa a execução e exibe uma solicitação:
As opções disponíveis são:
y(yes) — aprovar esta chamada específica única.n(no) — rejeitar a ação indicando o motivo da recusa.always(oua) — conceder permissão para chamar esta ferramenta até o final da sessão de trabalho atual.
9. Arquivos de configuração e gestão de direitos
9.1. Arquivos de configuração globais e de projeto (settings.json)
Para fixar regras permanentes, crie ou edite o arquivo global ~/.claude/settings.json:
9.2. Padrões para comandos bash e verificação via /permissions
A seção permissions.allow suporta máscaras de busca flexíveis (glob patterns):
Bash(npm test *)— permite a execução de pacotes de teste sem confirmações.Bash(git commit *)— permite a fixação de mudanças.Bash(rm -rf *)na listadeny— garante o bloqueio absoluto de exclusão massiva de dados.
Para visualizar as regras vigentes a qualquer momento da sessão, execute o comando /permissions.
10. Melhores práticas de segurança e operação
10.1. Estratégia de controle de acesso: princípio do menor privilégio
- Expansão gradual de direitos: Comece o trabalho com moderação totalmente manual. Adicione comandos à lista
allowapenas após garantir a estabilidade do comportamento do agente. - Proibição de wildcard para bash: Nunca especifique
"Bash(*)"nas ferramentas permitidas — isso anula completamente a sandbox de proteção. - Uso ativo de deny: Bloqueie explicitamente utilitários destrutivos (
sudo,mkfs,dd) para impedir danos acidentais ao sistema.
10.2. Proteção de segredos do ambiente e auditoria cuidadosa dos diffs
- Isolamento de tokens: O Claude Code tem acesso às variáveis de ambiente do shell atual. Não mantenha chaves críticas de bancos de dados de produção na sessão de trabalho.
- Revisão do diff antes da aprovação: Analise sempre o diff proposto para edição de arquivo, a fim de detectar a tempo a remoção acidental de módulos adjacentes.