Iterative Context Retrieval

Оптимизируйте рабочие процессы Claude Code с помощью Iterative Context Retrieval. Решите проблему контекста в мультиагентных системах, используя 4-этапный цикл уточнения для RAG.

Инструменты разработчика ★ 112,917 GitHub (112,917 ★)

Iterative Context Retrieval — это сложный паттерн, разработанный для Claude Code и агентных рабочих процессов, чтобы преодолеть ограничения фиксированного контекста. Реализуя 4-этапный цикл (Dispatch, Evaluate, Refine, Loop), этот навык позволяет агентам постепенно обнаруживать наиболее релевантные файлы и шаблоны кода в большой кодовой базе. Он предотвращает типичные ошибки, такие как превышение лимита контекста или неверные предположения, оценивая релевантность файлов и уточняя критерии поиска на основе найденной терминологии. Это гарантирует, что под-агенты получают именно ту информацию, которая необходима для точного выполнения задач, и при этом значительно оптимизируется использование токенов.

Ключевые особенности

01Оптимизация использования токенов за счёт исключения нерелевантных путей и приоритизации лучших кандидатов

02Четырёхэтапный цикл обратной связи (Dispatch, Evaluate, Refine, Loop) для точного обнаружения контекста

03Система оценки релевантности (от 0.0 до 1.0) для отбора наиболее значимых файлов

04Динамическое уточнение поисковых запросов на основе обнаруженной терминологии кодовой базы

05Автоматическое выявление пробелов для поиска недостающего архитектурного контекста

06112 917 звёзд на GitHub

Варианты использования

01Реализация новых функций, которые должны соответствовать существующим внутренним паттернам и промежуточным слоям

02Сокращение затрат на токены в RAG-ориентированных рабочих процессах ИИ-кодинга за счёт сужения фокуса поиска

03Поиск релевантных файлов для исправления ошибок в незнакомых или огромных кодовых базах

name	iterative-retrieval
description	逐步优化上下文检索以解决子代理上下文问题的模式
origin	ECC

迭代检索模式

解决多智能体工作流中的“上下文问题”，即子智能体在开始工作前不知道需要哪些上下文。

何时激活

当需要生成需要代码库上下文但无法预先预测的子代理时
构建需要逐步完善上下文的多代理工作流时
在代理任务中遇到"上下文过大"或"缺少上下文"的失败时
为代码探索设计类似 RAG 的检索��道时
在代理编排中优化令牌使用时

问题

子智能体被生成时上下文有限。它们不知道：

哪些文件包含相关代码
代码库中存在哪些模式
项目使用什么术语

标准方法会失败：

发送所有内容：超出上下文限制
不发送任何内容：智能体缺乏关键信息
猜测所需内容：经常出错

解决方案：迭代检索

一个逐步优化上下文的 4 阶段循环：

┌─────────────────────────────────────────────┐
│                                             │
│   ┌──────────┐      ┌──────────┐            │
│   │  调度    │─────▶│  评估    │            │
│   └──────────┘      └─────────��┘            │
│        ▲                  │                 │
│        │                  ▼                 │
│   ┌──────────┐      ┌──────────┐            │
│   │  循环    │◀─────│  优化    │            │
│   └──────────┘      └──────────┘            │
│                                             │
│        最多3次循环，然后继续                 │
└─────────────────────────────────────────────┘

阶段 1：调度

初始的广泛查询以收集候选文件：

// Start with high-level intent
const initialQuery = {
  patterns: ['src/**/*.ts', 'lib/**/*.ts'],
  keywords: ['authentication', 'user', 'session'],
  excludes: ['*.test.ts', '*.spec.ts']
};

// Dispatch to retrieval agent
const candidates = await retrieveFiles(initialQuery);

阶段 2：评估

评估检索到的内容的相关性：

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)
  }));
}

评分标准：

高 (0.8-1.0)：直接实现目标功能
中 (0.5-0.7)：包含相关模式或类型
低 (0.2-0.4)：略微相关
无 (0-0.2)：不相关，排除

阶段 3：优化

根据评估结果更新搜索条件：

function refineQuery(evaluation, previousQuery) {
  return {
    // Add new patterns discovered in high-relevance files
    patterns: [...previousQuery.patterns, ...extractPatterns(evaluation)],

    // Add terminology found in codebase
    keywords: [...previousQuery.keywords, ...extractKeywords(evaluation)],

    // Exclude confirmed irrelevant paths
    excludes: [...previousQuery.excludes, ...evaluation
      .filter(e => e.relevance < 0.2)
      .map(e => e.path)
    ],

    // Target specific gaps
    focusAreas: evaluation
      .flatMap(e => e.missingContext)
      .filter(unique)
  };
}

阶段 4：循环

使用优化后的条件重复（最多 3 个周期）：

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);

    // Check if we have sufficient context
    const highRelevance = evaluation.filter(e => e.relevance >= 0.7);
    if (highRelevance.length >= 3 && !hasCriticalGaps(evaluation)) {
      return highRelevance;
    }

    // Refine and continue
    query = refineQuery(evaluation, query);
    bestContext = mergeContext(bestContext, highRelevance);
  }

  return bestContext;
}

实际示例

示例 1：错误修复上下文

任务："修复身份验证令牌过期错误"

循环 1:
  分发：在 src/** 中搜索 "token"、"auth"、"expiry"
  评估：找到 auth.ts (0.9)、tokens.ts (0.8)、user.ts (0.3)
  优化：添加 "refresh"、"jwt" 关键词；排除 user.ts

循环 2:
  分发：搜索优化后的关键词
  评估：找到 session-manager.ts (0.95)、jwt-utils.ts (0.85)
  优化：上下文已充分（2 个高相关文件）

结果：auth.ts、tokens.ts、session-manager.ts、jwt-utils.ts

示例 2：功能实现

任务："为API端点添加速率限制"

周期 1：
  分发：在 routes/** 中搜索 "rate"、"limit"、"api"
  评估：无匹配项 - 代码库使用 "throttle" 术语
  优化：添加 "throttle"、"middleware" 关键词

周期 2：
  分发：搜索优化后的术语
  评估：找到 throttle.ts (0.9)、middleware/index.ts (0.7)
  优化：需要路由模式

周期 3：
  分发：搜索 "router"、"express" 模式
  评估：找到 router-setup.ts (0.8)
  优化：上下文已足够

结果：throttle.ts、middleware/index.ts、router-setup.ts

与智能体集成

在智能体提示中使用：

在为该任务检索上下文时：
1. 从广泛的关键词搜索开始
2. 评估每个文件的相关性（0-1 分制）
3. 识别仍缺失哪些上下文
4. 优化搜索条件并重复（最多 3 个循环）
5. 返回相关性 >= 0.7 的文件

最佳实践

先宽泛，后逐步细化 - 不要过度指定初始查询
学习代码库术语 - 第一轮循环通常能揭示命名约定
跟踪缺失内容 - 明确识别差距以驱动优化
在“足够好”时停止 - 3 个高相关性文件胜过 10 个中等相关性文件
自信地排除 - 低相关性文件不会变得相关

🧠 Что это

Iterative Context Retrieval (итеративное извлечение контекста) — это паттерн для многоагентных рабочих процессов, решающий проблему «контекстного дефицита» у дочерних агентов. Когда под-агент создаётся для выполнения конкретной задачи, он часто не знает, какие файлы, термины или архитектурные паттерны релевантны. Стандартные подходы — передать всё (переполнение токенов) или ничего (потеря точности) — не работают. Предлагается цикл из четырёх фаз: Dispatch (отправка широкого запроса), Evaluate (оценка релевантности), Refine (уточнение запроса) и Loop (повтор до 3 раз).

⚙️ Как работает

Паттерн реализует четырёхфазный цикл, который постепенно сужает поиск нужного контекста.

📦 1. Dispatch (отправка)

Начинается с широкого запроса: указываются маски файлов (src/**/*.ts), ключевые слова (authentication, user, session) и исключения (*.test.ts). Задача — собрать как можно больше потенциально релевантных кандидатов.

# Пример начального запроса
patterns: ['src/**/*.ts', 'lib/**/*.ts']
keywords: ['authentication', 'user', 'session']
excludes: ['*.test.ts', '*.spec.ts']

🔍 2. Evaluate (оценка)

Каждый найденный файл оценивается по шкале от 0 до 1:

0.8–1.0 — прямо реализует целевую функцию
0.5–0.7 — содержит связанные паттерны или типы
0.2–0.4 — слабо связан
0–0.2 — нерелевантен, исключается

Также фиксируются пробелы в контексте — что ещё не найдено.

🔧 3. Refine (уточнение)

На основе оценки уточняется запрос:

Добавляются новые паттерны из высокорелевантных файлов
Добавляются новые ключевые слова (например, jwt, refresh, throttle)
Исключаются пути с низкой релевантностью
Определяются фокус-области для устранения пробелов

🔄 4. Loop (цикл)

С уточнённым запросом повторяются фазы 1–3. Максимум 3 цикла. Цикл прерывается досрочно, если набрано минимум 3 файла с релевантностью ≥ 0.7 и нет критических пробелов.

🧩 Когда использовать

Генерация под-агентов, которым нужен контекст кодовой базы, но неизвестно заранее, какие файлы понадобятся.
Многоагентные рабочие процессы, где каждый агент должен быстро погрузиться в задачу без перегрузки контекстом.
Отладка ошибок, когда нужно найти корень проблемы — пример: «исправить ошибку истечения токена» → последовательно находятся auth.ts, tokens.ts, session-manager.ts.
Реализация новых функций — например, добавление rate limiting, когда кодовая база использует термин throttle, а не rate limit.

💡 Важно знать

Начинайте широко, не переопределяйте начальный запрос — первые циклы часто раскрывают реальную терминологию проекта.
Учитесь на каждом цикле: даже низкорелевантные файлы дают новые ключевые слова и паттерны.
Не гонитесь за полнотой: три файла с релевантностью ≥ 0.7 часто полезнее десяти средних.
Исключайте уверенно: если файл получил < 0.2, он вряд ли станет полезным в следующих циклах.
Оптимизируйте циклы: максимум 3, иначе тратятся лишние токены без значительного прироста качества.

🛠 Интеграция с агентами

В промпте агента можно использовать инструкцию:

Для извлечения контекста выполни:

Начни с широкого поиска по ключевым словам.

Оцени каждый файл по шкале 0–1.

Определи, какого контекста не хватает.

Уточни запрос и повтори (макс. 3 раза).

Верни файлы с релевантностью ≥ 0.7.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code iterative-retrieval

Источник: https://mcpmarket.com/tools/skills/iterative-context-retrieval-1774677981221