Otimização de Tokens em Agentes de Código: Além do CLAUDE.md

Introdução

A obsessão pela quantidade de contexto é um problema recorrente na adoção de agentes de IA para desenvolvimento. Desenvolvedores frequentemente sentem a necessidade de empurrar toda a informação possível para os modelos, acreditando que mais dados resultarão em melhores respostas. Essa intuição é intuitivamente atraente, mas empiricamente falsa. O que os pesquisadores e profissionais de produção descobriram é que qualidade de contexto supera quantidade de contexto de forma significativa.

A realidade é mais nuançada: LLMs funcionam como funções sem estado (stateless) com janelas de contexto finitas. Cada token é precioso, e o modo como você estrutura e entrega a informação determina se o agente mantém foco na tarefa ou se "se perde" em contexto irrelevante. Este artigo vai além de simples configurações de .cursorrules e CLAUDE.md, explorando estratégias de engenharia de contexto que profissionais usam diariamente com Cursor, Windsurf, Zed e Claude Code.

1. O Problema Real: Degradação de Atenção, Não Falta de Dados

A Realidade Empírica

Pesquisas recentes em geração de código com LLMs revelam um padrão contraintuitivo: quanto mais tokens você fornece, pior o modelo se comporta — até um certo limite onde a qualidade estabiliza ou degrada ainda mais.

Um caso estudo da Refine AI ilustra isso claramente. Ao tentar melhorar a geração de dashboards e componentes de análise de dados:

• Iteração 1: Incluir toda a documentação da biblioteca, guias de estilo e exemplos. Resultado: 10% de taxa de sucesso, ~100k tokens de entrada.
• Iteração 2: Tentar estruturar isso em um prompt de três estágios. Resultado: 20% de taxa de sucesso, mas com crescimento paradoxal de tokens para ~500k.
• Iteração 3: Arquitetura isolada multi-agente. Resultado: 80% de taxa de sucesso, com redução de 90% no consumo de tokens comparado à iteração anterior.

O insight crítico: o modelo não estava falhando por falta de informação. Ele estava falhando porque a atenção do modelo estava diluída entre contexto relevante e ruído.

Por Que Isso Acontece?

LLMs alocam "poder atencional" de forma não-uniforme. Quando você fornece 500k tokens de contexto, o modelo:

1. Não consegue processar efetivamente todo o contexto — a atenção se degrada uniformemente conforme a quantidade de tokens aumenta.
2. Prioriza periféricos — o modelo tende a prestar mais atenção ao início (system prompt, CLAUDE.md) e final (sua pergunta atual) do que ao meio.
3. Sofre com "path-of-least-resistance" — prefere gerar respostas genéricas usando padrões comuns em vez de explorar o contexto fornecido.

2. Arquitetura Multi-Agente: Dividir para Conquistar

O Paradoxo da Janela de Contexto

Esperar por janelas de contexto maiores é uma estratégia equivocada. Mesmo com 200k tokens (Claude 3.5 Opus), 128k-200k (Cursor Max Mode), ou 2M (modelos experimentais), o problema persiste: informação não é problema, foco é.

A solução estabelecida pela comunidade de produção é separação de responsabilidades através de múltiplos agentes especializados.

Padrão: Research-Plan-Implement-Review

Ao invés de um único agente fazer tudo (problema que CLAUDE.md tenta resolver), distribua a tarefa:

┌──────────────────────┐
│ Research Agent       │ (Identifica padrões e referências relevantes)
└──────────┬───────────┘
           │
           ↓
┌──────────────────────┐
│ Planning Agent       │ (Estrutura abordagem e roadmap)
└──────────┬───────────┘
           │
           ↓
┌──────────────────────┐
│ Implementation Agent  │ (Executa com contexto focado)
└──────────┬───────────┘
           │
           ↓
┌──────────────────────┐
│ Review Agent        │ (Valida e refina iterativamente)
└──────────────────────┘

Por que funciona:

• Cada agente herda apenas o contexto relevante para sua fase
• O Research Agent não carrega todo o histórico da conversa anterior
• O Implementation Agent recebe uma especificação clara, não um braindump
• O resultado total é melhor (80% vs 10%), mas com 90% menos tokens

Implementação em Cursor 2.0 / Windsurf / Claude Code

Cursor 2.0 (lançado outubro 2025) oferece até 8 agentes paralelos via git worktrees ou máquinas remotas. Cada agente trabalha isoladamente sem conflitos:

# Cursor 2.0 cria automaticamente worktrees isoladas
cursor-agent-1: feature-backend (Composer model)
cursor-agent-2: feature-frontend (Composer model)
cursor-agent-3: tests-e2e (GPT-4 Codex)
# Você compara resultados e escolhe o melhor

Windsurf implementa Cascade 2.0 (em desenvolvimento) com padrão "um agente escreve, outro revisa e marca". Cada um tem contexto separado e pode executar até 20 chamadas de ferramenta (tool calls) em sequência sem intervenção manual.

Claude Code oferece Sub-agents (native desde agosto 2025) — especializações com seus próprios system prompts, permissões de ferramentas, e janela de contexto isolada. Exemplo estrutura:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Analisa código para padrões, segurança e performance
tools:
  - grep
  - file-read
model: haiku  # Use modelo mais rápido/barato para tarefas focadas
---

Você é um revisor de código sênior especializado em...

3. Compressão Contextual Intencional

O Problema com Auto-Compactação

Claude Code resume automaticamente a 95% da janela. Cursor trunca internamente para "manter performance". Nenhuma ferramenta oferece controle explícito sobre o que é preservado e por quê.

Estratégia: Notas Estruturadas com Decisões Explícitas

Em vez de deixar o agente resumir automaticamente, você define o que é importante antes:

# Status do Projeto - Sprint 24

## Decisões Arquiteturais (✗ mude só com justificativa explícita)
- **Usar FastAPI + SQLAlchemy** — motivo: suporte a async nativo, comunidade ativa
- **Banco de dados: PostgreSQL 14+** — motivo: JSONB, full-text search, constraints avançados
- **Autenticação: JWT com refresh tokens** — motivo: stateless, ideal para escala horizontal

## Bugs Resolvidos
- ✓ N+1 queries em endpoint /users (eager loading adicionado)
- ✓ Memory leak em WebSocket cleanup (implementar context manager)

## Bugs em Andamento
- 🔴 CRÍTICO: Timeout em relatórios com >100k linhas (otimizar query, adicionar paginação)
- 🟡 MÉDIO: Validação insuficiente em upload de arquivos (adicionar sanitização)

## Contexto Técnico Recente
- Alterado schema de `profiles` para incluir `last_sync_at` (migration #47)
- Implementado paginação no endpoint GET /reports (20-100 itens/página)

Essa abordagem é superior a um resumo automático porque:

1. Preserva intenção — o agente sabe por que cada decisão foi tomada
2. Facilita busca — é fácil procurar "por que usamos FastAPI?" sem reler 500 mensagens
3. Reduz re-explicação — novos agentes entendem o contexto sem ambiguidade
4. Suporta versionamento — commit isso no git, rastreie evolução de decisões

Implementação Prática em Seus Projetos

Crie um arquivo .agent-state/progress.md no seu repositório:

# .agent-state/progress.md

## Última Sessão de Agent
- **Agente Anterior**: ImplementationAgent (FastAPI endpoints)
- **Tempo Gasto**: 2.5 horas
- **Completado**: 3 endpoints GET/POST/PATCH implementados + testes unitários
- **Status**: 🟢 Pronto para revisão

## Próximos Passos
1. ReviewAgent: Validar tipo de dados, casos extremos, segurança
2. TestAgent: Adicionar testes de integração (banco de dados)
3. DocsAgent: Atualizar Swagger/OpenAPI spec

## Problemas Conhecidos para Próxima Sessão
- Cache em memória causando inconsistência com dados do banco (pendente debugging)
- Endpoint POST /items ainda não paginado

Instrua seu agente: "Leia .agent-state/progress.md antes de começar qualquer tarefa nova e atualize-o antes de terminar."

4. Busca Inteligente e Recuperação Contextual (RAG Aprimorado)

O Anti-Padrão: "Anexar Tudo"

Muitos desenvolvedores anexam 50 arquivos esperando que o agente "encontre" o relevante. Resultado: tokens desperdiçados, atenção diluída, latência aumentada.

Solução: Recuperação Iterativa sob Demanda

Windsurf usa indexação semântica em Abstract Syntax Tree (AST) — não arquivo inteiro, mas blocos semânticos (função, classe, etc). Resultado: 3x melhor acurácia de recuperação comparado a métodos simples como grep naive.

Cursor 2.0 com Composer model usa busca em três camadas:

1. Embeddings semânticos — "qual arquivo provavelmente contém validação de emails?"
2. Grep para correspondências exatas — buscar por email_validator
3. AST parsing — entender estrutura e dependências

Como Implementar Com Seus Agentes

Instrua o agente para explorar de forma proativa:

"Explore o repositório de forma proativa:
1. Liste estrutura com depth=2 (tree -L 2)
2. Identifique arquivos críticos por tamanho/frequência
3. Procure por padrões específicos: /^\s*class\s+\w+.*Exception/
4. Leia apenas o que é necessário para a tarefa
5. Se em dúvida sobre padrões, busque exemplos (grep -r 'padrão' --include='*.py')"

Isso mantém a janela de contexto limpa e focada. O agente não carrega 50 arquivos — carrega 3-4 diretamente relevantes.

5. Sub-Agents vs. Slash Commands vs. Skills

A confusão entre "o que usar quando" é comum. Aqui está a matriz de decisão (baseada em Claude Code stack):

Paradigma "Divide & Conquer": Use sub-agents para paralelização real, slash commands para workflows manuais frequentes, skills para detecção automática de contexto.

6. Gerenciamento de Estado com MCPs (Model Context Protocol)

O Problema com Contexto Efêmero

Cada nova sessão/conversa é um reset. Você perde:

• Decisões arquiteturais prévias
• Padrões que funcionaram
• Bugs conhecidos
• Contexto acumulado do projeto

Solução: MCPs como Memória Persistente

MCPs (protocolo padronizado para integração de ferramentas) permitem ao agente acessar dados estruturados sem carregar no contexto:

{
  "name": "project-state-mcp",
  "description": "Acesso a estado persistente do projeto",
  "tools": [
    {
      "name": "get_architecture_decisions",
      "description": "Retorna decisões arquiteturais com justificativas"
    },
    {
      "name": "get_known_issues",
      "description": "Bugs conhecidos e resoluções anteriores"
    },
    {
      "name": "get_approved_patterns",
      "description": "Padrões de código aprovados no projeto"
    }
  ]
}

Exemplos de MCPs em Produção (Dezembro 2025):

• Serena MCP — toolkit completo para agentes de código (busca semântica, edição inteligente). Integra com Claude Code e funciona com sub-agents
• Google Cloud Security MCP — conecta SOC personas com runbooks de segurança
• Shortcut MCP — integra gerenciamento de projetos com contexto de agentes

Benefício: O agente não precisa reler tudo novamente — acessa via chamada de ferramenta, economizando 60-80% de tokens.

7. Novidade: Agentes Paralelos em Cursor 2.0

O Que Mudou (Outubro 2025)

Cursor 2.0 introduziu até 8 agentes simultâneos usando git worktrees ou máquinas remotas:

Agente 1 (Composer model, worktree-1): Backend refactoring
Agente 2 (Composer model, worktree-2): Frontend components
Agente 3 (GPT-4 Codex, worktree-3): Testes E2E

Cada worktree é um clone isolado da mesma repo — mudanças não conflitam. Você compara os 3 resultados e escolhe o melhor.

Implicação prática:

• Tarefas complexas resolvidas 2-3x mais rápido
• Comparação de resultados para hard problems (múltiplos modelos tentando a mesma coisa)
• Git worktrees gerenciadas automaticamente pelo Cursor

8. Windsurf Cascade: Indexação Semântica

Como Funciona (Dezembro 2025)

Windsurf pré-escaneia seu repositório inteiro e cria um índice semântico em AST:

Seu código:
├── auth/
│   ├── login.py     → [função login, classe AuthService, imports]
│   ├── jwt.py       → [função encode_token, função decode_token]
├── models/
│   ├── user.py      → [classe User, validadores]
│   ├── schema.py    → [Pydantic BaseModel subclasses]

Índice semântico de Windsurf:
- Entity: "login" (function) → arquivo: auth/login.py:15
- Entity: "AuthService" (class) → arquivo: auth/login.py:42
- Dependency: AuthService → jwt.encode_token
- Dependency: User model → schema.py

Quando você pede "refatore a autenticação para usar JWT", Cascade entende a estrutura sem ler arquivo inteiro.

Vantagem sobre grep: Contexto estrutural, não apenas strings.

9. Compressão Intencional vs. Auto-Compactação

Padrões de Falha em Compressão Automática

Pesquisa de Stanford (2024) identifica 3 padrões onde compressão automática falha:

1. "Lost by the boundary" — informação crítica no limite entre chunks é perdida
2. "Lost if surprise" — informações inesperadas/outliers são descartadas
3. "Lost along the way" — dados no meio do contexto sofrem degradação

Estratégia: Compressão Controlada com Ranks Explícitos

# Compressão Manual - Sessão #47

## Preservar (Crítico - nunca descartar)
- Decisão: Usar Row-Level Security no PostgreSQL
- Motivo: Requisito de segurança para dados multi-tenant
- Arquivo de referência: `docs/security-design.md`
- Prioridade: 🔴 CRÍTICO

## Preservar (Importante - se houver espaço)
- Padrão de retentativa exponencial com jitter
- Motivo: Prevenir thundering herd em rate limiting

## Descartar (Já resolvido, sem relevância futura)
- Discussões sobre escolha de ORM (resolvida com SQLAlchemy, sem alternativas)
- Debugging de sintaxe Python (problema isolado)

## Nova Janela de Contexto
- Começar nova sessão com CLAUDE.md + progress.md + arquivo de decisões
- Sub-agent de "implementation" receberá apenas o spec focado

10. Seleção de Modelo: O Token Mais Barato é o Que Você Não Usa

Matriz de Seleção (Dezembro 2025)

Anti-Padrão

❌ Usar Opus para TUDO porque "é o melhor"
❌ Usar Haiku para refactoring complexo
❌ Ativar "thinking mode" por padrão

Cursor 2.0 permite seleção automática por tarefa — configure "Auto" para tarefas simples, Sonnet para moderadas, Opus raramente.

11. O Papel do Thinking Mode

Modelos com raciocínio explícito ("thinking") podem resolver problemas complexos, mas consomem tokens exponencialmente.

Quando Usar Thinking

✅ Decisões arquiteturais críticas (e.g., migração de banco de dados) ✅ Otimizações de performance complexas (e.g., algoritmo de sorting distribuído) ✅ Análise de segurança profunda (e.g., auditoria de cryptografia)

Quando Evitar

❌ Refactoring simples ❌ Correção de typos ❌ Geração de boilerplate

Regra de Ouro: Thinking mode = 3-5x mais tokens. Use apenas quando qualidade justificar.

12. Terminologia e Linguagem Técnica em Português

Para evitar confusões de tradução direta:

13. Monitoramento e Otimização Contínua

Métricas que Importam

1. Taxa de Sucesso — % de tarefas completas na primeira tentativa
2. Tokens por Sucesso — quanto custa cada tarefa bem-feita
3. Tempo de Resposta — latência total (não linear com tokens)
4. Utilização Contextual — % da janela realmente usado

Ferramentas de Observabilidade (Dezembro 2025)

• Cursor: Veja tokens/stats em cada operação via UI
• Windsurf: Logs detalhados de retrieval + tokens em ~/.windsurf/logs
• Claude Code: Análise retrospectiva de traces via Claude Dashboard
• Qodo: Métricas por agent executado

Pipeline de Otimização Realista

Semana 1: Medir baseline
  Métrica: 150k tokens/tarefa, 60% sucesso

Semana 2: Implementar RAG inteligente
  Métrica: 80k tokens, 75% sucesso

Semana 3: Adicionar MCPs
  Métrica: 50k tokens, 85% sucesso

Semana 4: Multi-agent (research-plan-implement)
  Métrica: 40k tokens, 90% sucesso

Semana 5+: Refinamentos incrementais
  Métrica: 30k tokens, 92% sucesso

14. Anti-Padrões Comuns

❌ Enviando Tudo de Uma Vez

# RUIM
agent.run("""
    TODO: Refatore o módulo de autenticação.
    
    Aqui está TODA a base de código:
    [500 arquivos anexados]
    
    Aqui está a documentação:
    [50 PDFs]
""")

✅ Recuperação Iterativa

# BOM
agent.run("""
    TODO: Refatore o módulo de autenticação.
    
    Explore:
    1. Procure por classes com 'Auth' no nome
    2. Identifique a função entry point
    3. Mapeie dependências
    4. Depois, revise estrutura
""")

❌ Um Agente Fazendo Tudo

# RUIM - contexto poluído
agent = create_agent(
    instructions="""
        Você é um desenvolvedor full-stack que:
        - Escreve backend em FastAPI
        - Escreve frontend em React
        - Faz deploy em Docker
        - Escreve testes
        - Documenta tudo
        - Otimiza performance
    """
)

✅ Agentes Especializados

# BOM - contexto focado
research_agent = SubAgent(instructions="Analise a codebase e proponha arquitetura")
backend_agent = SubAgent(instructions="Implemente endpoints FastAPI")
test_agent = SubAgent(instructions="Escreva testes pytest")
review_agent = SubAgent(instructions="Revise código para padrões e segurança")

# Orquestre manualmente ou deixe Claude Code coordenar

Conclusão: Tokens Como Recurso Finito

A otimização de tokens é fundamentalmente sobre tratar tokens como um recurso finito e valioso, semelhante a memória RAM ou CPU em sistemas tradicionais.

Os princípios aplicados por profissionais de produção em Dezembro de 2025:

1. Qualidade > Quantidade — contexto focado supera contexto abundante
2. Arquitetura Multi-Agente — divida problemas complexos em tarefas especializadas
3. Compressão Intencional — controle o que é memorizado, não confie em resumos automáticos
4. Busca Iterativa — carregue contexto sob demanda, não tudo de uma vez
5. Seleção Apropriada de Modelo — use o modelo certo para cada tarefa
6. Indexação Semântica — aproveite AST e embeddings, não grep naive
7. MCPs para Memória — acesse estado persistente via ferramentas, não contexto
8. Observabilidade — meça e otimize continuamente
9. Sub-agents para Isolamento — cada agente especializado, contexto próprio
10. Agentes Paralelos — Cursor 2.0 permite 8 agentes simultâneos via git worktrees

Aplicar essas técnicas não é apenas economizar tokens — é construir agentes de IA que raciocinam melhor, entregam código de qualidade superior, e custam menos no processo.

Referências Técnicas

• Anthropic Engineering: "Effective context engineering for AI agents" (2025)
• Refine AI Case Study: "Quality Code Generation: Multi-Agent Systems and Token Dilution" (90% token reduction com multi-agent)
• Cursor 2.0 Release: "Introducing Cursor 2.0 and Composer" (October 2025) — git worktrees, 8 parallel agents
• Windsurf: AST-based semantic indexing, Cascade 2.0 roadmap (code review + benchmarking)
• Claude Code Documentation: Sub-agents, MCP protocol extensions, context isolation patterns
• Serena MCP: Semantic code understanding toolkit para code agents (GitHub: oraios/serena)
• HumanLayer Blog: "Writing a good CLAUDE.md" (instruction-following research)
• Research Papers:
  • "Self-Organized Agents" (SoA framework)
  • "Chain of Agents" (CoA framework)
  • "Gist Token-based Context Compression" (Stanford, padrões de falha)
  • "LLMLingua: Compressing Prompts for Accelerated Inference"