iterative-retrieval

Visão geral do skill iterative-retrieval

O skill iterative-retrieval é um padrão de workflow para resolver o “problema de contexto” em trabalhos agentic: um subagente começa com informação demais e, por isso, não sabe exatamente o que precisa; depois, vai afunilando progressivamente até encontrar os arquivos, termos e padrões certos. Ele é mais indicado para quem desenha workflows, explora codebases e constrói iterative-retrieval for Workflow Automation, especialmente quando a primeira busca costuma vir incompleta.

O que normalmente importa para quem usa não é a teoria, e sim saber se o skill ajuda o agente a evitar dois erros comuns: mandar contexto demais e estourar o orçamento, ou mandar contexto de menos e travar. O principal valor do iterative-retrieval é transformar a descoberta em um loop, em vez de um chute único.

O que o iterative-retrieval resolve

Use este skill quando a tarefa depender de contexto específico do codebase que não dá para saber de antemão: localizar padrões de implementação, identificar arquivos relevantes ou refinar termos de busca depois do primeiro reconhecimento. Ele é especialmente útil quando o agente precisa raciocinar sobre um repo grande sem orientação humana direta.

Por que este skill é diferente

Ao contrário de um prompt genérico que diz “procure por aí e depois decida”, o iterative-retrieval oferece um loop de recuperação concreto: disparar, avaliar, refinar, repetir. Isso facilita orquestrar subagentes, principalmente quando o seu processo precisa de crescimento previsível de contexto, e não de despejos amplos e ruidosos.

Casos de uso ideais

Este skill funciona bem para descoberta de arquitetura, exploração de codebase em estilo RAG e fluxos multiagente em que a primeira passada de recuperação é intencionalmente incompleta. Ele é menos útil quando a resposta já está local, o repo é pequeno ou você consegue fornecer a lista exata de arquivos desde o início.

Como usar o skill iterative-retrieval

Instale e ative

Use o caminho de instalação do skill no seu gerenciador de skills e, depois, aponte o workflow do seu agente para skills/iterative-retrieval/SKILL.md. Um padrão típico de instalação do iterative-retrieval neste repositório é:

npx skills add affaan-m/everything-claude-code --skill iterative-retrieval

Para melhores resultados, invoque o skill quando a tarefa depender de descoberta de contexto, e não depois que você já tiver selecionado manualmente todos os arquivos relevantes.

Transforme um objetivo vago em um prompt utilizável

O skill funciona melhor quando o prompt dá ao agente um alvo, um limite e uma regra de parada. Um input forte se parece com isto:

• Goal: “Find the auth flow and explain where token refresh is handled.”
• Boundary: “Search only production code, not tests.”
• Constraint: “Keep each retrieval pass under a few files.”
• Success condition: “Return the smallest file set that supports a confident answer.”

Isso importa porque iterative-retrieval usage tem a ver com refinar contexto, e não com pedir que o modelo adivinhe o repo inteiro a partir de uma solicitação vaga.

Leia estes arquivos primeiro

Comece com SKILL.md e, em seguida, examine qualquer documentação de apoio que o repo fornecer. Neste repositório, o ponto de entrada prático continua sendo SKILL.md; se a sua instalação copiar apenas o corpo do skill, esse é o source of truth. Depois disso, revise docs de workflow próximas, se existirem no seu ambiente, para alinhar o loop às suas próprias regras de orquestração.

Execute o loop de recuperação

Um bom fluxo é: disparar uma busca estreita, avaliar se o contexto retornado é suficiente, refinar a próxima busca com base no que faltou e repetir até o agente ter evidências suficientes para agir. O ponto principal é levar adiante os novos termos descobertos a cada passada, em vez de repetir a mesma consulta com outra redação.

FAQ do skill iterative-retrieval

O iterative-retrieval é só para codebases grandes?

Não. O tamanho importa, mas o verdadeiro gatilho é a incerteza. Se o agente não consegue prever quais arquivos importam antes de lê-los, o iterative-retrieval pode ajudar até em um repo de porte moderado.

Quando eu não devo usar?

Não use iterative-retrieval quando a tarefa já estiver bem delimitada, os arquivos relevantes forem conhecidos ou um prompt direto com entradas fixas resolver. Nesses casos, o loop adiciona overhead sem melhorar a resposta.

Isso é melhor do que um prompt normal?

Para tarefas de descoberta, sim. Um prompt normal muitas vezes presume que o modelo consegue adivinhar o contexto certo de antemão. O guia de iterative-retrieval é melhor quando o prompt precisa se adaptar depois de ler resultados parciais e a resposta final depende dessa adaptação.

É amigável para iniciantes?

Sim, desde que você siga o loop literalmente. A curva de aprendizado principal não é sintaxe; é escolher uma primeira recuperação que seja pequena o bastante para ser útil e ampla o bastante para revelar a terminologia certa.

Como melhorar o skill iterative-retrieval

Dê mais precisão à primeira passada

O maior ganho de qualidade vem de um framing inicial melhor. Em vez de “encontre código relevante”, peça um comportamento, subsistema ou ponto de decisão específico. Inclua o que você já sabe, o que suspeita e o que contaria como um indício útil. Isso torna o iterative-retrieval usage muito mais eficiente.

Fique atento aos modos de falha comuns

A falha mais comum é over-retrieval: o agente puxa arquivos demais e para de aprender com os resultados. A outra é under-retrieval: contexto de menos para identificar o próximo termo de busca. Se a primeira passada trouxer arquivos genéricos, refine pedindo terminologia, call sites ou entry points, em vez de ampliar a busca.

Itere com evidências, não com suposições

Depois da primeira saída, devolva apenas os artefatos mais informativos: nomes de arquivos, nomes de funções, mensagens de erro ou termos desconhecidos. Evite pedir que o agente “olhe de novo” sem acrescentar evidências novas. Para iterative-retrieval for Workflow Automation, a melhoria mais forte é codificar esse loop de evidências na sua orquestração para que cada passada altere o espaço de busca.

Adapte ao conjunto de regras do seu repositório

Se o seu ambiente tiver convenções de nomenclatura, limites de pastas ou regras de handoff entre agentes, incorpore isso ao prompt antes da primeira recuperação. O skill é mais forte quando respeita a estrutura real do seu repo, em vez de tratar todo codebase como um problema genérico de busca.