Eu li o código-fonte do Claude Code para que você não precise ler

A maioria das pessoas abre o Claude Code, digita um prompt, espera pela resposta, digita outro prompt.

É como comprar uma Ferrari e só dirigir na primeira marcha.

Eu queria entender por que algumas pessoas parecem tirar 10x mais proveito do Claude Code do que outras. Então fiz o que qualquer pessoa razoável faria: li o código-fonte inteiro (quando digo "eu", quero dizer o Claude Code, é claro).

11 camadas de arquitetura. Milhares de linhas. Uma plataforma de orquestração de agentes disfarçada de chat no terminal.

Aqui está o que o código-fonte revela sobre como usar isso de verdade.

1. O CLAUDE.md é carregado a cada iteração. Toda. Única. Vez.

Isso é a coisa de maior alavancagem que você pode fazer e quase ninguém faz direito.

A maioria das pessoas ou não tem nada no arquivo CLAUDE.md ou escreveu a Bíblia inteira nele.

O código-fonte mostra que o Claude Code lê seus arquivos CLAUDE.md em TODAS as iterações de consulta. Não no início da sessão. A cada turno. Isso significa que toda vez que você envia uma mensagem, ele relê suas instruções.

Existe uma hierarquia completa:

• ~/.claude/CLAUDE.md — global (seu estilo de codificação, preferências)

• ./CLAUDE.md — nível do projeto (decisões de arquitetura, convenções)

• .claude/rules/*.md — regras modulares

• CLAUDE.local.md — anotações privadas (gitignorado)

Você tem 40.000 caracteres. Isso é MUITO. A maioria das pessoas usa talvez 200.

Coloque suas decisões de arquitetura lá. Suas convenções de arquivos. Seus padrões de teste. Suas regras de "nunca faça isso". O modelo as lê a cada turno. Essa é a diferença entre o Claude Code ser um assistente genérico e ser SEU assistente que conhece SUA base de código.

Se você fizer uma coisa depois de ler isso, que seja essa.

2. Subagentes compartilham o cache de prompt (paralelismo é praticamente de graça)

Isso é o que explodiu minha mente.

Quando o Claude Code bifurca um subagente, ele cria uma cópia byte-idêntica do contexto pai. A API armazena isso em cache. Então, gerar 5 agentes para trabalhar em diferentes partes da sua base de código custa pouco mais do que 1 agente fazendo sequencialmente.

Leia de novo.

5 agentes. Mesmo custo que 1. Porque todos atingem o cache de prompt.

A maioria das pessoas usa o Claude Code como um único trabalhador. Uma tarefa de cada vez. Espera terminar. Dá a próxima coisa.

O código-fonte tem literalmente três modelos de execução para subagentes:

• fork — herda o contexto pai, otimizado para cache

• teammate — painel separado no tmux ou iTerm, se comunica via mailbox baseado em arquivo

• worktree — ganha sua própria git worktree, branch isolada por agente

Você pode dizer ao Claude Code para gerar 5 agentes: um fazendo uma auditoria de segurança, um refatorando o módulo de autenticação, um escrevendo testes, um atualizando documentação, um corrigindo bugs. Todos ao mesmo tempo. Todos compartilhando o cache.

A arquitetura é FEITA para isso. Usá-lo single-threaded é um crime.

3. O sistema de permissões foi projetado para ser configurado, não clicado

Toda vez que o Claude Code pergunta "permitir esta ação?" e você clica em sim, isso é uma falha de configuração, não uma funcionalidade.

O código-fonte revela uma cascata de configurações de 5 níveis:

1política > flag > local > projeto > usuário

Em ~/.claude/settings.json você pode definir padrões glob para o que é sempre permitido:

1{
2  "permissions": {
3    "allow": [
4      "Bash(npm *)",
5      "Bash(git *)",
6      "Edit(src/**)",
7      "Write(src/**)"
8    ]
9  }
10}

Existem três modos de permissão:

• bypass — sem verificações de permissão (perigoso, mas rápido)

• allowEdits — permite automaticamente edições de arquivos no diretório de trabalho

• auto (este é novo) — executa um classificador de LLM em cada ação. Este é o ponto ideal.

O modo auto tem suas próprias listas de permitir/negar que você pode configurar. O código-fonte mostra que ele executa vários resolvedores em paralelo: clique do usuário, classificador de hook, bridge, e o primeiro a responder vence.

Cada vez que você para para clicar em "permitir" é tempo perdido. Configure uma vez. Nunca clique novamente.

4. Existem 5 estratégias de compactação. A pressão de contexto é um problema real

O código-fonte tem CINCO maneiras diferentes de comprimir sua conversa quando ela fica muito longa:

1. microcompact — limpeza baseada em tempo de resultados antigos de ferramentas

1. context collapse — resume trechos da conversa

1. session memory — extrai contexto-chave para um arquivo

1. full compact — resume todo o histórico

1. PTL truncation — descarta os grupos de mensagens mais antigos

Isso nos diz algo importante: o estouro de contexto é um problema central no qual os engenheiros gastaram MUITO tempo.

O que isso significa para você:

• Use /compact proativamente. Não espere o sistema compactar automaticamente e perder contexto que você valoriza.

• A janela padrão é de 200K tokens. Mas você pode optar por 1M tokens usando o sufixo de modelo [1m]. Para refatorações grandes em muitos arquivos, isso importa.

• Sessões longas acumulam "session memory" — resumos estruturados de especificações de tarefas, listas de arquivos, estado do fluxo de trabalho, erros e aprendizados. É por isso que retomar uma sessão é melhor do que começar do zero.

• Resultados grandes de ferramentas são armazenados em disco com apenas uma prévia de 8KB enviada ao modelo. Se você colar um arquivo enorme, o modelo pode ver apenas uma fração. Mantenha as entradas focadas.

As pessoas que tiram o máximo proveito do Claude Code usam /compact como um ponto de salvamento manual em um videogame. Preserve o que importa, limpe o que não importa, e continue.

5. O sistema de hooks é a verdadeira API de extensão (25+ eventos de ciclo de vida)

Este é o recurso de usuário avançado que quase ninguém conhece.

O código-fonte revela mais de 25 eventos de ciclo de vida nos quais você pode se conectar:

• PreToolUse — executa antes de qualquer ferramenta ser executada

• PostToolUse — executa depois de qualquer ferramenta ser executada

• UserPromptSubmit — executa quando você envia uma mensagem

• SessionStart / SessionEnd — ciclo de vida da sessão

• e mais de 20 outros

Com 5 tipos de hooks:

• command — executa um comando shell

• prompt — injeta contexto via LLM

• agent — executa um loop de verificação de agente completo

• HTTP — chama um webhook

• function — executa JS

Exemplos reais do que você pode fazer:

• Executar linting automaticamente antes de cada gravação de arquivo

• Executar testes após cada edição

• Injetar documentação relevante em cada prompt automaticamente

• Enviar uma notificação no Slack quando uma tarefa for concluída

• Validar se os padrões de segurança são seguidos antes do código ser enviado

O hook UserPromptSubmit é especialmente louco. Você pode injetar additionalContext em cada mensagem que envia. Imagine anexar automaticamente a saída de testes, diffs recentes do git ou estado do projeto a cada prompt sem digitar nada.

É assim que você constrói um ambiente de desenvolvimento personalizado em cima do Claude Code. Não melhorando os prompts. Conectando-se ao próprio sistema.

6. Sessões são persistentes e retomáveis (pare de começar do zero)

Toda conversa é salva como JSONL em

1~/.claude/projects/{hash}/{sessionId}.jsonl

O código-fonte suporta:

• --continue — retoma sua última sessão

• --resume — escolhe uma sessão passada específica

• --fork-session — ramifica a partir de uma conversa anterior (eu pessoalmente amo isso)

A extração de memória de sessão preserva o contexto chave entre compactações: especificações de tarefas, listas de arquivos, estado do fluxo de trabalho, erros e aprendizados.

A maioria das pessoas começa uma nova sessão toda vez que abre o Claude Code. Isso é como fechar seu IDE e reabri-lo do zero a cada hora. Todo o contexto sobre o que você estava fazendo, o que falhou, o que aprendeu — perdido.

Use --continue. Sempre. Deixe o contexto acumular. Deixe a memória da sessão construir aprendizados ao longo do tempo. O código-fonte literalmente tem infraestrutura para isso. Use-a.

7. O sistema de ferramentas executa mais de 60 ferramentas com agrupamento inteligente

O Claude Code tem mais de 60 ferramentas integradas. Mas a parte interessante é COMO elas são executadas.

O código-fonte particiona as chamadas de ferramentas em duas categorias:

• concurrent — operações somente leitura (ler arquivos, pesquisar, globbing) são executadas em paralelo

• serial — operações de mutação (edições, gravações, comandos bash) são executadas uma de cada vez

Isso significa que quando o Claude Code precisa ler 10 arquivos para entender sua base de código, ele lê todos os 10 simultaneamente. Mas quando precisa editar 3 arquivos, ele os faz um de cada vez para evitar conflitos.

Além das ferramentas integradas, você pode conectar servidores MCP que adicionam mais ferramentas. O código-fonte usa carregamento adiado. As ferramentas MCP só carregam quando necessárias, então conectar 5 servidores MCP não retarda cada requisição.

E há o ToolSearch para descoberta adiada de ferramentas que o agente ainda não conhece.

A conclusão prática: se seu fluxo de trabalho envolve sistemas externos (bancos de dados, provedores de nuvem, CI/CD), conecte servidores MCP para eles. A arquitetura lida com a complexidade. Você só ganha mais capacidades.

8. A arquitetura de streaming significa que interromper é barato

Todo o pipeline usa geradores assíncronos emitindo eventos individuais. Pressionar Escape aborta limpidamente o fluxo atual sem perder o contexto anterior.

Isso parece pequeno, mas muda como você deve usar o Claude Code.

Não espere por uma resposta que você sabe que está indo mal. Interrompa imediatamente e redirecione. O código-fonte é projetado para isso. Seu contexto anterior é preservado. A resposta interrompida é descartada limpidamente. Zero penalidade.

Pense como programação em par. Se seu par começar a ir pelo caminho errado, você não espera ele terminar. Você diz "na verdade, vá por este caminho". Mesma energia.

9. O sistema de repetição é mais sofisticado do que você imagina

O código-fonte revela:

• 10 repetições com backoff exponencial e jitter (base de 500ms)

• Atualização automática de token OAuth em 401/403

• Fallback de modelo: se o Opus falhar 3 vezes com erros 529, ele cai automaticamente para o Sonnet

• Watchdog de 90 segundos de inatividade em streams — se o streaming parar, ele cai para não-streaming

• Modo persistente tem repetição infinita com backoff máximo de 5 minutos

Isso significa que o Claude Code é projetado para ser deixado rodando. Ele lida com soluços de API, limites de taxa e falhas com elegância. Você não precisa ficar de babá. Deixe-o rodar em segundo plano e volte para os resultados.

O resumo: ações de maior alavancagem a partir do código-fonte:

• Escreva um CLAUDE.md de verdade → carregado a cada turno. 40K caracteres. Configuração de maior alavancagem.

• Paralelize com subagentes → modelo fork compartilha cache de prompt. 5 agentes ≈ custo de 1.

• Configure permissões no settings.json → elimine a fadiga de cliques para sempre.

• Use /compact proativamente → 5 estratégias de compactação existem porque a pressão de contexto é real.

• Configure hooks → mais de 25 eventos, 5 tipos. Esta é a verdadeira API de extensão.

• Sempre use --continue para sessões → persistência JSONL + memória de sessão = contexto acumulado.

• Conecte servidores MCP → carregamento adiado significa custo zero até o uso.

• Interrompa livremente → geradores assíncronos significam zero penalidade para redirecionamento.

A conclusão: o Claude Code é uma plataforma de orquestração de agentes vestindo uma UI de terminal.

As pessoas que tiram 10x de resultado dele não são melhores em prompts. Elas o configuraram. Elas o paralelizaram. Elas se conectaram a ele. Elas deixaram o contexto acumular entre sessões.

O código-fonte torna isso óbvio. Agora você sabe o que ele realmente faz por baixo dos panos.

Compartilhe se achou útil 🫶