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 de que contexto precisam até começarem a trabalhar.

Quando Ativar

• Ao gerar subagentes que precisam de contexto do código que não conseguem prever antecipadamente
• Ao construir fluxos de trabalho com múltiplos agentes onde o contexto é refinado progressivamente
• Ao encontrar falhas de "contexto muito grande" ou "contexto ausente" em tarefas de agentes
• Ao projetar pipelines de recuperação tipo RAG para exploração de código
• Ao otimizar 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 base
• Qual terminologia o projeto usa

Abordagens padrão falham:

• Enviar tudo: Excede os limites de contexto
• Enviar nada: O agente carece de informações críticas
• Adivinhar o necessário: Muitas vezes 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 prossiga       │
└─────────────────────────────────────────────┘

Fase 1: DISPATCH

Consulta inicial ampla para reunir arquivos candidatos:

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

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

Fase 2: EVALUATE

Avalie 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): Relacionada tangencialmente
• Nenhuma (0-0.2): Não relevante, excluir

Fase 3: REFINE

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

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

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

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

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

Fase 4: LOOP

Repita com critérios refinados (máx. 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);

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

    // Refine e continue
    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: Buscar por "token", "auth", "expiry" em src/**
  EVALUATE: Encontrado auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)
  REFINE: Adicionar "refresh", "jwt" como palavras-chave; excluir user.ts

Ciclo 2:
  DISPATCH: Buscar com 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: Buscar por "rate", "limit", "api" em routes/**
  EVALUATE: Nenhuma correspondência - o código base usa terminologia "throttle"
  REFINE: Adicionar "throttle", "middleware" como palavras-chave

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

Ciclo 3:
  DISPATCH: Buscar por 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 nos prompts de agentes:

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, refine progressivamente - Não especifique demais as consultas iniciais
2. Aprenda a terminologia do código base - O primeiro ciclo frequentemente revela convenções de nomenclatura
3. Acompanhe o que está faltando - A identificação explícita de lacunas impulsiona o refinamento
4. Pare no "bom o suficiente" - 3 arquivos de alta relevância são melhores que 10 medíocres
5. Exclua com confiança - Arquivos de baixa relevância não se tornarão relevantes

Relacionados

• The Longform Guide - Seção de orquestração de subagentes
• Habilidade continuous-learning - Para padrões que melhoram ao longo do tempo
• Definições de agente incluídas com ECC (caminho de instalação manual: agents/)