Como agentes de codificação por IA pré-carregam seu contexto e quando isso sai pela culatra

Você abre o editor e inicia uma sessão. Antes de digitar qualquer coisa, antes mesmo de o cursor se acomodar no campo de entrada, o agente já leu uma quantidade considerável. Ele absorveu o system prompt, as definições de cada ferramenta que pode chamar, as instruções de comportamento, o CLAUDE.md do seu projeto (ou .cursorrules, ou AGENTS.md), quaisquer regras vinculadas a caminhos que se apliquem e tudo o que estiver no seu arquivo de memória. Quando você diz a primeira palavra, o agente já tem um modelo de você, do seu projeto e de como deve se comportar.

O modelo mental ingênuo é: você digita, o agente responde. A sequência real é: o agente lê seu contexto, você digita, o agente responde. É nesse primeiro passo silencioso, com o agente lendo você antes de você falar, que uma parcela surpreendentemente grande do seu resultado é decidida. E as evidências sobre se o contexto que você fornece realmente ajuda são mais incômodas do que a maioria de nós supõe.

A versão curta

• Agentes de codificação com IA carregam contexto pré-escrito antes da sua primeira mensagem: prompts de sistema, definições de ferramentas e arquivos de instruções específicos de cada ferramenta, como CLAUDE.md, regras do Cursor, instruções do GitHub Copilot ou AGENTS.md onde houver suporte ou importação. Não é você quem inicia a conversa; é a leitura do agente.
• Essa pré-carga consome uma fatia significativa da janela de contexto utilizável antes de você digitar um único caractere, então seu orçamento real de trabalho é menor do que a janela anunciada do modelo sugere.
• O achado empírico é a parte contraintuitiva: arquivos de contexto escritos por desenvolvedores ajudam um pouco (cerca de +4% de sucesso nas tarefas) a um custo real (cerca de +19% de custo de inferência), enquanto arquivos de contexto gerados por LLM ou copiados e colados podem deixar os resultados um pouco pior.
• Hospedar seu próprio modelo muda o que você pode ver, não o que você tem que do. A arquitetura de pré-sessão é a mesma em todos os lugares; as ferramentas locais apenas permitem inspecioná-la e auditá-la. A disciplina de escrever contexto que você realmente entende não desaparece.

O modelo ingênuo está errado: o agente lê primeiro

Imagine o momento exato em que uma sessão do Claude Code começa. O prompt de sistema entra. As definições de ferramentas entram. Depois, antes de você dizer qualquer coisa, o seu CLAUDE.md é entregue, e o detalhe mecânico aqui importa. A própria documentação da Anthropic diz explicitamente que O conteúdo de CLAUDE.md é “entregue como uma mensagem de usuário após o prompt do sistema,” carregado “no início de cada conversa.” Portanto, o primeiro turno do usuário na transcrição não é você. É o seu arquivo, falando em seu nome, estabelecendo os termos antes que você chegue.

O que de fato carrega naquele momento inicial é uma pilha: o system prompt, as definições de ferramentas, as instruções de comportamento, seus arquivos de contexto de projeto e de usuário, quaisquer regras vinculadas a caminhos que correspondam aos arquivos em jogo e um arquivo de memória que o próprio agente mantém. No Claude Code, os arquivos de contexto se resolvem por uma hierarquia de quatro níveis (política gerenciada, depois usuário (~/.claude/CLAUDE.md), depois projeto (./CLAUDE.md), depois local (./CLAUDE.local.md)), concatenados nessa ordem. A memória automática acrescenta a sua fatia: as primeiras 200 linhas (ou 25KB) de um MEMORY.md que o agente escreve e lê por conta própria, carregado a cada sessão.

Nada disso é de graça. A sobrecarga de infraestrutura (prompt de sistema, definições de ferramentas, instruções de comportamento) consome uma parcela significativa da janela de contexto efetiva antes mesmo de sua primeira mensagem chegar. Esse é o imposto que você paga para o agente saber ser um agente, e ele é invisível a menos que você vá atrás dele.

Um nome está se formando em torno da disciplina de gerenciar tudo isso. A equipe de IA aplicada da Anthropic chama isso de engenharia de contexto: “o conjunto de estratégias para curar e manter o conjunto ideal de tokens (informação) durante a inferência de um LLM.” É um termo útil porque transforma o arquivo que você escreve: de bilhete para o robô em decisão arquitetural sobre o que ocupa um recurso escasso e caro.

Quatro agentes, quatro formas de te ler primeiro

Os agentes não leem você todos da mesma forma. Eles se dividem ao longo de dois eixos que valem a pena nomear: o que é carregado no início da sessão (uma hierarquia de arquivos curada, em vez de regras sempre ativas ou uma varredura do repositório inteiro), e quanto disso você pode inspecionar, ou seja, se o mecanismo é um artefato determinístico e auditável ou um índice semântico que você precisa aceitar na fé. É nesses dois eixos que Claude Code, Cursor, GitHub Copilot e Aider divergem de verdade.

A divisão do Cursor é a mais instrutiva. Suas regras ficam em arquivos legíveis que você controla, mas ele também cria uma índice semântico de toda a sua base de código, embeddings de vetor que alimentam a pesquisa @codebase e que você não pode realmente inspecionar. Aider fica na outra extremidade: lê todo o seu repositório git e constrói um repo-map, de forma determinística, sem embeddings em lugar nenhum. Você pode auditar exatamente o que foi entregue ao modelo. A mesma inversão arquitetural, com uma visibilidade bem diferente sobre ela. Para a comparação mais profunda ferramenta a ferramenta, cobrimos o cenário das CLIs agênticas no nosso confronto de CLIs de programação agêntica e foram confrontados diretamente em OpenCode versus Claude Code em outro lugar.

Por baixo dos formatos específicos de cada ferramenta, um padrão comum está se consolidando. O AGENTS.md surgiu no ecossistema de ferramentas de agentes (OpenAI Codex, Amp, Jules do Google, Cursor e Factory) e agora é administrado pela Agentic AI Foundation sob a Linux Foundation, adotado em mais de 60.000 repositórios. É o arquivo de contexto pré-sessão sendo promovido de conveniência de uma ferramenta a artefato portátil de primeira classe: a indústria concordando que “o que o agente lê antes de você falar” merece um padrão próprio.

O que as evidências dizem sobre se algo disso ajuda

É aqui que a história confortável se rompe. Uma equipe da ETH Zurich (Gloaguen, Mündler, Müller, Raychev e Vechev) realizou uma avaliação controlada, “Avaliando AGENTS.md,” sobre se esses arquivos de contexto no nível do repositório realmente melhoram o desempenho dos agentes de codificação. Entre os agentes e modelos que estudaram, o resultado não foi “arquivos de contexto funcionam” nem “arquivos de contexto falham”. O resumo atual diz que os arquivos de contexto em geral não melhoram o sucesso das tarefas e aumentam o custo de inferência em mais de 20% na média. Nos resultados detalhados do artigo, os arquivos escritos por desenvolvedores foram a exceção: melhoraram o desempenho em cerca de 4% na média, mas aumentaram o custo em até 19%. Os arquivos gerados por LLM foram na direção errada, reduzindo o desempenho em cerca de 3% na média enquanto elevavam o custo em mais de 20%. Um terceiro achado deixa isso mais nítido: os agentes chamam uma ferramenta de 1,6 a 2,5 vezes mais quando essa ferramenta é citada em um arquivo de contexto, o que ajuda ou atrapalha inteiramente conforme essas chamadas extras fossem ou não justificadas.

Pare um segundo na linha dos ficheiros gerados por LLM, porque é essa que suporta tudo o resto. Um ficheiro que não foi escrito por si, quer tenha sido gerado por um modelo, quer descarregado de um pacote comunitário das «melhores configurações de CLAUDE.md» e largado no seu repositório, soa ao agente como instruções de alguém que não conhece de facto a sua base de código. Nos modelos do estudo, o saldo foi negativo: pagou mais tokens por resultados ligeiramente piores. O análise do Augment Code sobre isso resume bem ao chamar o resultado acumulado de “a gaveta de tranqueiras do contexto do seu agente”. Cada instrução de aparência plausível que você joga lá dentro tem um custo, e as que você não escreveu, para uma base de código que elas não entendem, costumam custar mais do que devolvem.

Eu não leio isso como “arquivos de contexto são ruins” nem como “arquivos de contexto são bons”. São exatamente esses enquadramentos de tudo ou nada que se desfazem no contato com os dados. A leitura mais estreita é esta: contexto é infraestrutura que você arquiteta de forma deliberada, e um arquivo que você não escreveu, para uma base de código que ele não entende, é um custo e não um presente. A ressalva de escopo também importa. Isso é o que o artigo encontrou para os modelos e agentes que testou, não uma lei universal sobre todo LLM. Mas aponta com força em uma direção, e é corroborado do lado do fornecedor: a própria equipe de IA aplicada da Anthropic apontou a mudança para carregar contexto “na hora certa” por meio de ferramentas em tempo de execução, em vez de pré-carregar tudo de antemão, e descreve uma abordagem híbrida que busca alguns dados no início e explora o restante em tempo de execução. Quando a empresa que publica o CLAUDE.md está pendendo para pré-carregar menos, o instinto de copiar e colar um arquivo de contexto gigante merece uma segunda olhada.

Conclusão da seção: a autoria é o sinal que prevê se o contexto compensa. O custo em tokens é o mesmo nos dois casos; o que muda o retorno é se as instruções vieram de alguém que realmente conhece a base de código.

O contexto que se esvai: por que o início da sessão não é a história toda

O pré-carregamento define a restrição. Ele não sustenta a restrição. O que os desenvolvedores vivem esbarrando é na segunda metade da história: o contexto que você organizou com cuidado no início da sessão se desgasta conforme a sessão avança, e faz isso em silêncio.

Uma maneira útil de visualizar isso vem do enquadramento da equipe Mem0, que diz que um a janela de contexto é RAM, não armazenamento, efêmera e limitada, não um lugar permanente onde suas instruções moram. Carregue algo no começo e ele está presente; siga por tempo suficiente sem usá-lo e ele desbota, do jeito que uma variável que você para de referenciar acaba sobrescrita. Esse é o mecanismo por trás de um padrão que pesquisadores descrevem como decaimento de instruções. Um estudo de 2026 por Gamage e colegas descobriu que restrições de omissão são especialmente frágeis: em um cenário testado, a conformidade caiu de 73% no turno 5 para cerca de 33% no turno 16. É um achado de laboratório, não uma constante universal, mas bate com o que muita gente sente em sessões longas.

O limite da sessão é onde fica mais claro. Desenvolvedores em uma discussão no Hacker News relatam que subagentes gerados podem sofrer com problemas de transferência de contexto, então o trabalho repassado no meio da tarefa pode chegar com menos contexto da sessão-pai do que você supunha. E o tempo ocioso tem um custo próprio: em uma thread onde Boris Cherny da Anthropic se manifestou, a discussão aborda como uma sessão ociosa pode disparar uma reconstrução enorme por falha de cache, centenas de milhares de tokens, sem nenhum aviso para você. O fio condutor que a comunidade continua relatando é o silêncio: a compactação roda, o raciocínio anterior é cortado, a qualidade cai e nada na tela avisa que isso aconteceu. Você só percebe que a saída piorou.

O self-hosting te dá mais controle?

Execute tudo você mesmo (Ollama mais Open WebUI, ou um agente como Aider ou Continue.dev apontado para um modelo local) e a resposta honesta para “agora eu tenho mais controle?” é: você ganha mais visibilidade, não mais controle inerente. Essa distinção é todo o ponto.

O que a auto-hospedagem realmente lhe dá é inspeção. Nenhum dado de conversa sai da sua infraestrutura. Você pode ler o system prompt completo em vez de aceitar um proprietário na fé. Com uma ferramenta determinística como o Aider, você pode auditar exatamente o que entrou em cada chamada ao modelo: o repo-map é um artefato legível, não uma caixa-preta semântica como o índice de embeddings do Cursor. Para quem se importa com auditabilidade e reprodutibilidade, com poder responder “o que o agente realmente viu?”, essa possibilidade de inspeção é real e não é pouco.

Mas a inversão arquitetural não se importa com onde o modelo roda. Esteja você em um modelo local via Ollama, no Claude Code contra uma API na nuvem ou no Cursor por assinatura, o agente continua lendo seu contexto de pré-sessão antes de você falar, e você continua tendo de arquitetar esse contexto de forma deliberada. A disciplina é idêntica. Hospedar por conta própria te dá uma janela mais clara para o mecanismo; não te dá um mecanismo diferente e, com certeza, não te livra da lição da ETH Zurich sobre o que acontece quando você carrega um contexto que não escreveu. Então a única mudança que vale a pena tirar de tudo isso: pare de tratar o arquivo de contexto como um presente que você entrega ao agente e passe a tratá-lo como infraestrutura com custo corrente. Escreva o que você realmente entende da base de código, carregue menos em vez de mais e lembre-se de que o agente leu você primeiro, então a versão de você que ele leu deveria ser uma que você assine embaixo.

Perguntas frequentes

Os agentes de codificação por IA leem seus arquivos antes de você digitar qualquer coisa?

Sim. No arranque da sessão, um agente de programação com IA carrega o seu prompt de sistema, as definições das ferramentas e os seus ficheiros de contexto (CLAUDE.md, .cursorrules ou AGENTS.md), juntamente com qualquer repo-map ou ficheiro de memória, tudo antes da sua primeira mensagem. No Claude Code em concreto, o CLAUDE.md é entregue como mensagem de utilizador logo a seguir ao prompt de sistema, pelo que a conversa começa, na prática, com o seu ficheiro e não consigo.

Arquivos de contexto como CLAUDE.md realmente melhoram o desempenho do agente?

Em parte, e menos do que a maioria das pessoas assume. No Avaliação da ETH Zurich de arquivos no estilo AGENTS.md, o resumo atual diz que os arquivos de contexto geralmente não melhoram o sucesso das tarefas e aumentam o custo de inferência em mais de 20% na média. Os resultados detalhados são mais úteis para quem está na prática: arquivos fornecidos por desenvolvedores melhoraram o desempenho em cerca de 4% na média, mas elevaram o custo em até 19%, enquanto arquivos gerados por LLM reduziram o desempenho em cerca de 3% na média e aumentaram o custo em mais de 20%. A leitura prática: um arquivo que você escreveu e entende pode ajudar um pouco; um arquivo que você não escreveu pode custar caro em silêncio.

Quanto da janela de contexto é usado antes de eu enviar uma mensagem?

Uma parcela significativa. O prompt de sistema, as definições de ferramentas e as instruções de comportamento carregam antes de qualquer entrada do usuário e, juntos, consomem uma fatia relevante da janela de contexto efetiva. Seu orçamento de trabalho utilizável é menor que a janela de contexto anunciada do modelo por causa dessa sobrecarga fixa de inicialização.

O self-hosting de um modelo de IA dá mais controle sobre o contexto?

Mais visibilidade, não mais controle intrínseco. Hospedar por conta própria permite inspecionar o prompt de sistema completo, mantém os dados de conversa na sua própria infraestrutura e (com uma ferramenta determinística como o Aider) permite auditar exatamente o que entrou em cada chamada. Mas a arquitetura de contexto pré-sessão é a mesma das ferramentas na nuvem, e você ainda precisa projetar seu contexto de forma deliberada.

O que é AGENTS.md?

AGENTS.md é um formato aberto para dizer aos agentes de código como trabalhar com uma base de código, o equivalente a um README voltado ao agente. Surgiu em todo o ecossistema de ferramentas para agentes (OpenAI Codex, Amp, Jules do Google, Cursor e Factory) e hoje é mantido pela Agentic AI Foundation, sob a Linux Foundation, com adoção em mais de 60.000 repositórios, o que o torna o padrão entre ferramentas que está emergindo para o contexto de agente antes da sessão.