← Все гайды AI Release
EN Подписаться на @ai_release1

Как настроить QMD для кодинг-агентов и сократить расход токенов на поиск файлов

Обновлено: 16.11.2026 · AI Release · @ai_release1
Как настроить QMD для кодинг-агентов и сократить расход токенов на поиск файлов

TL;DR

QMD — локальный поисковый движок по markdown-файлам и коду, который отдаёт агенту не файлы целиком, а top-k релевантных фрагментов. MCP (Model Context Protocol) — стандарт, по которому агент вызывает внешние инструменты; через него агент и обращается к QMD.

Требования и подготовка

Иллюстрация к разделу «Требования и подготовка»
Иллюстрация к разделу «Требования и подготовка»

Как работает схема (поток данных):

1. QMD один раз обходит каталоги и строит локальный индекс: разбивает файлы на фрагменты и сохраняет их в файл на диске.

2. Агент вместо grep -r и чтения файлов целиком делает один MCP-вызов поиска.

3. QMD возвращает 3–10 фрагментов с путём и номером строки.

4. Агент открывает только тот файл, который ему действительно нужен.

Экономия возникает на шаге 3–4: агенту в контекст попадают сотни строк вместо десятков тысяч.

Пример: монорепозиторий, где документация лежит в docs/, а сервисы — в services/api/ и services/worker/. Создаём две коллекции — docs и services, — чтобы поиск по документации не разбавлялся кодом.

Если вместо лёгкого индекса нужен полноценный локальный семантический поиск с эмбеддингами, посмотрите разбор Как настроить локальный семантический поиск по файлам с Rummage и EmbeddingGemma 2 — там тот же принцип «сначала индекс, потом ответ».

Шаг 1. Установите QMD и проверьте CLI

Что сделать: поставить QMD глобально и убедиться, что бинарник доступен в PATH.

Зачем: агенту нужно запускать сервер по имени команды; если бинарник не в PATH, MCP-подключение упадёт ещё до поиска.

npm install -g qmd
qmd --version
qmd --help

Пример: qmd --help печатает список подкоманд. Если в вашей версии установка описана иначе (bun, Homebrew, готовый бинарник) — сверьтесь с разделом Install в документации проекта; имя пакета и флаги между версиями меняются.

Как проверить: команда qmd --version выводит строку с номером версии без ошибок, а qmd --help — список подкоманд. Запишите путь к бинарнику — он понадобится в Шаге 3:

which qmd
# например: /usr/local/bin/qmd

Почему это работает: MCP-клиент запускает процесс по имени или абсолютному пути; глобальная установка кладёт исполняемый файл в PATH, поэтому агент находит его без дополнительных настроек.

Шаг 2. Соберите индекс и ограничьте область поиска

Иллюстрация к разделу «Шаг 2. Соберите индекс и ограничьте область поиска»
Иллюстрация к разделу «Шаг 2. Соберите индекс и ограничьте область поиска»

Что сделать: добавить каталоги как коллекции, собрать индекс и исключить мусор — node_modules, сборки, .env, логи.

Зачем: индекс по node_modules и dist раздувает файл на диске и подмешивает в выдачу нерелевантные фрагменты, из-за чего агент снова начинает читать лишнее.

cd <путь-к-репозиторию>

# регистрируем коллекции
qmd collection add ./docs      --name docs
qmd collection add ./services  --name services

# строим индекс
qmd index

# смотрим, что получилось
qmd status
qmd collections

Пример: после qmd index команда qmd status показывает число проиндексированных документов и фрагментов по каждой коллекции. Если по коллекции docs ноль документов — путь указан неверно.

Что включать и что исключать:

КаталогВключатьПричина
`docs/`, `*.md`даосновные знания для агента
`services/**/*.ts`даисходники, по которым идёт поиск
`node_modules/`, `dist/`, `build/`нетшум и лишний объём индекса
`.env`, `*.pem`, ключинетсекреты не должны попадать ни в индекс, ни в контекст агента

Правила исключения задаются в конфиге QMD или через фильтры коллекции — синтаксис сверьте с документацией (qmd collection add --help). Каталоги с секретами проще не регистрировать вовсе.

Как проверить: выполните тестовый поиск и убедитесь, что в выдаче есть пути из нужных каталогов:

qmd search "rate limit" --limit 5

Ожидаемый результат — 5 строк вида docs/api/limits.md:12 ...фрагмент.... Если выдача пустая или в ней только пути из node_modules — вернитесь к регистрации коллекций.

Пересобирайте индекс после крупных правок: qmd index. Если расходы на агента выходят за бюджет, ограничьте их отдельно — см. Как настроить лимиты расходов и бюджеты для ИИ-агентов: контроль затрат на API.

Шаг 3. Подключите MCP-сервер к агенту и замерьте экономию

Иллюстрация к разделу «Шаг 3. Подключите MCP-сервер к агенту и замерьте экономию»
Иллюстрация к разделу «Шаг 3. Подключите MCP-сервер к агенту и замерьте экономию»

Что сделать: прописать QMD как MCP-сервер в конфиге агента и сравнить объём данных, который агент читает при обычном поиске и через QMD.

Зачем: без MCP-подключения агент про QMD не знает и продолжает жечь токены на grep и чтение файлов целиком.

Для Claude Code конфиг проекта — файл .mcp.json в корне репозитория:

{
  "mcpServers": {
    "qmd": {
      "command": "/usr/local/bin/qmd",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Для Cursor тот же блок кладётся в ~/.cursor/mcp.json. Точное имя подкоманды запуска сервера (mcp или иное) сверьте с qmd --help — это единственное место, где конфиг зависит от версии.

Пример: в Claude Code команда /mcp показывает список серверов; рядом с qmd должен быть статус connected. Если статус failed — смотрите раздел «Возможные проблемы».

Теперь замер. Сравниваем, сколько байт текста уходит в контекст при обычном поиске и при поиске через QMD:

# 1) «слепой» поиск: сколько байт в файлах, которые агент прочитал бы целиком
grep -rIl "rate limit" . --exclude-dir=node_modules | xargs wc -c | tail -1

# 2) выдача QMD
qmd search "rate limit" --limit 5 > /tmp/qmd.out
wc -c /tmp/qmd.out

Пример вывода: первая команда — 412033 total, вторая — 3800 /tmp/qmd.out. Подставьте свои значения: соотношение и есть ваша экономия в байтах. Байты переведите в токены тем же токенизатором, что использует ваша модель, — коэффициент зависит от языка и кода.

Чек-лист приёмки:

Почему это работает: инструмент поиска попадает в список доступных агенту функций, и модель выбирает его вместо обхода файловой системы — контекст наполняется только найденными фрагментами.

Возможные проблемы и решения

Проблема. Агент не видит инструмент QMD

Проблема. Поиск возвращает пустую выдачу

Проблема. Ошибка авторизации при построении индекса

Резюме и следующие шаги

Вы развернули локальный индекс QMD, подключили его к агенту через MCP и получили воспроизводимый замер расхода контекста до и после. Дальше имеет смысл автоматизировать пересборку индекса и отдельно ограничить бюджеты API-вызовов агента.

FAQ

Что такое QMD простыми словами?

Локальный поисковый движок по markdown и коду, который по запросу возвращает несколько релевантных фрагментов с путями и номерами строк вместо целых файлов.

Экономит ли QMD токены, если агент всё равно открывает файл?

Да, потому что агент открывает один файл по точному пути, а не перебирает grep -r и не читает десятки кандидатов целиком; разницу покажет замер из Шага 3.

Нужен ли API-ключ для работы QMD?

Зависит от конфигурации: локальные модели эмбеддингов ключа не требуют, облачные — требуют. Поддерживаемые провайдеры и имена переменных сверьте с документацией.

Безопасно ли индексировать рабочий репозиторий?

Индекс хранится локально, но всё, что в него попало, может уйти в контекст агента. Не регистрируйте каталоги с .env, ключами и приватными данными — общие правила в Безопасность ИИ-агентов: как защитить данные и избежать утечек.

🤖 Кратко для ИИ

AI Release Knowledge Layer
Машинно-читаемое описание публикации · Версия 1.0

Статус: практическое руководство. Часть утверждений — заявления вендоров и проектов; проверяйте на своей среде.

1. Суть публикации

Пошаговое руководство по установке, индексации проекта и подключению QMD к Claude Code и другим ИИ-агентам, чтобы меньше тратить токены на поиск файлов. Время выполнения: 30–45 минут Уровень сложности: Intermediate

Внутри: прямые ответы, ключевые факты, участники, связи, достоверность, неизвестное и источники.

Машинные данные публикации: Citation Map JSON · JSON-LD · Semantic Embeddings — отдельный этап.

Полный Knowledge Layer: разделы 2–8

2. Прямые ответы

Что это за материал?
Пошаговое руководство по установке, индексации проекта и подключению QMD к Claude Code и другим ИИ-агентам, чтобы меньше тратить токены на поиск файлов. → подробнее (AR-GUIDE-KAKNASTROI-001)
Что понадобится?
ОС: macOS 13+, Ubuntu 22.04+ или Windows 10/11 с WSL2.; Node.js LTS и npm — проверить: node -v && npm -v. Точную минимальную версию сверьте с документацией QMD.; git — QMD индексирует рабочую копию, а не историю коммитов.; Кодинг-агент с MCP: Claude Code (claude --version), Cursor или аналог. → подробнее (AR-GUIDE-KAKNASTROI-003)
Как это сделать?
Шаг 1. Установите QMD и проверьте CLI → Шаг 2. Соберите индекс и ограничьте область поиска → Шаг 3. Подключите MCP-сервер к агенту и замерьте экономию → подробнее (AR-GUIDE-KAKNASTROI-004)
Что может пойти не так?
Ошибка: MCP error -32000: Connection closed → подробнее (AR-GUIDE-KAKNASTROI-006)

3. Ключевые факты

  1. Время выполнения: 30–45 минут — подтверждение; статус: заявление источника.
  2. Уровень сложности: Intermediate — подтверждение; статус: заявление источника.
  3. Понадобится: macOS, Linux или WSL2; Node.js LTS (или bun); git; кодинг-агент с поддержкой MCP (Claude Code, Cursor или аналог); репозиторий с markdown-документацией и кодом; свободное место под локальный файл индекса — оцените по размеру репозитория, индекс лежит на диске рядом с ним — подтверждение; статус: заявление источника.
  4. ОС: macOS 13+, Ubuntu 22.04+ или Windows 10/11 с WSL2. — подтверждение; статус: заявление источника.
  5. Node.js LTS и npm — проверить: node -v && npm -v. Точную минимальную версию сверьте с документацией QMD. — подтверждение; статус: заявление источника.
  6. git — QMD индексирует рабочую копию, а не историю коммитов. — подтверждение; статус: заявление источника.
  7. Ошибка: MCP error -32000: Connection closed — подтверждение; статус: анализ AI Release.
  8. Причина: MCP-клиент запускает процесс в окружении без вашего PATH (типично для GUI-приложений), поэтому "command": "qmd" не находится. — подтверждение; статус: анализ AI Release.

4. Участники и сущности

СущностьТипРоль в публикации
QMD для кодинг-агентовтема/инструментупоминается в заголовке, TL;DR или разделах гайда
как настроить QMDтема/инструментупоминается в заголовке, TL;DR или разделах гайда
экономия токенов ИИ-агентатема/инструментупоминается в заголовке, TL;DR или разделах гайда
Windowsплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Linuxплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
macOSплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Node.jsплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
npmплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Gitплатформа/технологияупоминается в заголовке, TL;DR или разделах гайда
Claudeтема/инструментупоминается в заголовке, TL;DR или разделах гайда

5. Связи и контекст

  • Гайд — описывает → Как настроить QMD для кодинг-агентов и сократить расход токенов на поиск файлов (AR-GUIDE-KAKNASTROI-001).
  • Гайд — содержит шаг → Шаг 1. Установите QMD и проверьте CLI (AR-GUIDE-KAKNASTROI-001).

6. Достоверность и происхождение информации

Подтверждено

В материале нет отдельного независимого подтверждения; ниже разделены заявления источников и редакционные выводы.

Заявление источника

  • Характеристики продуктов, версии, цены и лимиты — из описаний вендоров и материалов гайда.
  • Команды и шаги приведены как рекомендация, а не как гарантированный результат.

Анализ AI Release

  • Структура, сравнение и критерии выбора — редакционные.
  • Гайд не заменяет независимый аудит или юридическую консультацию.

7. Что пока неизвестно

  • Ошибка: MCP error -32000: Connection closed
  • Причина: MCP-клиент запускает процесс в окружении без вашего PATH (типично для GUI-приложений), поэтому "command": "qmd" не находится.
  • Решение: укажите абсолютный путь из which qmd в поле command и перезапустите агент. Проверка — /mcp показывает connected.
  • Ошибка: qmd status печатает documents: 0 для коллекции, агент отвечает «No results found».

8. Источники

ИсточникТипРоль
Внешние ссылки в материале не указаны——

Как цитировать: AI Release. Как настроить QMD для кодинг-агентов и сократить расход токенов на поиск файлов. ai-release.org.