Anatomia completa de como o Claude Code funciona por dentro — do Agentic Loop ao carregamento de contexto

Organizei de forma objetiva os pontos principais de como o Claude Code funciona no terminal, com base na documentação oficial (resumo em Mintlify feito por VineeTagarwaL).

Como o Claude Code funciona?
Em uma frase: é um loop de “ler → pensar → usar ferramentas → ver o resultado → repetir”.
6 etapas do Agentic Loop

1. O usuário insere uma mensagem no terminal (ou ela é passada via --print / stdin)
2. Montagem do prompt do sistema — data atual, estado do git, arquivo CLAUDE.md, lista de ferramentas disponíveis
3. Chamada da API da Anthropic → o modelo gera um bloco tool_use (nome da ferramenta + entrada JSON)
4. Verificação de permissões — decide entre aprovação automática / solicitar confirmação / bloquear
5. Execução da ferramenta → o resultado (conteúdo de arquivo, saída de comando etc.) é adicionado à conversa como tool_result
6. O modelo, após receber o resultado, faz chamadas adicionais de ferramentas ou produz a resposta final — repete até não haver mais chamadas de ferramenta
   O loop roda apenas no processo local do terminal. A menos que seja uma ferramenta que chame explicitamente recursos externos, como WebFetch, WebSearch ou um servidor MCP, arquivos, shell e credenciais não saem da máquina.

Como o contexto é criado?
No início da conversa, dois blocos são montados e anexados antes de todas as chamadas de API.

• Contexto do sistema — branch atual, 5 commits mais recentes, resultado de git status --short (cortado se passar de 2.000 caracteres)
• Contexto do usuário — arquivo de memória CLAUDE.md (busca hierárquica em 4 etapas), data de hoje (Today's date is YYYY-MM-DD)
  Ambos os blocos são armazenados em cache por conversa com lodash/memoize. Ao chamar setSystemPromptInjection(), o cache é reinicializado imediatamente.

Modelo de permissões — quando as ferramentas são executadas?

Resultado	Comportamento
allow	Executa imediatamente e adiciona o resultado à conversa
ask	Pausa temporariamente → exibe um diálogo de confirmação
deny	Recusa → retorna um erro ao modelo

• Modo bypassPermissions: ignora todas as verificações
• Modo acceptEdits: aprova automaticamente edições de arquivo, mas comandos bash ainda pedem confirmação
• Ferramentas somente leitura, como Read, Glob e Grep, têm aprovação automática por padrão em todos os modos

Subagentes (ferramenta Task)
O Claude pode iniciar subagentes com a ferramenta Task (AgentTool). Os subagentes executam seu próprio Agentic Loop com uma conversa isolada e, opcionalmente, com um conjunto de ferramentas restrito; ao concluir, retornam o resultado ao agente pai. Eles podem rodar localmente (in-process) ou em computação remota.

Salvar e restaurar conversas
As conversas são salvas em ~/.claude/ como arquivos de transcrição JSON.

• --resume <session-id> ou apenas --resume para retomar uma conversa anterior
• Ao retomar: carrega todo o histórico de mensagens, refaz a busca pelos arquivos CLAUDE.md e redefine o modo de permissões para o padrão da configuração
• Conversas longas passam por compactação periódica — mensagens antigas são resumidas para gerenciar a janela de contexto. A transcrição original completa é preservada em disco

O que o mecanismo de consulta faz
Cada “turno” é conduzido por query.ts.

• Exibe o streaming de tokens no terminal em tempo real
• Encaminha blocos tool_use para o handler apropriado
• Gerencia o orçamento de tokens e chamadas de ferramentas por turno
• Aciona a compactação quando a janela de contexto enche
• Cada ferramenta tem a propriedade maxResultSizeChars — se o resultado ultrapassar esse limite, ele é salvo em um arquivo temporário e apenas o caminho do arquivo é enviado ao modelo (para evitar overflow da janela de contexto)

Original: How Claude Code works — Mintlify
Referência: é um documento-espelho não oficial em que VineeTagarwaL reorganizou a documentação oficial do Claude Code no Mintlify.​​​​​​​​​​​​​​​​

[jeeeyul]

Desde 2023, a estrutura ReAct aparentemente não mudou muito.