Por dentro do Claude Code: 9 lições do novo artigo de arquitetura em nível de código

O que o artigo realmente é

Em 14 de abril de 2026, quatro pesquisadores — Jiacheng Liu, Xiaohan Zhao, Xinyi Shang e Zhiqiang Shen, com autoria de correspondência de Zhiqiang Shen (MBZUAI) — subiram ao arXiv um passeio de 70 páginas pela arquitetura do Claude Code. Eles não tiveram acesso interno. Trabalharam a partir do build TypeScript distribuído publicamente (v2.1.88), rastrearam arquivos como query.ts, permissions.ts e tools.ts, e conferiram a leitura deles contra um agente de código aberto independente chamado OpenClaw. O resultado é o primeiro relato completo, em nível de código-fonte, de como um agente de programação em produção é de fato montado.

Nós lemos para você não precisar ler. As lições abaixo são as partes que deveriam mudar o seu jeito de pensar sobre construir o seu próprio arcabouço de agente. O trabalho é dos autores; se algo disso for útil, por favor cite o original.

O laço é minúsculo — o arcabouço é tudo

Aquilo que todo tutorial chama de "o agente" é, no Claude Code, um ciclo while-true: chamar o modelo, interpretar os blocos tool_use que ele devolveu, passá-los pelo sistema de permissões, despachá-los para as ferramentas, anexar o resultado, repetir. É isso. A análise da comunidade citada no artigo estima a parte de lógica de decisão do modelo em cerca de 1,6% do código; os outros 98,4% são a infraestrutura operacional em volta do laço — montagem de contexto, permissões, roteamento de ferramentas, isolamento, recuperação. A única função queryLoop() em query.ts roda tanto na CLI interativa quanto no caminho sem interface claude -p, no SDK de agentes ou numa integração com editor. Só a renderização muda.

Se você levar uma coisa só do artigo, leve esta: o agente não é um modelo com um prompt. É um arcabouço determinístico dentro do qual um modelo tem permissão para decidir. O modelo nunca acessa o sistema de arquivos diretamente, nem roda comandos de shell, nem faz requisições de rede. A única interface dele com o mundo é o protocolo estruturado tool_use, que o arcabouço valida antes de executar. Um modelo comprometido ou manipulado de forma adversária não consegue burlar as regras implementadas no arcabouço, porque raciocínio e imposição vivem em caminhos de código diferentes.

Cinco valores, treze princípios

Os autores não descrevem a arquitetura como uma lista de recursos. Eles identificam cinco valores humanos — autoridade de decisão humana, segurança, proteção e privacidade, execução confiável, ampliação de capacidade, adaptabilidade ao contexto — e os seguem por treze princípios de projeto, cada um respondendo a uma pergunta recorrente que qualquer agente de programação em produção precisa resolver. Alguns desses princípios vão soar familiares para quem já perdeu uma tarde com um agente desgovernado:

• Negar primeiro, com escalonamento humano — ações não reconhecidas são negadas ou escalonadas, nunca permitidas em silêncio.
• Defesa em profundidade com mecanismos em camadas — várias camadas de segurança independentes, cada uma capaz de bloquear sozinha.
• Contexto como recurso escasso, com gestão progressiva — trate a janela de contexto como a restrição que manda e administre-a em etapas.
• Avaliação de risco ponderada por reversibilidade — supervisão mais leve para ações somente leitura e reversíveis, mais pesada para as destrutivas.
• Estado durável somente de acréscimo — mude o mínimo possível; preserve as trilhas de auditoria.
• Julgamento do modelo dentro de um arcabouço determinístico — confie no raciocínio do modelo, mas só dentro de guardas que o arcabouço consiga impor.
• Andaime mínimo, arcabouço operacional máximo — invista em roteamento de ferramentas e recuperação, não em grafos de planejamento explícitos.

Catalogá-los torna as escolhas legíveis. Se o seu arcabouço embute princípios diferentes — "grafos de planejamento explícitos" em vez de "andaime mínimo", ou "isolamento em contêiner" em vez de "avaliação de negar primeiro" — você vai ter LangGraph, SWE-Agent ou Aider em vez do Claude Code, e isso é uma escolha deliberada, não um acidente.

Negar primeiro porque as pessoas dizem sim 93% das vezes

O dado empírico mais útil do artigo vem do próprio modelo de ameaças do modo automático da Anthropic: quem usa a ferramenta aprova cerca de 93% dos pedidos de permissão. Esse número não é uma vitória. Ele significa que a confirmação interativa não é confiável como único mecanismo de segurança, porque depois que a gente se acostuma, assina sem olhar.

A resposta arquitetural é em camadas. A pré-filtragem de negação total tira as ferramentas proibidas da visão do modelo já na montagem do conjunto de ferramentas — o modelo nunca vê ferramentas que não pode rodar, então nunca gasta um turno propondo-as. Regras de negação valem mais que regras de perguntar, que valem mais que regras de permitir, mesmo quando a regra de permitir é mais específica. Um classificador de aprendizado de máquina opcional no modo automático corre contra o diálogo do usuário quando BASH_CLASSIFIER está ativo, aprovando na hora as ações seguras de alta confiança e escalonando o resto. Por baixo de tudo isso fica um sandbox de shell opcional. Os sete modos de permissão documentados no artigo (plan, default, acceptEdits, auto, dontAsk, bypassPermissions, mais o bubble interno usado no escalonamento de subagentes) são pontos em um espectro graduado de confiança, não interruptores.

Um detalhe sutil que vale destacar: quando o classificador ou uma regra de negação bloqueia uma ação, o sistema trata a negação como sinal de roteamento e não como parada seca. O modelo recebe o motivo da negação, revisa a abordagem e tenta algo mais seguro na iteração seguinte. A imposição de permissões molda o comportamento em vez de interrompê-lo.

Contexto como um pipeline de cinco estágios, não um botão só

Modelos de contexto longo não eliminam o problema do contexto; eles o deslocam. O Claude Code roda cinco compactadores distintos antes de cada chamada ao modelo, em ordem crescente de custo:

1. Redução de orçamento — corta no lugar as saídas de ferramenta grandes demais, trocando-as por referências ao conteúdo.
2. Poda — corte leve do histórico, controlado por HISTORY_SNIP.
3. Microcompactação — compressão de granulação fina com um caminho opcional consciente do cache, que adia as decisões de fronteira até depois da resposta da API para poder usar os cache_deleted_input_tokens reais em vez de estimativas.
4. Colapso de contexto — uma projeção em tempo de leitura sobre a conversa, de modo que o modelo vê a visão colapsada enquanto o histórico completo continua intacto para retomada.
5. Compactação automática — um resumo gerado pelo modelo que só dispara quando todo o resto falhou.

Cada camada trata um tipo de pressão diferente. As camadas baratas rodam antes das caras. CLAUDE.md com carga preguiçosa, esquemas de ferramenta adiados e retornos de subagente só com resumo são amortecedores extras de custo de contexto em volta do laço. Se o seu arcabouço tem um único mecanismo de resumo automático, ele tem o número errado.

Quatro superfícies de extensão, não uma megaAPI

Servidores MCP, plugins, habilidades e ganchos. Cada um se conecta em um ponto de injeção diferente e a um custo de contexto diferente.

• MCP é o caminho de integração de ferramentas externas, com transportes stdio, SSE, HTTP, WebSocket, SDK e específicos de editor.
• Plugins empacotam vários tipos de componente em uma unidade de distribuição — comandos, agentes, habilidades, ganchos, servidores MCP e LSP, estilos de saída, canais, ajustes e configuração de usuário.
• Habilidades são arquivos SKILL.md com cabeçalho YAML; as instruções delas só entram no contexto quando invocadas, então saem baratas enquanto ficam paradas.
• Ganchos disparam em um de 27 eventos documentados — PreToolUse, PostCompact, SessionStart, FileChanged, SubagentStop e assim por diante — com quatro tipos de comando persistíveis (shell, prompt, http, agente) e uma variante de retorno de chamada em tempo de execução para uso no SDK.

A recusa deliberada em entregar uma única API de extensão unificada é, ela mesma, uma decisão de projeto. A extensão é estratificada de modo que os mecanismos de baixo custo sejam favorecidos e os caros (ferramentas sempre ativas, respostas MCP grandes) sejam opcionais.

Subagentes são isolamento, não paralelismo

O erro que a maioria de quem constrói agentes comete com subagentes é tratá-los como trabalhadores de um pool. O artigo torna explícita a leitura alternativa. Os subagentes do Claude Code criam janelas de contexto novas e isoladas; não compartilham o estado de permissões nem a transcrição do pai; devolvem ao pai apenas texto de resumo. O isolamento baseado em worktree permite que um subagente rode em um worktree do git literalmente separado da árvore de trabalho do usuário. O objetivo não é vazão — é limitar o raio de estrago de uma tarefa delegada. Se você quisesse paralelismo, construiria de outro jeito.

Estado somente de acréscimo — auditabilidade acima de poder de consulta

As transcrições de sessão são arquivos JSONL somente de acréscimo, com correção de cadeia em tempo de leitura. As permissões deliberadamente não são restauradas ao retomar — os autores apontam isso como escolha de segurança, não descuido. Até a compactação é implementada, quando possível, como uma projeção em tempo de leitura sobre o histórico completo, e não como uma edição destrutiva.

O custo é real e explícito: consultas estruturadas do tipo "todas as chamadas de ferramenta em todas as sessões que tocaram o arquivo X" exigem reconstrução posterior. Os autores ligam esse compromisso de volta à autoridade de decisão humana — dá para auditar porque nada é sobrescrito.

Três padrões que aparecem em toda parte

Quando os autores se afastam para olhar o todo, três compromissos aparecem em cada subsistema que eles analisam:

1. Estratificação graduada em vez de mecanismos monolíticos. O sistema de permissões tem sete estágios; a gestão de contexto tem cinco compactadores; a extensibilidade tem quatro mecanismos. Cada camada é auditável de forma independente.
2. Somente acréscimo acima de poder de consulta — em toda parte. Logs, transcrições, memória, saídas de ganchos.
3. Julgamento do modelo dentro de um arcabouço determinístico. O arcabouço cria as condições para o modelo decidir bem e depois sai do caminho.

Esses três são bons pontos de checagem ao revisar o seu próprio projeto. Se um subsistema é monolítico, muda estado ou restringe as escolhas do modelo de forma procedural, você provavelmente escolheu um ponto diferente do espaço de projeto daquele que o Claude Code escolheu. Pode ser a decisão certa — mas vale fazer de propósito.

Seis perguntas em aberto para quem construir o próximo

A seção final do artigo é a mais generosa. Ela nomeia seis direções em aberto, cada uma com citações suficientes para ocupar um time de pesquisa por um trimestre:

• A lacuna entre observabilidade e avaliação. Pesquisas do setor mostram que cerca de 89% dos times entrega observabilidade mas só 52% faz avaliação offline, e a Bessemer estima que 78% das falhas de IA são invisíveis. Fechar essa lacuna provavelmente exige andaime na camada do arcabouço (separação gerador-avaliador, contratos de sprint, verificações posteriores) e não melhorias de modelo.
• Persistência entre sessões. O que existe entre as instruções estáticas do CLAUDE.md e a transcrição JSONL de cada sessão? Manuais de estratégia curados automaticamente a partir de sessões passadas são a próxima camada natural.
• Evolução da fronteira do arcabouço nos eixos onde, quando, o quê e com quem. Agentes gerenciados virtualizam sessão, arcabouço e sandbox; pulsos proativos no estilo KAIROS mudam quando o agente age; o trabalho em visão-linguagem-ação muda sobre o quê ele age; topologias multiagente mudam com quem.
• Escalonamento de horizonte — da sessão ao programa científico. Se as mesmas primitivas que funcionam para um turno e uma sessão continuam funcionando ao longo de semanas de pesquisa autônoma.
• Governança. A Lei de IA da União Europeia entra em plena aplicação em agosto de 2026, e apenas 13,3% dos sistemas agênticos indexados publica fichas de segurança específicas do agente.
• A lente avaliativa. A preocupação do próprio artigo: a ampliação de capacidade no curto prazo pode corroer a capacidade humana no longo prazo. Um estudo interno da própria Anthropic encontrou uma queda de 17% na compreensão de quem programa com ajuda de IA. Vale manter uma coluna no painel de projeto para isso.

Essas são as partes da pilha de agentes com maior chance de parecerem completamente diferentes daqui a 18 meses.

Créditos e fonte

Este artigo é um resumo. O trabalho é dos autores. A referência completa é:

Jiacheng Liu, Xiaohan Zhao, Xinyi Shang, Zhiqiang Shen. "Dive into Claude Code: The Design Space of Today's and Future AI Agent Systems." arXiv:2604.14228 [cs.SE], 14 de abril de 2026. Código: github.com/VILA-Lab/Dive-into-Claude-Code. CC BY-NC-SA 4.0. Autor de correspondência: Zhiqiang Shen (MBZUAI).

Se você só tem tempo para partes do original, vá para a seção 2 (a tabela de valores e princípios), a seção 4 (o pipeline de compactação) e a seção 11 (as tensões de projeto transversais). O artigo é a fonte da verdade; este post é só um guia de leitura.

Leitura relacionada neste site: O que é MCP?, Os melhores servidores MCP em 2026, Cursor vs Windsurf vs Claude Code.