# Claude Code: guia para iniciantes > Guia completo sobre o uso do Claude Code da Anthropic: instalação da CLI, autenticação, gerenciamento de permissões, atalhos de teclado e desenvolvimento passo a passo do primeiro projeto. 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: ```bash npm install -g @anthropic-ai/claude-code ``` Verifique a correção da instalação do binário: ```bash claude --version ``` 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: ```bash export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api" ``` Para que a chave seja mantida entre reinicializações do terminal, adicione o comando ao arquivo de configuração do seu shell: ```bash echo 'export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api"' >> ~/.zshrc source ~/.zshrc ``` **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: ```bash claude login ``` 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: ```bash cd ~/my-project claude ``` Após a execução, você entrará em um ambiente de linha de comando interativo. Tente enviar uma consulta básica de teste: ```text Summarize the structure of this project and list the main technologies used. ``` 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: 1. Peça ao Claude para criar um novo arquivo de página `app/practice/page.tsx`. 2. Instrua-o a descrever um estado simples de carregamento e um botão para chamar um endpoint de teste. 3. 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: ```tsx // app/practice/page.tsx 'use client'; import { useState } from 'react'; export default function PracticePage() { const [result, setResult] = useState(''); const [loading, setLoading] = useState(false); async function runTest() { setLoading(true); try { const response = await fetch('/api/test'); const data = await response.json(); setResult(data.message || 'Запит виконано успішно'); } catch { setResult('Помилка виконання тестового запиту'); } finally { setLoading(false); } } return (

Практична вправа 1: Прототип

{result && (
{result}
)}
); } ``` --- ## 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): ```bash cd ~/my-project claude ``` 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: ```mermaid flowchart TD A["Користувач ставить завдання природною мовою"] --> B["Claude аналізує кодову базу та формує план"] B --> C["Агент запитує дозвіл на модифікацію файлів/команд"] C --> D["Виконання затверджених дій та валідація дифу"] D --> E["Користувач перевіряє результат та надає фідбек"] ``` 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.tsx` e identifica a ausência de tratamento para espera de dados. - **Proposta:** Criação do componente `loading.tsx` e envolvimento do bloco dentro de limites `Suspense`. - **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`): ```bash # Отримання швидкої довідки про проєкт claude -p "Яку базу даних використовує цей проєкт?" # Передача логів для аналізу через пайплайн cat error.log | claude -p "Знайди першопричину збою та запропонуй рішення" ``` > 💡 **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 `/compact` regularmente 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: ```text Abra app/practice/page.tsx. Adicione tipagem TypeScript estrita e correta, um bloco de tratamento de erros try/catch que exiba a mensagem de erro em fundo vermelho, e adicione um spinner CSS animado durante o carregamento. ``` ### 7.2. Expansão de funcionalidades: estilização, tratamento de erros e animação O código atualizado da página: ```tsx // app/practice/page.tsx - Доопрацьована версія 'use client'; import { useState } from 'react'; export default function PracticePage() { const [result, setResult] = useState(null); const [error, setError] = useState(null); const [loading, setLoading] = useState(false); async function runTest() { setLoading(true); setError(null); try { const response = await fetch('/api/test'); if (!response.ok) throw new Error(`Помилка сервера: код ${response.status}`); const data = await response.json(); setResult(data.message || 'Операцію успішно завершено'); } catch (err: unknown) { setError(err instanceof Error ? err.message : 'Сталася непередбачена помилка'); } finally { setLoading(false); } } return (

Практична вправа 2: Доопрацювання

Тестування обробки винятків та динамічних станів.

{error && (
{error}
)} {result && (
{result}
)}
); } ``` --- ## 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: ```text Claude wants to run: npm install express Allow? (y/n/always) ``` 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` (ou `a`) — 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`: ```json { "permissions": { "allow": [ "Read", "Glob", "Grep", "Edit", "Write", "Bash(npm run *)", "Bash(git status)" ], "deny": [ "Bash(rm -rf *)", "Bash(sudo *)" ] } } ``` ### 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 lista `deny` — 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 `allow` apenas 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. --- ## 11. Prática: versão final da aplicação ### 11.1. Versão protegida da aplicação