Módulo 1.3 — Conceitos Essenciais

🔢 O que é um Token

Token é a unidade mínima de texto que um LLM processa. Não é uma letra, não é uma palavra — é algo no meio. Entender tokens é fundamental para entender custo, contexto e performance.

Como tokens funcionam na prática

Texto em inglês — ~1 token por palavra:

Hello world ! = 3 tokens

Texto em português — ~1.3 tokens por palavra:

Ol á mun do ! = 5 tokens

Código — mais tokens por linha:

const result = await fetch ( url ) = 8 tokens

📊 Referência prática de tokens

1 página de texto≈ 500 tokens

100 linhas de código≈ 800 tokens

Arquivo JS médio (200 linhas)≈ 1.500 tokens

Componente React completo≈ 2.000 tokens

Conversa de 10 turnos≈ 5.000 tokens

Janela 128k (Llama 3.3)≈ 85 arquivos médios

Janela 200k (Claude)≈ 133 arquivos médios

Janela 8k (Gemma)≈ 5 arquivos médios

💡 Com Ollama/OpenRouter free: custo de tokens = $0

Usando modelos locais ou free tier, você não paga por token. A única "moeda" que importa é o limite da janela de contexto — que define quanto o modelo pode "ver" de uma vez.

🗜️ Compactação de contexto

Quando a janela de contexto começa a encher, a qualidade das respostas degrada — o modelo "esquece" o início da conversa. A compactação resolve isso resumindo o histórico e liberando espaço.

Duas formas de compactar

Manual: /compact

Digite no Claude Code quando sentir a sessão pesada ou antes de iniciar uma nova tarefa grande.

              # No terminal do Claude Code:

              /compact

              # Com instrução personalizada:

              /compact Foca nas decisões de arquitetura

Automático: autoCompactThreshold

Configure no settings.json para compactar automaticamente ao atingir uma porcentagem da janela.

              // ~/.claude/settings.json

              {

                "autoCompactThreshold": 75

              }

              // Compacta aos 75% da janela

O que acontece durante a compactação

1. Claude Code pausa a sessão

2. O modelo gera um resumo do histórico focando em decisões e contexto relevante

3. O histórico original é substituído pelo resumo compactado

4. A sessão continua — o modelo mantém o contexto geral mas perde detalhes específicos de mensagens antigas

💡 Recomendação prática

Configure autoCompactThreshold: 75 no settings.json global e esqueça. Para sessões críticas, use /compact manualmente antes de iniciar uma tarefa complexa — assim o modelo começa com o máximo de espaço disponível.

🗝️ API Key e autenticação

API Key é a senha de acesso ao serviço de modelo. O Claude Code envia essa chave em cada requisição para provar que você tem permissão de usar a API. Cada serviço tem um formato diferente.

API Keys por serviço

Serviço	Formato da Key	Onde obter	Custo
Anthropic (oficial)	sk-ant-api03-...	console.anthropic.com	Pago por token
OpenRouter	sk-or-v1-...	openrouter.ai/keys	Free tier disponível
Ollama (local)	ollama (qualquer texto)	Não precisa	Gratuito

⚠️ Segurança: nunca exponha sua API Key

✗Nunca commitar a API Key no git (nem em arquivo .env)
✗Nunca colocar a key diretamente no CLAUDE.md
✗Nunca compartilhar a key em screenshots ou vídeos
✓Usar variável de ambiente ou settings.json (não versionado)
✓Adicionar .claude/settings.json ao .gitignore se contiver keys

⚙️ settings.json

O settings.json é o arquivo de configuração central do Claude Code. Existe em dois níveis: global (para todos os projetos) e por projeto (sobrescreve o global naquele projeto).

Localização dos arquivos

Global (todos os projetos)

              # Linux / Mac:

              ~/.claude/settings.json

              # Windows:

              %USERPROFILE%\.claude\settings.json

Por projeto (sobrescreve global)

              # Na raiz do projeto:

              .claude/settings.json

              # Adicionar ao .gitignore se tiver keys!

settings.json completo para Ollama

          {

            "env": {

              "ANTHROPIC_BASE_URL": "http://localhost:11434",

              "ANTHROPIC_AUTH_TOKEN": "ollama",

              "ANTHROPIC_API_KEY": ""

            },

            "autoCompactThreshold": 75,

            "permissions": {

              "allow": ["Bash(npm test)", "Bash(git status)", "Bash(git diff)"]

            }

          }

settings.json completo para OpenRouter

          {

            "env": {

              "ANTHROPIC_BASE_URL": "https://openrouter.ai/api/v1",

              "ANTHROPIC_API_KEY": "sk-or-v1-sua-chave-aqui"

            },

            "autoCompactThreshold": 75

          }

💡 Hierarquia de configuração

A ordem de prioridade, do menor para o maior:

1.Settings global (~/.claude/settings.json) — base padrão
2.Settings de projeto (.claude/settings.json) — sobrescreve o global
3.Variáveis de ambiente exportadas no terminal — sobrescreve tudo

🌐 Variáveis de ambiente

Variáveis de ambiente são pares chave=valor acessíveis por processos do sistema operacional. É a forma padrão de passar configuração sensível (como chaves de API) para programas sem hardcodar nos arquivos.

🐧 Linux e macOS

Usando o terminal (bash/zsh):

            # Apenas para a sessão atual (desaparece quando fechar o terminal):

            export ANTHROPIC_BASE_URL="http://localhost:11434"

            export ANTHROPIC_API_KEY="ollama"

            # Para persistir em todas as sessões (adicionar ao arquivo de perfil):

            echo 'export ANTHROPIC_BASE_URL="http://localhost:11434"' >> ~/.bashrc

            echo 'export ANTHROPIC_API_KEY="ollama"' >> ~/.bashrc

            source ~/.bashrc

            # Verificar se foi definida:

            echo $ANTHROPIC_BASE_URL

Para zsh: use ~/.zshrc em vez de ~/.bashrc

🪟 Windows — Prompt de Comando (CMD)

            :: Apenas para a sessão atual:

            set ANTHROPIC_BASE_URL=http://localhost:11434

            set ANTHROPIC_API_KEY=ollama

            :: Para persistir (permanente no sistema):

            setx ANTHROPIC_BASE_URL "http://localhost:11434"

            setx ANTHROPIC_API_KEY "ollama"

            :: Verificar:

            echo %ANTHROPIC_BASE_URL%

Após setx, feche e reabra o terminal para as variáveis entrarem em vigor.

💙 Windows — PowerShell

            # Apenas para a sessão atual:

            $env:ANTHROPIC_BASE_URL = "http://localhost:11434"

            $env:ANTHROPIC_API_KEY = "ollama"

            # Para persistir (usando [System.Environment]):

            [System.Environment]::SetEnvironmentVariable(

              "ANTHROPIC_BASE_URL",

              "http://localhost:11434",

              "User"

            )

            # Verificar:

            $env:ANTHROPIC_BASE_URL

⚠️ Lembre-se: export é temporário

O export sem adicionar ao .bashrc/.zshrc dura apenas a sessão atual. Fechar o terminal = variável some. Por isso, recomendamos usar o settings.json — ele sempre persiste.

🔄 Sessão vs configuração permanente

Este é um dos pontos de maior confusão no início. Há três formas de configurar o Claude Code, cada uma com escopo diferente. Saber qual usar evita horas de debug.

Comparativo de métodos de configuração

export VAR=valor (sem .bashrc)

Temporário

Dura apenas a sessão do terminal atual. Fechar o terminal = configuração perdida. Útil para testar uma configuração rapidamente.

              export ANTHROPIC_BASE_URL="http://localhost:11434"

              claude  # funciona

              # fechar terminal...

              claude  # erro: variável não definida

echo 'export...' >> ~/.bashrc

Semi-permanente

Persiste entre sessões, mas depende do shell usado e do sistema. Pode ser sobrescrito por outras ferramentas. Bom para Linux/Mac.

              echo 'export ANTHROPIC_BASE_URL="http://localhost:11434"' >> ~/.bashrc

              source ~/.bashrc

              # agora funciona mesmo reabrindo o terminal

settings.json

Recomendado

Persiste sempre. Funciona em todos os sistemas operacionais. Pode ser global ou por projeto. A solução mais confiável e portável.

              // ~/.claude/settings.json

              {

                "env": {

                  "ANTHROPIC_BASE_URL": "http://localhost:11434",

                  "ANTHROPIC_API_KEY": "ollama"

                }

              }

💡 Recomendação final

Configure tudo no settings.json global (~/.claude/settings.json). Funciona em qualquer projeto, em qualquer terminal, sempre. Use export apenas para testar configurações antes de gravar permanentemente.

📝 CLAUDE.md básico de referência

Para começar qualquer projeto, crie um CLAUDE.md na raiz com pelo menos isso:

          # CLAUDE.md

          ## Projeto

          Nome e descrição breve do projeto.

          ## Stack

          - [Linguagem e versão]

          - [Framework principal]

          - [Banco de dados, se houver]

          ## Convenções

          - [Padrão de código: tabs/spaces, aspas, etc.]

          - [Estilo de nomenclatura: camelCase, snake_case, etc.]

          ## Comandos importantes

          - `npm run dev` — inicia o servidor de desenvolvimento

          - `npm test` — roda os testes

          - `npm run build` — gera o build de produção

          ## Regras

          - Sempre rodar os testes antes de commitar

          - Nunca modificar arquivos em dist/ diretamente

✅ Resumo do Módulo 1.3

✓

Token — unidade mínima de texto; 1 palavra ≈ 1.3 tokens em português

✓

Compactação — /compact manual ou autoCompactThreshold: 75 no settings.json

✓

API Key — senha de acesso; Ollama aceita qualquer texto, OpenRouter usa sk-or-v1-...

✓

settings.json — global (~/.claude/) ou por projeto (.claude/); projeto sobrescreve global

✓

Variáveis de ambiente — export (Linux/Mac), setx (Windows CMD), $env: (PowerShell)

✓

settings.json > export — o settings sempre persiste; export some ao fechar o terminal

Parabéns! Você concluiu a Trilha 1.

Agora você tem a base conceitual completa. A próxima trilha é a instalação prática do Claude Code e configuração do ambiente.

← Módulo Anterior Próxima Trilha: Instalação →