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.

isso é 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 de terminal.

aqui está o que o código-fonte revela sobre como realmente usar essa ferramenta.

1. CLAUDE.md é carregado a cada iteração. toda. maldita. iteração.

essa é a ação de maior alavancagem que você pode tomar 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 TODA iteração de consulta. não no início da sessão. a cada turno. isso significa que toda vez que você envia uma mensagem, ele rele suas instruções.

existe toda uma hierarquia:

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

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

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

• CLAUDE.local.md — notas privadas (ignorado pelo git)

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 o claude code 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 gratuito)

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 quase o mesmo que 1 agente fazendo sequencialmente.

leia de novo.

5 agentes. mesmo custo que 1. porque todos acessam 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 tarefa.

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

• fork — herda o contexto pai, otimizado para cache

• teammate — painel separado no tmux ou iterm, comunica-se via mailbox baseado em arquivos

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

você pode dizer ao claude code para gerar 5 agentes: um fazendo 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 é CONSTRUÍDA para isso. usá-lo single-threaded é criminoso.

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:

1policy > flag > local > project > user

no ~/.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 (isso é novo) — executa um classificador LLM em cada ação. esse é 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 múltiplos 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 desperdiçado. configure uma vez. nunca mais clique.

4. existem 5 estratégias de compactação. 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 de ferramentas antigas

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 grupos de mensagens mais antigos

isso nos diz algo importante: 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ê se importa.

• a janela padrão é 200K tokens. mas você pode optar por 1M tokens usando o sufixo de modelo [1m]. para grandes refatorações 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 mais 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, continue em frente.

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

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

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

• PreToolUse — executa antes de qualquer ferramenta ser usada

• PostToolUse — executa depois de qualquer ferramenta ser usada

• UserPromptSubmit — executa quando você envia uma mensagem

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

• e mais 20+

com 5 tipos de hooks:

• command — executa um comando shell

• prompt — injeta contexto via LLM

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

• HTTP — chama um webhook

• function — executa JS

exemplos reais do que você pode fazer:

• executar linting automaticamente antes de toda escrita de arquivo

• executar testes após cada edição

• injetar documentação relevante em todo prompt automaticamente

• enviar uma notificação no slack quando uma tarefa é concluída

• validar que padrões de segurança são seguidos antes do código ser enviado

o hook UserPromptSubmit é especialmente louco. você pode injetar additionalContext em toda mensagem que enviar. imagine anexar automaticamente saída de teste, diffs recentes do git ou estado do projeto a cada prompt sem digitar nada.

é assim que você constrói um ambiente de desenvolvimento personalizado sobre o claude code. não melhorando os prompts. mas 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 passada (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 inicia 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 se 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 60+ ferramentas com agrupamento inteligente

o claude code tem 60+ ferramentas integradas. mas a parte interessante é COMO ele as executa.

o código-fonte particiona chamadas de ferramenta em duas categorias:

• concurrent — operações somente leitura (ler arquivos, pesquisar, glob) executadas em paralelo

• serial — operações de mutação (edições, escritas, comandos bash) 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 ele 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 diferido. ferramentas MCP só carregam quando necessárias, então conectar 5 servidores MCP não desacelera toda requisição.

e há ToolSearch para descoberta diferida 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 interrupção é barata

todo o pipeline usa geradores assíncronos emitindo eventos individuais. pressionar Escape aborta limpa e corretamente 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 limpa e corretamente. zero penalidade.

pense nisso 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 retry é mais sofisticado do que você pensa

o código-fonte revela:

• 10 retentativas com backoff exponencial e jitter (base de 500ms)

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

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

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

• modo persistente tem retry infinito 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 interrupções graciosamente. você não precisa ficar de babá. deixe rodar em segundo plano e volte para ver os resultados.

o resumo: ações de maior alavancagem 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 → 25+ eventos, 5 tipos. essa é a verdadeira API de extensão.

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

• conecte servidores MCP → carregamento diferido significa custo zero até serem usados.

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

a conclusão: o claude code é uma plataforma de orquestração de agentes usando uma UI de terminal.

as pessoas que tiram 10x mais dele não são melhores em prompts. elas configuraram. paralelizaram. se conectaram a hooks. 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 🫶