Como Funciona
Pra usar bem o Claude Code você precisa entender o que está acontecendo por baixo. Não é mágica: é um loop agêntico com regras claras de contexto, ferramentas e permissões. Quem entende essas regras gasta menos token, comete menos erro e consegue extrair muito mais da ferramenta.
O Loop Agêntico
Toda interação com o Claude Code segue o mesmo ciclo:
- Entrada: você digita um prompt ou um hook injeta contexto
- Decisão: o modelo decide o próximo passo (responder, chamar uma ferramenta, planejar)
- Execução: se chamou ferramenta, ela passa pelo sistema de permissões e roda
- Observação: o resultado da ferramenta volta como mensagem para o modelo
- Iteração: repete até a tarefa terminar ou pedir input
Esse loop é o coração do Claude Code. A diferença entre um chatbot e um agente está exatamente nesse passo 3 e 4: a capacidade de executar ações no mundo e observar os efeitos.
A Janela de Contexto
A janela de contexto é o recurso mais importante a gerenciar. Tudo o que o Claude vê (system prompt, CLAUDE.md, auto memory, mensagens da conversa, conteúdo de arquivos lidos, saída de comandos) ocupa espaço nela.
A performance do modelo cai conforme a janela enche. Quando passa de uns 50-60% de uso, ele começa a "esquecer" instruções iniciais e a cometer mais erros. Por isso, gerenciar contexto não é opcional, é parte do trabalho.
O que carrega no início de cada sessão
| Item | Quando carrega | Custo aproximado |
|---|---|---|
| System prompt | Sempre | ~4.200 tokens |
Auto memory (MEMORY.md) | Sempre, primeiras 200 linhas ou 25KB | Variável |
| Environment info | Sempre | ~280 tokens |
| Tools built-in | Sempre | Variável |
| MCP tools | Nomes sempre, schemas sob demanda | Variável |
CLAUDE.md (todos os hierárquicos) | Sempre | Você controla |
| Skills (descrições) | Sempre | Truncado em 1.536 chars cada |
| Skills (corpo completo) | Só quando invocadas | Você controla |
| Subagents (definições) | Sempre | Variável |
Auto-Compaction
Quando a janela está prestes a estourar, o Claude Code faz auto-compaction: resume a conversa pra preservar o que importa (decisões, padrões, arquivos modificados) e libera espaço.
Você pode controlar o que é preservado:
/compact <instruções>- força compactação com foco específico, ex:/compact Foque nas mudanças de API- Adicione no
CLAUDE.md:"Quando compactar, sempre preserve a lista de arquivos modificados e os comandos de teste"
O que sobrevive à compactação
- O
CLAUDE.mdda raiz do projeto é re-lido do disco e re-injetado. - Skills invocadas recentemente são re-anexadas (até 25.000 tokens combinados).
- Mensagens recentes são preservadas.
- Conteúdos lidos antigos somem (e devem sumir mesmo).
CLAUDE.md aninhados em subdiretórios não são re-injetados automaticamente. Eles voltam quando o Claude lê um arquivo daquele diretório de novo.
Tools (Ferramentas)
São as primitivas que o agente usa pra interagir com o mundo. As principais built-in:
| Tool | Função |
|---|---|
Read | Lê arquivos (suporta imagens, PDFs, notebooks) |
Write | Cria arquivos novos ou sobrescreve |
Edit | Substituição exata em arquivo existente |
Bash | Executa comandos shell |
Glob | Busca arquivos por padrão (**/*.tsx) |
Grep | Busca conteúdo via ripgrep |
WebFetch | Busca e analisa conteúdo de URLs |
WebSearch | Pesquisa na web |
Task | Spawna um subagente |
TaskCreate/Update/List | Sistema de tarefas para tracking de progresso |
Cada chamada de ferramenta é registrada na conversa. Conteúdos longos (output de comando, arquivo grande) são preservados na conversa e contam tokens.
Por que isso importa
Cada Read ou Bash que retorna 5.000 linhas é um custo permanente na sua janela. Por isso, prompts específicos que apontam exatamente o que ler (em vez de "explore o projeto") são muito mais eficientes.
Permission Modes
Controlam o nível de aprovação para ações sensíveis. Você troca em tempo real com Shift+Tab:
| Modo | Comportamento |
|---|---|
default | Pede aprovação para ações que modificam o sistema |
acceptEdits | Aceita edits sem perguntar, ainda pede para Bash |
plan | Plan mode: só lê e analisa, não modifica nada |
auto | Classificador de IA decide automaticamente |
dontAsk | Não pede aprovação, mas respeita allowlists |
bypassPermissions | Pula tudo (use com cuidado extremo) |
Os modos podem ser definidos por flag (--permission-mode plan), nas settings (defaultMode) ou via toggle no terminal.
Plan Mode
Vale destaque. No plan mode, o Claude só lê e analisa, sem editar. É o modo certo pra usar quando você quer entender uma codebase ou planejar uma mudança grande sem risco. Quando o plano está pronto, você troca pro modo normal e ele executa.
Esc + Esc → abre menu de rewind (volta a checkpoint)
Shift+Tab → cicla entre permission modes
Ctrl+G (em plan mode) → abre o plano no editor pra você editar
Esc → para a ação atual sem perder contexto
Checkpoints
Toda ação do Claude cria um checkpoint automático. Você pode reverter conversa, código, ou ambos, com /rewind ou duplo Esc. Os checkpoints persistem entre sessões.
Isso muda a forma de trabalhar: em vez de planejar com cuidado cada movimento, você pode pedir pro Claude tentar algo arriscado. Não funcionou? Rewind e tenta outra abordagem.
Importante: checkpoints só rastreiam mudanças feitas pelo Claude. Não substitui git.
Sessões e Persistência
Sessões são salvas localmente. Os comandos relevantes:
claude --continue # Retoma a última conversa do diretório atual
claude --resume # Picker interativo de sessões recentes
claude --resume <nome> # Retoma sessão específica por nome ou ID
claude -n "minha-feature" # Cria sessão com nome descritivo
/rename # Renomeia sessão atual
/clear # Reseta o contexto (mantém a sessão)
Trate sessões como branches: workstreams diferentes em sessões separadas, com nomes descritivos pra você achar depois.
Settings e Configuração
A configuração mora em arquivos JSON em ordem de precedência:
| Local | Escopo |
|---|---|
| Managed policy settings | Toda a organização (MDM/Group Policy) |
.claude/settings.local.json | Projeto, gitignored |
.claude/settings.json | Projeto, versionado |
~/.claude/settings.json | Pessoal, todos os projetos |
Os arrays se mesclam entre layers. Configurações mais específicas vencem as mais genéricas.
Modos de Execução
Claude Code roda em três modos principais:
Interativo
claude no terminal. É o modo padrão, com chat persistente, slash commands, plan mode, etc.
Print (Não-Interativo)
claude -p "prompt" - executa uma vez e sai. Ideal para CI, scripts, hooks de pré-commit, automações:
claude -p "explique o que esse projeto faz"
claude -p "liste todos os endpoints de API" --output-format json
claude -p "analise esse log" --output-format stream-json
Bare
claude --bare -p "..." - modo mínimo que pula auto-discovery de hooks, skills, plugins, MCP servers e CLAUDE.md. Sobe mais rápido. Útil pra scripts que querem só Bash + Read + Edit sem overhead.
Conclusão
O Claude Code é um agente em loop com regras claras de contexto, ferramentas e permissões. Entender essas regras é o que permite usá-lo de forma eficiente. Nos próximos capítulos vamos abrir cada componente em detalhe.
Próximo: Slash Commands e Skills
Referências: