🧭 Fundamentos

Um agente é um programa que percebe o ambiente, toma decisões e age de forma autônoma para alcançar um objetivo — diferente de um chatbot que só responde perguntas.

Entender essa diferença é fundamental para saber o que esperar do Claude Code e como pedir tarefas de forma eficiente.

Percepção → Decisão → Ação; ciclo autônomo; objetivo vs. resposta única; contexto persistente.

O terminal é a interface de texto que dá acesso direto ao sistema operacional — arquivos, processos, rede. É onde o agente executa comandos reais.

Interfaces gráficas são lentas e difíceis de automatizar. No terminal, o Claude Code pode ler, escrever, executar e pesquisar em segundos.

Shell, stdin/stdout, pipe, permissões de arquivo, PATH, processo filho.

O Claude Code usa ferramentas concretas: Read (lê arquivos), Edit (modifica arquivos), Bash (executa comandos), Search (busca padrões no código).

Saber quais ferramentas existem ajuda a entender o que o agente pode e não pode fazer em cada tarefa.

Read, Edit, Write, Bash, Glob, Grep — as ferramentas nativas do Claude Code.

Refatorar código, criar features, escrever testes, migrar APIs, corrigir bugs, gerar documentação — tudo sem sair do terminal.

Delimitar o escopo de uso aumenta a efetividade. Saber "onde o agente brilha" economiza tempo e evita frustrações.

Tarefas de código, automação de repositórios, CI/CD, geração de boilerplate, análise de logs.

Um chatbot responde texto. Um agente executa ações no mundo real: cria arquivos, roda testes, faz commits. O Claude Code é um agente.

Mudar o frame mental de "perguntar" para "delegar tarefas" transforma o modo de usar a ferramenta.

Ação vs. resposta; efeito colateral; permissão de execução; autonomia controlada.

O primeiro contato: abrir o terminal, digitar claude, pedir uma tarefa simples e observar o agente trabalhar passo a passo.

Ver o agente funcionando na prática — com as ferramentas aparecendo em tempo real — é a melhor forma de internalizar o conceito.

Sessão interativa, modo headless, claude --help, primeira tarefa delegada.

O agente executa um ciclo contínuo: Pensar (raciocinar sobre o que fazer), Usar Ferramenta (ação no mundo real), Observar (ler o resultado) e repetir.

Entender o loop ajuda a formular tarefas melhores e a saber por que o agente faz certas perguntas ou toma certas decisões.

ReAct loop, "chain of thought", observação do ambiente, iteração até conclusão.

Ferramentas são as "mãos" do agente: Read (lê arquivo), Edit (edita arquivo), Bash (roda comando), Glob (lista arquivos), Grep (busca texto).

Cada ferramenta tem custo, permissão e escopo diferentes. Conhecê-las permite entender logs e otimizar o fluxo.

Tool call, tool result, permissão explícita vs. implícita, custo de tokens por ferramenta.

Antes de agir, o agente raciocina internamente: divide o problema em passos, identifica dependências e escolhe a ferramenta certa para cada etapa.

Dar contexto suficiente na tarefa permite que o plano seja mais preciso, reduzindo idas e vindas desnecessárias.

Decomposição de tarefas, plano explícito vs. implícito, scratchpad interno, rastreamento de progresso.

O agente pede confirmação antes de ações destrutivas (deletar arquivos, rodar comandos perigosos) ou quando não tem contexto suficiente.

Saber quando o agente vai pausar e pedir ajuda evita surpresas e ajuda a configurar permissões corretamente no settings.json.

allowlist, denylist, confirmação interativa, modo autônomo, --dangerously-skip-permissions.

O agente não navega em sites, não clica em UIs gráficas (sem plugins), não tem memória entre sessões por padrão, e não tem acesso à internet sem ferramentas externas.

Conhecer os limites evita expectativas erradas e ajuda a complementar com outras ferramentas quando necessário.

Sem memória persistente nativa, sem acesso GUI, sandboxing, escopo do projeto local.

Durante a execução, o Claude Code exibe cada ferramenta chamada, o que foi lido e o que foi modificado — o log de raciocínio visível em tempo real.

Ler os logs ajuda a entender as decisões, detectar erros mais cedo e ganhar confiança no que o agente está fazendo.

Verbose output, tool trace, raciocínio explícito, verificação humana, interrupção segura (Ctrl+C).

Contexto é tudo que o modelo "sabe" no momento: a conversa, os arquivos lidos, o resultado das ferramentas. É a memória de trabalho ativa da sessão.

Sem entender o contexto, você não sabe por que o agente "esqueceu" algo ou por que suas respostas ficaram estranhas no fim da sessão.

Prompt, histórico de conversa, tool results no contexto, CLAUDE.md como contexto persistente.

Tokens são fragmentos de texto (≈ 4 chars em inglês, ≈ 3 em pt-BR). Cada palavra vira 1-3 tokens. Modelos processam e cobram por tokens.

Entender tokens ajuda a estimar custo, controlar o uso da janela e evitar ultrapassar o limite que degrada as respostas.

Token de input, token de output, tokenizer, custo por 1M tokens, comprimento de arquivo em tokens.

A janela de contexto é o limite máximo de tokens que o modelo processa de uma vez. Claude 3 Sonnet tem 200K tokens — cerca de 500 páginas de texto.

Quando a janela enche, o agente começa a "esquecer" partes da conversa ou o sistema trunka o contexto automaticamente.

200K tokens, truncamento automático, degradação de performance, janela deslizante.

O contexto enche por: arquivos grandes lidos inteiros, histórico longo, respostas verbosas, muitas tool calls acumuladas na mesma sessão.

Identificar o culpado permite agir: dividir sessões, usar /clear, ou mudar a estratégia de leitura de arquivos.

Arquivo grande, histórico longo, tool results acumulados, leitura desnecessária de arquivos binários.

O comando /compact resume a conversa anterior, liberando espaço na janela. O Claude Code também faz compactação automática quando necessário.

Saber quando e como compactar evita perda de contexto crítico e mantém o agente eficaz em sessões longas.

/compact, /clear, summarização automática, CLAUDE.md como memória externa.

Práticas como usar CLAUDE.md para instruções fixas, dividir tarefas grandes em sessões menores, e evitar ler arquivos desnecessários economizam tokens e melhoram a qualidade.

Um contexto enxuto significa respostas mais precisas, custo menor e sessões mais longas antes da degradação.

CLAUDE.md, sessões curtas focadas, leitura seletiva, evitar copiar código inteiro nas mensagens.

O terminal é um programa que interpreta comandos de texto. No Mac: Terminal ou iTerm2. No Windows: PowerShell ou WSL. No Linux: qualquer emulador.

O Claude Code só funciona no terminal. Sem saber abrir e usar o terminal, não é possível nem iniciar o agente.

Shell (bash/zsh), prompt ($), emulador de terminal, stdin/stdout, código de saída 0 = sucesso.

O sistema de arquivos é uma árvore. Caminho absoluto: /home/user/projeto. Caminho relativo: ./src. O ponto de partida é o diretório atual.

O Claude Code opera no diretório onde você o inicia. Entender caminhos é essencial para apontar o agente para os arquivos certos.

Raiz (/), home (~), caminho absoluto, caminho relativo, . (atual), .. (pai).

cd (mudar pasta), ls (listar), mkdir (criar pasta), pwd (onde estou), cat (ver arquivo), cp/mv/rm.

Estes comandos são usados pelo Claude Code em quase toda tarefa. Reconhecê-los nos logs ajuda a acompanhar o que o agente está fazendo.

cd, ls -la, mkdir -p, pwd, cat, cp, mv, rm -rf (cuidado!), man (ajuda).

CLI (Command-Line Interface) é um programa que você controla via texto no terminal: git, npm, python, claude são CLIs.

O Claude Code É uma CLI. Entender como CLIs funcionam (flags, subcomandos, --help) ajuda a usar qualquer ferramenta de linha de comando.

Flags (--flag), argumentos posicionais, subcomandos, --help, código de retorno.

Gerenciadores de pacotes instalam CLIs: npm install -g @anthropic-ai/claude-code (Node), brew install (Mac), apt install (Linux).

Instalar o Claude Code é o primeiro passo prático. Entender como gerenciadores de pacotes funcionam evita erros de instalação.

npm, Node.js, PATH, versão global vs. local, which claude, atualização.

Nunca execute comandos copiados da internet sem entender o que fazem. rm -rf /, curl | bash sem verificar, e sudo desnecessário são riscos reais.

O terminal tem poder real sobre o sistema. Um comando errado pode apagar arquivos, expor credenciais ou instalar malware.

Ler antes de executar, sudo com parcimônia, variáveis de ambiente com segredos, .env no .gitignore.