Orçamento de contexto para agentes de código é a prática de medir o que o agente carrega antes de trabalhar. O prompt visível é só uma parte. Instruções, ferramentas, MCP, histórico, memória e subagentes também entram no custo e podem mudar o resultado.
Em julho de 2026, a Systima publicou uma medição de tráfego entre harnesses de coding agent. No ensaio, Claude Code enviou cerca de 33 mil tokens antes de ler o prompt, enquanto OpenCode enviou cerca de 7 mil (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). O número não prova que uma ferramenta é melhor que outra. Ele prova que contexto precisa de orçamento.
Resumo prático
- Meça o baseline antes de culpar o modelo.
- Corte instrução carregada em toda sessão, não conhecimento útil.
- MCP e subagentes entram no custo por tarefa.
- O CI deve registrar contexto, ferramentas e exceções.
Por que o custo aparece antes do prompt?
Em 2026, a Systima mediu cerca de 33 mil tokens enviados pelo Claude Code antes do prompt, contra cerca de 7 mil no OpenCode (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). Esse custo nasce do harness: sistema, ferramentas, schemas, memórias, instruções e lembretes que chegam antes da tarefa.
O agente não começa vazio. Ele carrega contratos de ferramenta, política de execução, instruções persistentes, estado da conversa e pistas do repositório. Em um loop curto, esse custo parece aceitável. Em um loop longo, ele vira imposto recorrente sobre cada tentativa, teste, correção e revisão.
Esse é o ponto que muitos times perdem ao otimizar prompt. O prompt pode estar enxuto, mas o agente ainda pode carregar um pacote grande de contexto automático. O trabalho correto começa com uma pergunta simples: o que entrou no modelo antes do pedido do usuário?
Cápsula citável: Orçamento de contexto em agentes de código começa antes do prompt visível. A medição da Systima em 2026 encontrou cerca de 33 mil tokens iniciais no Claude Code e cerca de 7 mil no OpenCode, mostrando que harness e configuração definem o piso operacional.
O que medir antes de cortar contexto?
Em 2026, a Systima relatou que um arquivo de instrução de 72 KB adicionou pouco mais de 20 mil tokens por requisição nos dois harnesses testados (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). Antes de cortar conteúdo, separe baseline, instruções, ferramentas e histórico em categorias auditáveis.
Eu começo por cinco medidas. O baseline é o payload sem tarefa real. A camada de instrução cobre AGENTS.md, CLAUDE.md e regras por caminho. A camada de ferramentas cobre schemas de MCP e ferramentas internas. A camada de histórico cobre conversa, resultados de shell e diffs. A camada de fan-out cobre subagentes.
Essa separação evita cortes ruins. Remover comandos de teste do arquivo de instrução pode economizar contexto, mas piorar validação. Remover arquitetura duplicada que o agente pode descobrir com rg costuma ser mais seguro. Para a base conceitual, veja também context engineering para agentes de código.
Experiência prática: quando uma sessão fica cara, eu salvo a lista de arquivos de instrução carregados, ferramentas disponíveis e subagentes chamados. Sem esse inventário, a discussão vira opinião sobre modelo, não engenharia de sistema.
Como deixar AGENTS.md e CLAUDE.md menores sem quebrar o agente?
Em 2026, o estudo "Evaluating AGENTS.md" concluiu que arquivos de contexto aumentaram o custo médio de inferência em mais de 20% e não melhoraram, de forma geral, a taxa de sucesso nas tarefas avaliadas (arXiv, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", 2026). Portanto, instrução persistente precisa provar valor.
AGENTS.md e CLAUDE.md não devem ser README duplicado. Eles devem conter o que o agente precisa saber em toda tarefa: comandos de teste, limites de segurança, convenções incomuns, definição de pronto e armadilhas reais do repositório. O resto pode ficar em documentação buscável.
A documentação do Claude Code diz que CLAUDE.md é carregado no contexto da sessão e recomenda mirar menos de 200 linhas por arquivo (Claude Code Docs, "How Claude remembers your project", 2026). A documentação do Codex diz que AGENTS.md é lido antes do trabalho e que o limite padrão combinado de instruções do projeto é 32 KiB (OpenAI, "Custom instructions with AGENTS.md", 2026).
O corte bom é cirúrgico. Troque árvore de diretórios por padrões de busca. Troque política longa por regra verificável. Troque processo raro por skill chamada sob demanda. Se o post sobre AGENTS.md enxuto para agentes é a camada editorial, este artigo é a camada de medição.
Cápsula citável: Arquivo de instrução bom reduz ambiguidade sem virar documentação inteira no contexto. O arXiv mediu custo médio acima de 20% com AGENTS.md, enquanto Claude Code recomenda menos de 200 linhas e Codex define 32 KiB como limite padrão combinado.
Quando MCP e subagentes entram no orçamento?
Em 2026, a Systima mediu que servidores MCP pequenos adicionaram cerca de 1 mil a 1,4 mil tokens por servidor e por requisição, enquanto um fan-out modesto com subagentes multiplicou o total medido por 4,2 vezes (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). Ferramenta e delegação precisam de limite explícito.
MCP vale quando evita colar contexto vivo no prompt. Ele não vale quando todo servidor fica ligado por padrão. A própria documentação de boas práticas do Codex recomenda adicionar ferramentas apenas quando elas destravam um fluxo real, começando por poucas integrações claras (OpenAI, "Best practices", 2026).
Subagentes seguem a mesma lógica. Eles são ótimos para pesquisa paralela, migração por domínio e revisão independente. Mas cada subagente pode carregar seu próprio bootstrap, ferramentas e histórico. Quando o trabalho é pequeno, chamar subagente pode custar mais que resolver direto.
Quando uso loops longos em Claude Code ou Codex, eu coloco o RemoteCode como camada para fazer agentes irem mais longe com menos desperdício de contexto. É uma ferramenta minha, então a recomendação é editorial: ela ajuda no gargalo de contexto e coordenação, não substitui orçamento, sandbox ou revisão.
Cápsula citável: MCP e subagentes são multiplicadores de contexto. A Systima mediu cerca de 1 mil a 1,4 mil tokens por servidor MCP pequeno e 4,2 vezes mais tokens em fan-out modesto; use essas camadas quando elas removem trabalho real.
Como transformar orçamento de contexto em gate de CI?
Em 2026, a Systima mediu uma configuração real com 75 mil tokens aproximados no Claude Code e 90.817 tokens no OpenCode antes do trabalho útil, combinando MCP, plugins e arquivo de instrução grande (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). O CI deve tornar esse custo visível.
Um gate simples não precisa saber preço. Ele precisa registrar variação. Capture quais arquivos de instrução foram carregados, quantas ferramentas ficaram disponíveis, quais servidores MCP entraram, quais subagentes rodaram e qual foi o payload antes da primeira ação de código.
O gate deve falhar quando a configuração muda sem revisão. Um novo MCP, uma importação grande em CLAUDE.md, uma skill que injeta checklist longo ou um subagente criado para tarefa pequena deve aparecer no PR. Isso combina com evals de PR para agentes no CI e loops self-correcting no CI.
Cápsula citável: Gate de orçamento de contexto não precisa calcular preço por token. Ele precisa detectar drift: instruções maiores, MCP novo, mais ferramentas, subagentes extras e payload inicial maior. A configuração medida pela Systima mostra que o custo real nasce da pilha inteira.
Um harness simples para auditar tokens por tarefa
Em 2026, "Configuration Smells in AGENTS.md Files" analisou 100 repositórios populares e encontrou Lint Leakage em 62% dos arquivos, Context Bloat em 42% e Skill Leakage em 35% (arXiv, "Configuration Smells in AGENTS.md Files", 2026). Esses smells viram critérios úteis para um harness de auditoria.
O harness deve rodar antes do agente principal. Ele lista instruções, procura duplicação, mede tamanho, registra ferramentas e exige justificativa para fan-out. Depois grava o resumo como artefato de CI. Não precisa expor segredo nem capturar conteúdo sensível; o objetivo é rastrear estrutura, não vazar prompt.
Um contrato operacional pode ser assim:
contexto:
medir_baseline: true
registrar_arquivos_de_instrucao: true
registrar_ferramentas: true
registrar_mcp: true
registrar_subagentes: true
politica:
bloquear_instrucao_sem_revisao: true
bloquear_mcp_nao_revisado: true
exigir_motivo_para_fan_out: true
saida:
artefato_ci: ".ci/context-budget/report.json"
resumo_pr: ".ci/context-budget/summary.md"O próximo passo é ligar esse harness ao processo de revisão. Se o PR altera AGENTS.md, CLAUDE.md, .claude/rules, .mcp.json ou skills de agente, o orçamento precisa aparecer como parte da evidência. Sem isso, o time só descobre o custo quando a sessão já ficou lenta, cara ou instável.
Cápsula citável: Harness de contexto para agentes mede estrutura antes de medir preço. Como um estudo de 2026 encontrou Context Bloat em 42% dos arquivos AGENTS.md ou CLAUDE.md analisados, o CI deve tratar instrução persistente como superfície de performance e revisão.
Checklist de corte seguro
Em 2026, "Probe-and-Refine Tuning of Repository Guidance" obteve 33,0% de resolução média no SWE-bench Verified contra 28,3% da base estática inicial e 25,5% sem orientação (arXiv, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents", 2026). O recado é equilibrado: contexto ruim atrapalha, mas orientação refinada ajuda.
Use este checklist quando o agente estiver caro, lento ou disperso:
- Remova visão geral que o agente pode descobrir com busca.
- Mantenha comandos de build, teste e lint que são realmente usados.
- Mova processos raros para skills ou runbooks sob demanda.
- Prefira regras por caminho para áreas especializadas.
- Revise imports em
CLAUDE.md; eles expandem contexto. - Ligue MCP apenas quando a tarefa exige dado externo vivo.
- Peça justificativa antes de fan-out de subagentes.
- Registre drift de contexto no PR.
O objetivo não é deixar o agente cego. É dar contexto suficiente para ele acertar o arquivo, rodar a prova certa e parar de carregar material irrelevante. Em agentes de código, economia de token também é engenharia de confiabilidade.
Perguntas frequentes sobre orçamento de contexto
Orçamento de contexto é só cortar tokens?
Não. Em 2026, a Anthropic descreveu context engineering como curadoria do menor conjunto de tokens de alto sinal para maximizar o resultado desejado (Anthropic, "Effective context engineering for AI agents", 2026). O orçamento mede custo, mas a decisão é sobre relevância, verificabilidade e controle.
AGENTS.md sempre piora o agente?
Não. Em 2026, "Probe-and-Refine" mostrou 33,0% de resolução média contra 25,5% sem orientação em seu experimento (arXiv, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents", 2026). O problema é contexto genérico, inchado ou não testado, não a existência do arquivo.
MCP deve ficar desligado por padrão?
Na maioria dos repositórios, sim. Em 2026, a Systima mediu cerca de 1 mil a 1,4 mil tokens por servidor MCP pequeno por requisição (Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", 2026). Ligue MCP quando ele substitui uma tarefa manual real, não como decoração.
Subagentes são desperdício de contexto?
Não necessariamente. Em 2026, a Anthropic descreveu subagentes como forma de isolar buscas extensas e devolver resumos menores ao agente principal (Anthropic, "Effective context engineering for AI agents", 2026). Use fan-out quando paralelismo reduz risco ou tempo, e registre o custo no harness.
Fontes
- Systima, "Claude Code Sends 4.7x More Tokens Than OpenCode Before Reading Your Prompt", consultado em 2026-07-14, https://systima.ai/blog/claude-code-vs-opencode-token-overhead
- Claude Code Docs, "How Claude remembers your project", consultado em 2026-07-14, https://code.claude.com/docs/en/memory
- Anthropic, "Effective context engineering for AI agents", consultado em 2026-07-14, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
- OpenAI, "Custom instructions with AGENTS.md", consultado em 2026-07-14, https://developers.openai.com/codex/guides/agents-md
- OpenAI, "Best practices", consultado em 2026-07-14, https://developers.openai.com/codex/learn/best-practices
- arXiv, "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", consultado em 2026-07-14, https://arxiv.org/abs/2602.11988
- arXiv, "Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents", consultado em 2026-07-14, https://arxiv.org/abs/2606.15828
- arXiv, "Probe-and-Refine Tuning of Repository Guidance for Coding Agents", consultado em 2026-07-14, https://arxiv.org/abs/2606.20512
