Claude Code: Filosofia e Arquitetura

O código organiza a execução em três camadas distintas — essa separação é o que permite o mesmo binário funcionar em terminal local, IDE, CI/CD e como SDK:

O modelo NÃO roda o loop. O modelo é um dos atores no loop. Quem decide "agora leio o arquivo X, agora compacto contexto, agora peço confirmação ao usuário" é código determinístico — não o LLM.

A documentação oficial agrupa as ferramentas em cinco categorias. No código vazado os schemas completos ocupam cerca de 29.000 linhas:

O detalhe técnico mais importante do Claude Code — e o que explica por que ele vence em tarefas longas — é o auto-compact. Quando a conversa chega a ≈98% da janela do modelo, o harness dispara:

// Pseudo-código do auto-compact
if (contextTokens >= windowSize * 0.98) {
  const summary = await model.summarize({
    history,
    preserve: [
      "objetivo original do usuário",
      "arquivos tocados e seus estados finais",
      "comandos executados com seus resultados",
      "decisões de design feitas até agora",
      "erros encontrados e como foram resolvidos",
    ],
    discard: [
      "tool calls exploratórias já resolvidas",
      "conteúdo de arquivos lidos mas não modificados",
      "tentativas falhadas depois corrigidas",
    ],
  });

  session.replaceHistory(summary);
  // continua a tarefa sem o usuário perceber
}

Isso é fundamentalmente diferente de "truncar as mensagens mais antigas" (o que perderia contexto crítico) ou "passar tudo toda vez" (que estoura a janela). É o que permite uma sessão de 6 horas em uma codebase com milhares de arquivos.

O system prompt do Claude Code é pesado — dezenas de milhares de tokens entre instruções, definições de ferramentas e CLAUDE.md carregados. Mandar tudo de novo a cada turno seria insustentável.

A Anthropic documentou publicamente que, com o cache_control aplicado corretamente, os times internos de managed-agents reduziram p50 de time-to-first-token em ~60% e p95 em mais de 90%. O Claude Code usa os mesmos breakpoints de cache:

Cada ferramenta é classificada por blast radius. O harness valida a tier antes de executar — é o que permite você rodar Claude Code em CI sem se preocupar que ele vai dar rm -rf por acidente.

# Os 4 modos de permissão
Default         → Pergunta antes de qualquer Tier 2
Accept Edits    → Aceita Write/Edit, pergunta Bash
Plan Mode       → Só Tier 1. Produz plano sem executar
Auto (yolo)     → Autoriza tudo. Use em CI ou sandbox isolado

O Claude Code implementa o Model Context Protocol, padrão aberto da Anthropic para expor ferramentas externas ao agente sem precisar alterar o binário. Você configura um servidor MCP em ~/.claude/mcp.json e as ferramentas aparecem no próximo turno.

Limite técnico interessante: o harness expõe 25.000 tokens de saída MCP direto para o modelo. Acima disso, grava em disco (até 500.000 tokens) e passa só um ponteiro — o modelo pode usar Read para puxar o que precisar. Isso evita que um servidor MCP mal-comportado entupa o contexto.

Quando você escreve claude "adiciona validação de email no formulário", o QueryEngine faz:

1. SESSION: carrega sessão (ou cria nova)
   - Lê CLAUDE.md hierárquico (repo → subpasta → cwd)
   - Monta system prompt com cache breakpoints

2. HARNESS: entra no loop
   a. Envia request ao modelo (com prompt caching)
   b. Modelo responde com text + tool_use blocks
   c. Para cada tool_use:
      - Valida tier (Tier 1 auto, Tier 2 respeita modo)
      - Confirma com usuário se necessário
   d. SANDBOX executa: lê arquivo, roda bash, faz grep
   e. Resultado volta como tool_result
   f. Se tokens > 98% janela → auto-compact
   g. Volta ao passo (a) até o modelo emitir stop_reason

3. SESSION: persiste histórico serializado em ~/.claude/

O CLAUDE.md não é um arquivo só — o harness busca e empilha do repo até o cwd. Isso permite convenções por subprojeto:

~/projetos/empresa/
├── CLAUDE.md                # convenções gerais da empresa
├── backend/
│   └── CLAUDE.md            # Go, testes em table-driven
└── frontend/
    └── CLAUDE.md            # TS strict, Tailwind, nunca usar any
        └── CLAUDE.md        # (cwd) regras do sub-app específico

// Ao rodar em frontend/app-x/, o harness injeta os 3 CLAUDE.md
// no system prompt, mais específico tem precedência.

O Claude Code é desacoplado do modelo. O usuário pode escolher:

Flag --model ou /model dentro da sessão. O dispatch de subagents (Task) pode usar modelo diferente do principal — um padrão comum é main=Sonnet, subagents=Haiku para grunt work paralelo.