A primeira vez que usei o Claude Code para refatorar um módulo inteiro, tive uma experiência quase mística. Descrevi o que queria, fui buscar um café, e quando voltei tinha um pull request com 14 arquivos alterados, testes atualizados e uma mensagem de commit decente. “Isso é mágica”, pensei.

Não é mágica. É um while loop.

Michael Bolin, da OpenAI, publicou recentemente um artigo onde desvenda o funcionamento interno do Codex CLI. E acontece que o segredo por trás dos AI coding agents não é um algoritmo revolucionário nem uma rede neural misteriosa. É um loop que chama um LLM, executa ferramentas, e repete até não sobrar nada para fazer.

Vamos abri-lo no bisturi.

A máquina de estados: 5 fases e um loop

Todo coding agent — Codex, Claude Code, Cursor, tanto faz — executa o mesmo padrão fundamental. Michael Bolin descreve como um loop de 5 fases:

flowchart TD
    A["1. Prompt Assembly\n(montar o prompt)"] --> B["2. Inference\n(enviar ao LLM)"]
    B --> C{¿Tool call?}
    C -->|Sim| D["3. Tool Invocation\n(executar ferramenta)"]
    D --> E["4. Tool Response\n(retornar resultado ao LLM)"]
    E --> B
    C -->|Não| F["5. Assistant Message\n(resposta final)"]
    F -->|Novo input| A

    style A fill:#2d3748,stroke:#4a9eed,color:#fff
    style B fill:#2d3748,stroke:#4a9eed,color:#fff
    style C fill:#4a3728,stroke:#ed9a4a,color:#fff
    style D fill:#2d3748,stroke:#4a9eed,color:#fff
    style E fill:#2d3748,stroke:#4a9eed,color:#fff
    style F fill:#283d28,stroke:#4aed5c,color:#fff

Em termos simples:

  1. Prompt Assembly: monta um prompt gigante com tudo que o agente precisa saber — sua mensagem, as instruções do sistema, as ferramentas disponíveis, arquivos que leu, e o histórico completo da conversa.
  2. Inference: esse prompt é tokenizado e enviado ao modelo. O modelo retorna um stream de eventos: raciocínio interno, tool calls, ou texto de resposta.
  3. Tool Invocation: se o modelo pede para executar uma ferramenta (ler um arquivo, rodar um comando, escrever código), ela é executada. Se falha, o erro volta para o modelo.
  4. Tool Response Loop: o resultado da ferramenta volta para o modelo como contexto adicional. E os passos 2-4 se repetem até o modelo não pedir mais ferramentas.
  5. Assistant Message: quando o modelo decide que terminou, emite uma mensagem final e o ciclo se fecha.

É só isso. Não há grafos de conhecimento, nem planejadores simbólicos, nem arquiteturas sofisticadas. É um loop while com um LLM dentro.

A diferença entre um agente bom e um ruim não está na arquitetura do loop — que é idêntica — mas nos detalhes de cada fase.

Fase 1: A arte de montar um prompt

A primeira fase é onde tudo acontece. Antes do LLM ver uma única linha do seu código, o agente tem que construir um prompt que inclua:

flowchart LR
    subgraph Prompt["Prompt Assembly"]
        direction TB
        SP["System Prompt\n(personalidade, regras)"]
        Tools["Ferramentas disponíveis\n(Read, Write, Bash, MCP...)"]
        Ctx["Arquivos / imagens\nlidos anteriormente"]
        Inst["CLAUDE.md / AGENTS.md\n(instruções do repo)"]
        Env["Info do ambiente\n(OS, shell, git status)"]
        Hist["Histórico da\nconversa"]
        User["Mensagem do usuário"]
    end

    SP --> Final["Prompt\ncompleto"]
    Tools --> Final
    Ctx --> Final
    Inst --> Final
    Env --> Final
    Hist --> Final
    User --> Final

    style Final fill:#283d28,stroke:#4aed5c,color:#fff

Aqui já vemos uma decisão de design crítica: a ordem importa. O prompt é construído do mais estável ao menos estável. O system prompt vai primeiro (nunca muda), depois as ferramentas (raramente mudam), depois arquivos e histórico (crescem a cada interação), e por último sua mensagem mais recente.

Por que essa ordem? Por causa do prompt caching. Como o cache funciona por coincidência exata de prefixo, se você coloca o conteúdo estável no início, maximiza a quantidade de tokens que são lidos do cache em cada iteração. Mudar algo no início invalida tudo que vem depois. Já falei sobre isso em detalhes em meu artigo sobre prompt caching, mas a ideia chave é: a ordem do seu prompt não é cosmética, é econômica.

E depois temos os arquivos CLAUDE.md e AGENTS.md. Ambos são o equivalente a deixar um bilhete para o encanador antes de sair de casa: “a chave de registro está embaixo da pia, não mexa no cano azul”. O agente os lê na inicialização e os injeta em cada prompt. São seu mecanismo para dar contexto sem ter que se repetir toda vez.

O problema quadrático: por que o contexto cresce como uma bola de neve

Aqui vem o tapa na cara da realidade. Cada iteração do loop envia toda a conversa completa para o modelo. Não há estado no servidor. Cada request é independente, stateless.

Por quê? Porque assim o provedor pode garantir Zero Data Retention — seus dados não persistem nos servidores entre requisições. É uma decisão de privacidade, não de eficiência.

Mas tem um custo brutal:

flowchart LR
    subgraph Msg1["Iteração 1"]
        S1["System\n10K tok"] --> U1["User\n500 tok"]
    end

    subgraph Msg5["Iteração 5"]
        S5["System\n10K tok"] --> H5["Histórico\n40K tok"] --> U5["User\n500 tok"]
    end

    subgraph Msg20["Iteração 20"]
        S20["System\n10K tok"] --> H20["Histórico\n180K tok"] --> U20["User\n500 tok"]
    end

    style Msg1 fill:#1a2332,stroke:#4a9eed,color:#fff
    style Msg5 fill:#2a2332,stroke:#9a4eed,color:#fff
    style Msg20 fill:#3a1a1a,stroke:#ed4a4a,color:#fff

Na iteração 1 você envia 10K tokens. Na 5, envia 50K. Na 20, envia 190K. Cada mensagem reenvia todo o histórico anterior. E como o mecanismo de self-attention do transformer tem custo quadrático em relação ao número de tokens, não só cresce a quantidade de dados enviados — cresce o custo computacional de processá-los.

Ou seja: a iteração 20 não custa 20 vezes mais que a primeira. Custa muito mais.

Compaction: comprimir sem perder o importante

Tanto Codex quanto Claude Code têm uma solução para o crescimento descontrolado do contexto: compaction (ou compressão automática).

Quando o histórico se aproxima do limite da janela de contexto, o agente faz algo inteligente: envia todo o histórico para um endpoint especial que gera uma representação comprimida. Em vez de 180K tokens de conversa, você obtém talvez 20K que capturam as decisões tomadas, os arquivos modificados e o estado atual da tarefa.

flowchart TD
    Full["Histórico completo\n180K tokens"] --> Check{¿Perto do limite?}
    Check -->|Não| Continue["Continuar normalmente"]
    Check -->|Sim| Compact["Compaction endpoint"]
    Compact --> Summary["Resumo comprimido\n~20K tokens"]
    Summary --> NewCtx["Novo contexto\n= System + Resumo + Última mensagem"]
    NewCtx --> Continue2["Continuar com contexto fresco"]

    style Full fill:#3a1a1a,stroke:#ed4a4a,color:#fff
    style Summary fill:#283d28,stroke:#4aed5c,color:#fff
    style Compact fill:#2d3748,stroke:#4a9eed,color:#fff

Atenção: a compressão não é de graça. Você perde detalhes. O modelo não tem mais acesso ao diff exato que você fez no passo 7, mas a um resumo que diz “foi refatorado o módulo de autenticação”. Para a maioria das tarefas é suficiente. Para debug cirúrgico, pode ser um problema.

Codex chama de compaction. Claude Code faz algo equivalente com compressão automática de contexto. A ideia é idêntica: quando o contexto sai de controle, você comprime o passado e segue em frente com uma versão mais leve.

Sandbox: a gaiola dourada

Ambos os agentes executam ferramentas em um sandbox — um ambiente restrito onde o acesso à rede e ao sistema de arquivos é limitado por padrão.

Isso é fundamental. Sem sandbox, um rm -rf / gerado por alucinação do modelo destruiria sua máquina. Com sandbox, o pior cenário é que quebre algo dentro dos limites permitidos.

Claude Code pede confirmação para cada operação potencialmente destrutiva (a menos que você aprove explicitamente). Codex CLI opera por padrão em um modo similar de permissões explícitas.

A lição aqui não é técnica, é filosófica: um agente que pode fazer qualquer coisa é um agente no qual você não pode confiar. As restrições não são limitações — são garantias.

Codex CLI vs Claude Code: gêmeos não idênticos

Agora vem a parte divertida. Ambos são o mesmo loop por dentro, mas as decisões de design divergem em pontos interessantes:

flowchart TB
    subgraph Codex["Codex CLI (OpenAI)"]
        direction TB
        CG["GUI de desktop\n(Command Center)"]
        CS["Shell genérico\n(bash/terminal)"]
        CA["Automations\n(scheduling nativo)"]
        CD["Diffs com\ncomentários inline"]
    end

    subgraph Claude["Claude Code (Anthropic)"]
        direction TB
        CC["CLI-first\n(terminal nativo)"]
        CT["Ferramentas dedicadas\n(Read, Edit, Grep, Glob)"]
        CK["Skills\n(/blog, /improve...)"]
        CF["Feedback\nconversacional"]
    end

    style Codex fill:#1a2332,stroke:#4a9eed,color:#fff
    style Claude fill:#2a1a32,stroke:#9a4eed,color:#fff

Ferramentas: genérico vs especializado

Codex dá ao modelo acesso a um shell genérico. Se quer ler um arquivo, o modelo executa cat arquivo.py. Se quer buscar texto, executa grep -r "padrão" ..

Claude Code faz o oposto: tem ferramentas dedicadas para cada operação. Read para ler arquivos, Edit para editá-los (com substituição exata de strings, não reescrita completa), Grep para buscar, Glob para encontrar arquivos por padrão.

Qual é melhor? Depende de como você vê. O shell genérico é mais flexível — qualquer coisa que você pode fazer num terminal, o modelo pode fazer. Mas as ferramentas dedicadas são mais seguras e eficientes. Um Edit que só envia o diff da mudança é mais rápido e menos propenso a erros que um cat > arquivo.py << 'EOF' que reescreve o arquivo inteiro.

Minha experiência: as ferramentas dedicadas ganham em 90% dos casos. O shell genérico ganha quando você precisa fazer algo exótico que nenhuma ferramenta cobre.

GUI vs CLI

Codex aposta numa GUI de desktop (Command Center) onde você vê os diffs como num pull request, pode colocar comentários inline nas mudanças, e tem uma vista gráfica do que o agente está fazendo.

Claude Code é CLI puro. Seu terminal. Seu shell. Nada de janelinhas. Se quer revisar uma mudança, o agente mostra em texto. Se quer dar feedback, você escreve como mais uma mensagem na conversa.

O que prefiro? O CLI, sem dúvida. E não por purismo hacker. É que um CLI se integra com tudo: tmux, scripts, cron, pipelines de CI, remote control via SSH. Uma GUI te amarra a uma tela específica. Para sessões interativas a GUI é mais visual, sim. Mas para trabalhar de verdade — tarefas longas, automações, agentes que rodam sozinhos — o CLI não tem concorrência.

Scheduling: nativo vs DIY

Codex tem Automations: você pode programar tarefas que executam automaticamente (reagir a um evento do GitHub, lançar um agente toda manhã, etc.). É scheduling nativo dentro da plataforma.

Claude Code não tem nada disso. Se quer que um agente execute a cada 30 minutos, você coloca um cron ou um systemd timer. Se quer que reaja a um webhook, monta a integração você mesmo.

Aqui Codex tem vantagem objetiva para equipes que querem automação out of the box. Mas a solução DIY do Claude Code tem uma vantagem não óbvia: você controla a infraestrutura. Se Anthropic mudar sua API, seu cron continua funcionando porque é sua máquina. Se OpenAI mudar as Automations, você está ferrado.

O que realmente importa

Depois de desmontar as entranhas de ambos os agentes, a conclusão é quase decepcionante de tão simples:

Um coding agent é um loop que monta um prompt, chama um LLM, executa ferramentas, e repete. Ponto.

A mágica não está no loop. Está em três coisas:

  1. A qualidade do modelo. Um while loop com GPT-3 não faz nada útil. Com Claude Opus ou GPT-4o, refatora módulos inteiros. O loop é o mesmo — o cérebro dentro do loop é o que faz a diferença.

  2. A gestão do contexto. O prompt não pode crescer infinitamente. Como você ordena a informação, quando comprime, o que prioriza ao comprimir — aí é onde a engenharia de verdade importa. Um agente que perde contexto crítico ao comprimir comete erros que um humano nunca cometeria.

  3. O design das ferramentas. Dar a um LLM acesso ao bash sem restrições é como dar as chaves do carro para alguém que nunca dirigiu. As ferramentas bem projetadas (com validação, restrições e feedback claro de erros) são a diferença entre um agente que te ajuda e um que pira e apaga node_modules às três da manhã.

Na próxima vez que seu coding agent fizer algo que parece mágica, lembre-se: é um while True com um LLM dentro. Elegante, sim. Potente, sem dúvida. Mas mágica mesmo… não é bem assim.

Fontes: O artigo principal é “What Actually Happens Inside an AI Coding Agent (We Unrolled It)” de Michael Bolin (OpenAI). A comparação com Claude Code vem da experiência direta e da documentação oficial da Anthropic. Se te interessa o tema do contexto e caching, leia Por que 99% do que você envia para o Claude ele já tem em cache e O cache do seu LLM te cobra o dobro por te economizar dinheiro.

Este artigo foi escrito originalmente em espanhol e traduzido com a ajuda de IA.