🧠 Fundamentos do Claude Code

Claude Code é uma ferramenta de linha de comando (CLI) criada pela Anthropic. Ela roda direto no terminal e permite programar com IA no seu projeto real — não em um chat web isolado.

Diferente de chatbots web, o Claude Code lê seus arquivos reais, executa comandos e edita código com contexto completo do projeto. Isso muda completamente a produtividade.

CLI (Command Line Interface), criada pela Anthropic, funciona com qualquer endpoint compatível, opera no diretório do seu projeto.

Claude Code é o "carro" — a interface, o repositório, as ferramentas. O modelo LLM (Claude, Qwen, Gemma, etc.) é o "motor" — o que gera as respostas. São separados.

Entender essa separação é o que permite usar Claude Code de graça: você mantém a interface e troca o motor por um gratuito (Ollama local ou OpenRouter free tier).

Interface ≠ modelo, ANTHROPIC_BASE_URL para trocar o motor, compatibilidade de API, modelos intercambiáveis.

LLM (Large Language Model) é um modelo de inteligência artificial treinado em enormes volumes de texto e código. Ele aprende padrões para gerar texto coerente e útil.

Entender o que é um LLM ajuda a calibrar expectativas: ele prevê o próximo token, não "pensa" como humano. Isso explica por que instruções claras produzem resultados melhores.

Tokens, previsão de sequência, treinamento em código/texto, parâmetros do modelo, temperatura, contexto.

Existem dois caminhos para usar Claude Code sem pagar: Ollama (roda modelos localmente na sua máquina, sem internet) e OpenRouter (API com modelos gratuitos na nuvem).

A API oficial da Anthropic cobra por token. Conhecer as alternativas gratuitas permite experimentar, aprender e usar em projetos pessoais sem custo algum.

Ollama = local/offline/gratuito, OpenRouter = nuvem/free tier disponível, ambos compatíveis com a API da Anthropic via ANTHROPIC_BASE_URL.

Modelos fechados (Claude, GPT-4) são proprietários e acessados via API paga. Modelos open source (Qwen, Llama, Gemma) têm pesos disponíveis publicamente para rodar localmente.

O benchmark SWE-bench mede capacidade de resolver issues de código. Em 2025, modelos open source chegaram a 76% (Qwen3.5-397B) vs 79% do Claude Opus 4.6. A diferença diminuiu muito.

SWE-bench score, modelos open source, modelos fechados, custo vs desempenho, privacidade dos dados.

Claude Code brilha em tarefas que envolvem múltiplos arquivos, execução de comandos e iteração — refatorações grandes, debugging complexo, criação de features completas.

Chat web é ótimo para perguntas pontuais. Claude Code é ótimo para trabalhar no projeto real. Saber quando usar cada um economiza tempo e tokens.

Tarefas multi-arquivo, acesso ao terminal, contexto do projeto completo, iteração automática, casos de uso ideais.

Quando você envia uma mensagem, Claude Code empacota seu pedido + contexto do projeto e envia ao modelo LLM. O modelo responde com chamadas de ferramentas (leia arquivo X, execute comando Y). CC executa e itera.

Entender o fluxo ajuda a formular pedidos melhores e entender por que algumas tarefas levam mais tempo — o modelo precisa de múltiplas iterações de ferramenta.

Loop agente, tool calls, iteração automática, contexto enviado ao modelo, resposta final ao usuário.

Claude Code oferece ferramentas que o modelo pode invocar: Read (ler arquivos), Edit (editar trecho), Write (criar arquivo), Bash (executar comando), WebSearch (buscar na web).

Cada ferramenta tem permissões diferentes. Saber quais existem permite pedir tarefas que fazem uso delas — e saber quando o modelo vai pedir permissão para executar algo.

Read/Edit/Write para arquivos, Bash para terminal, permissões por ferramenta, MCP para ferramentas externas.

Janela de contexto é o limite de tokens que o modelo consegue "ver" de uma vez. Inclui o histórico da conversa, arquivos lidos e instruções. Quando cheia, informações antigas são descartadas.

Sessões longas enchem a janela. Quando isso acontece, o modelo "esquece" o início da conversa. O comando /compact comprime o histórico para liberar espaço.

Limite de tokens, compactação automática, /compact manual, autoCompactThreshold, impacto na qualidade das respostas.

CLAUDE.md é um arquivo Markdown na raiz do projeto que é automaticamente lido pelo Claude Code no início de cada sessão. Funciona como instruções permanentes para o modelo.

Sem CLAUDE.md você repete as mesmas instruções toda sessão. Com ele, você define padrões de código, convenções do projeto e contexto importante uma vez só.

Arquivo na raiz do projeto, lido automaticamente, instruções persistentes, padrões de código, contexto do projeto.

Por padrão, Claude Code pede confirmação antes de executar comandos bash e editar arquivos fora do diretório atual. Essas permissões podem ser ajustadas no settings.json.

Entender o modelo de permissões evita surpresas e acidentes. Você pode configurar para pedir menos confirmações em tarefas de rotina sem abrir mão da segurança.

Permissões por ferramenta, settings.json, confirmação de comandos bash, escopo do diretório, modo seguro.

ANTHROPIC_BASE_URL é uma variável de ambiente que redireciona todas as chamadas da API para o endereço especificado. Aponte para Ollama local ou OpenRouter e use de graça.

Essa variável é o "interruptor" que troca o motor. Sem ela, CC usa sempre a API paga da Anthropic. Com ela configurada corretamente, você usa o modelo que quiser.

Variável de ambiente, redirecionamento de API, compatibilidade, ANTHROPIC_API_KEY em branco para Ollama, autenticação para OpenRouter.

Token é a unidade básica de texto que os LLMs processam. Em inglês, 1 palavra ≈ 1.3 tokens. Em português, um pouco mais. Código tende a ter mais tokens por linha por causa de símbolos.

A API cobra por tokens. O contexto tem limite de tokens. Entender tokens ajuda a otimizar prompts, estimar custos e entender quando a janela de contexto está cheia.

Input tokens, output tokens, custo por token, tokenização, diferença por idioma, limite de contexto.

Compactação é o processo de resumir o histórico da conversa para liberar espaço na janela de contexto. O comando /compact dispara manualmente; autoCompactThreshold faz automaticamente.

Sessões longas degradam a qualidade quando a janela enche. Configurar autoCompactThreshold: 75 faz o CC compactar quando atinge 75% da janela — mantendo desempenho sem intervenção.

/compact, autoCompactThreshold, resumo do histórico, tokens economizados, impacto na continuidade da sessão.

API Key é uma chave secreta que identifica e autentica você junto ao serviço de API. Para a API da Anthropic, começa com "sk-ant-". Para OpenRouter, começa com "sk-or-".

Sem API Key válida, o Claude Code não consegue se conectar. Com Ollama local, você usa um valor fake (ex: "ollama") — mas ainda precisa definir a variável.

ANTHROPIC_API_KEY, chave secreta, autenticação Bearer, nunca commitar no git, usar variável de ambiente.

settings.json é o arquivo de configuração do Claude Code. Existe um global (~/.claude/settings.json) e um por projeto (.claude/settings.json). O projeto sobrescreve o global.

settings.json é onde você define variáveis de ambiente (como ANTHROPIC_BASE_URL), permissões de ferramentas e comportamentos padrão — sem precisar exportar nada no terminal.

Global vs projeto, chave "env", chave "permissions", hierarquia de configuração, JSON válido obrigatório.

Variáveis de ambiente são pares chave=valor acessíveis por processos do sistema operacional. Claude Code lê ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY e outras para configuração.

É a forma mais segura de passar configurações sensíveis (como chaves) sem hardcodar em arquivos. Linux/Mac usa export; Windows usa setx ou $env: no PowerShell.

export VAR=valor (Linux/Mac), setx VAR valor (Windows CMD), $env:VAR = "valor" (PowerShell), ~/.bashrc para persistência.

export no terminal dura apenas aquela sessão do shell. Quando fecha o terminal, a variável some. settings.json persiste entre sessões e é recomendado para configurações permanentes.

Muita confusão vem de configurar via export e depois reabrir o terminal sem funcionar. Entender a diferença resolve esse problema definitivamente.

Escopo de sessão vs permanente, settings.json como solução ideal, ~/.bashrc para export permanente no Linux, prioridade de configuração.