recuperação-iterativa

Padrão de Recuperação Iterativa

Resolve o "problema de contexto" em fluxos de trabalho com múltiplos agentes, onde subagentes não sabem qual contexto precisam até começarem a trabalhar.

Quando Ativar

• Ao gerar subagentes que precisam de contexto do código que não podem prever antecipadamente
• Construindo fluxos de trabalho com múltiplos agentes onde o contexto é progressivamente refinado
• Encontrando falhas de "contexto muito grande" ou "contexto ausente" em tarefas de agente
• Projetando pipelines de recuperação do tipo RAG para exploração de código
• Otimizando o uso de tokens na orquestração de agentes

O Problema

Subagentes são gerados com contexto limitado. Eles não sabem:

• Quais arquivos contêm código relevante
• Quais padrões existem no código
• Qual terminologia o projeto usa

Abordagens padrão falham:

• Enviar tudo: Excede os limites de contexto
• Não enviar nada: O agente carece de informações críticas
• Adivinhar o que é necessário: Frequentemente errado

A Solução: Recuperação Iterativa

Um loop de 4 fases que refina progressivamente o contexto:

┌─────────────────────────────────────────────┐
│                                             │
│   ┌──────────┐      ┌──────────┐            │
│   │ DISPATCH │─────│ EVALUATE │            │
│   └──────────┘      └──────────┘            │
│        ▲                  │                 │
│        │                  ▼                 │
│   ┌──────────┐      ┌──────────┐            │
│   │   LOOP   │─────│  REFINE  │            │
│   └──────────┘      └──────────┘            │
│                                             │
│        Máx. 3 ciclos, depois prosseguir     │
└─────────────────────────────────────────────┘

Fase 1: DISPATCH

Consulta inicial ampla para reunir arquivos candidatos:

// Começar com intenção de alto nível
const initialQuery = {
  patterns: ['src/**/*.ts', 'lib/**/*.ts'],
  keywords: ['authentication', 'user', 'session'],
  excludes: ['*.test.ts', '*.spec.ts']
};

// Despachar para agente de recuperação
const candidates = await retrieveFiles(initialQuery);

Fase 2: EVALUATE

Avaliar o conteúdo recuperado quanto à relevância:

function evaluateRelevance(files, task) {
  return files.map(file => ({
    path: file.path,
    relevance: scoreRelevance(file.content, task),
    reason: explainRelevance(file.content, task),
    missingContext: identifyGaps(file.content, task)
  }));
}

Critérios de pontuação:

• Alta (0.8-1.0): Implementa diretamente a funcionalidade alvo
• Média (0.5-0.7): Contém padrões ou tipos relacionados
• Baixa (0.2-0.4): Tangencialmente relacionado
• Nenhuma (0-0.2): Não relevante, excluir

Fase 3: REFINE

Atualizar os critérios de busca com base na avaliação:

function refineQuery(evaluation, previousQuery) {
  return {
    // Adicionar novos padrões descobertos em arquivos de alta relevância
    patterns: [...previousQuery.patterns, ...extractPatterns(evaluation)],

    // Adicionar terminologia encontrada no código
    keywords: [...previousQuery.keywords, ...extractKeywords(evaluation)],

    // Excluir caminhos irrelevantes confirmados
    excludes: [...previousQuery.excludes, ...evaluation
      .filter(e => e.relevance < 0.2)
      .map(e => e.path)
    ],

    // Focar em lacunas específicas
    focusAreas: evaluation
      .flatMap(e => e.missingContext)
      .filter(unique)
  };
}

Fase 4: LOOP

Repetir com critérios refinados (máximo de 3 ciclos):

async function iterativeRetrieve(task, maxCycles = 3) {
  let query = createInitialQuery(task);
  let bestContext = [];

  for (let cycle = 0; cycle < maxCycles; cycle++) {
    const candidates = await retrieveFiles(query);
    const evaluation = evaluateRelevance(candidates, task);

    // Verificar se temos contexto suficiente
    const highRelevance = evaluation.filter(e => e.relevance >= 0.7);
    if (highRelevance.length >= 3 && !hasCriticalGaps(evaluation)) {
      return highRelevance;
    }

    // Refinar e continuar
    query = refineQuery(evaluation, query);
    bestContext = mergeContext(bestContext, highRelevance);
  }

  return bestContext;
}

Exemplos Práticos

Exemplo 1: Contexto para Correção de Bug

Tarefa: "Corrigir o bug de expiração do token de autenticação"

Ciclo 1:
  DISPATCH: Procurar por "token", "auth", "expiry" em src/**
  EVALUATE: Encontrado auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)
  REFINE: Adicionar keywords "refresh", "jwt"; excluir user.ts

Ciclo 2:
  DISPATCH: Procurar termos refinados
  EVALUATE: Encontrado session-manager.ts (0.95), jwt-utils.ts (0.85)
  REFINE: Contexto suficiente (2 arquivos de alta relevância)

Resultado: auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts

Exemplo 2: Implementação de Funcionalidade

Tarefa: "Adicionar limitação de taxa aos endpoints da API"

Ciclo 1:
  DISPATCH: Procurar "rate", "limit", "api" em routes/**
  EVALUATE: Sem correspondências - o código usa terminologia "throttle"
  REFINE: Adicionar keywords "throttle", "middleware"

Ciclo 2:
  DISPATCH: Procurar termos refinados
  EVALUATE: Encontrado throttle.ts (0.9), middleware/index.ts (0.7)
  REFINE: Necessário padrões de roteador

Ciclo 3:
  DISPATCH: Procurar padrões "router", "express"
  EVALUATE: Encontrado router-setup.ts (0.8)
  REFINE: Contexto suficiente

Resultado: throttle.ts, middleware/index.ts, router-setup.ts

Integração com Agentes

Use em prompts de agente:

Ao recuperar contexto para esta tarefa:
1. Comece com uma busca ampla por palavras-chave
2. Avalie a relevância de cada arquivo (escala 0-1)
3. Identifique qual contexto ainda está faltando
4. Refine os critérios de busca e repita (máx. 3 ciclos)
5. Retorne arquivos com relevância >= 0.7

Melhores Práticas

1. Comece amplo, estreite progressivamente - Não especifique demais as consultas iniciais
2. Aprenda a terminologia do código - O primeiro ciclo geralmente revela convenções de nomenclatura
3. Acompanhe o que está faltando - A identificação explícita de lacunas impulsiona o refinamento
4. Pare quando estiver "bom o suficiente" - 3 arquivos de alta relevância vencem 10 medíocres
5. Exclua com confiança - Arquivos de baixa relevância não se tornarão relevantes

Relacionados

• O Guia Detalhado - Seção de orquestração de subagentes
• Habilidade continuous-learning - Para padrões que melhoram com o tempo
• Definições de agente incluídas com ECC (caminho de instalação manual: agents/)