Инструкции для базы знаний: как научить агента искать

Зачем нужны инструкции

Мы проверили это на частной базе знаний курса: четыре модели Claude, одни и те же вопросы, с инструкциями и без. Подробности — в статье Нужны ли агенту инструкции к базе знаний. Главное:

• Слабым моделям инструкции нужны. Claude Haiku без инструкций дала все провалы прогона: один раз решила, что доступа к базе нет, и ответила из головы. С инструкциями провалов не было, а нужную заметку она открывала в 12 вопросах из 13 вместо 9.
• Сильные модели находят инструкции сами. Sonnet, Opus и Fable без подсказки при подключении в большинстве запусков сами вызывали инструмент instructions(). Им хватает того, что инструкции вообще есть.
• Правила формата работают. Правило «отвечай цитатой из заметки» подняло долю ответов с дословной цитатой у Haiku с 0,12 до 0,81.

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

Где живут инструкции

Инструкции — это обычные заметки с полем mcp_method во frontmatter. Технические подробности — в документации MCP-сервера.

Добавьте free: true, если база открыта для анонимных клиентов. Иначе заметку получат только те, у кого есть доступ.

Инструкции как навык поиска по базе

Инструкции удобно воспринимать как навык (skill) агента: «как искать в этой базе знаний». Устройство то же, что у навыков в Claude и других агентах — от общего к частному, и каждый уровень загружается, только когда нужен:

Из этого следуют правила письма. initialize должна отвечать на два вопроса: что это за база и когда за ней идти. Как в описании навыка, здесь не место подробностям, иначе они займут контекст каждого разговора, даже не связанного с базой. Подробности живут в instructions и справочных заметках, которые агент откроет сам. Хорошая проверка: если агент прочтёт только initialize, поймёт ли он, стоит ли вызывать instructions()?

Шаг 1. Сначала бенчмарк на своей базе

Не пишите инструкции из головы. Сначала посмотрите, где агент спотыкается на вашей базе без них, и пишите инструкции под эти места.

Соберите 15–30 вопросов, какие реально задают читатели базы. Смешайте типы:

• прямые — ответ лежит в одной заметке;
• ситуационные — «у меня X, что делать»;
• про деталь — число, порог, поле, спрятанные глубоко в длинной заметке;
• 3–5 вопросов, ответа на которые в базе нет. Без них вы не узнаете, выдумывает ли агент.

Для каждого вопроса запишите, какая заметка отвечает и что должно быть в правильном ответе.

Прогоните две модели без инструкций: одну слабую и дешёвую, одну сильную. Любой MCP-клиент подойдёт. Для каждого вопроса отметьте:

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

Шаг 2. Почините базу там, где спотыкается поиск

Часть ошибок лечится не инструкцией, а устройством базы. Это надёжнее: так вы помогаете любому агенту, даже тому, кто инструкции не прочтёт.

После правок прогоните бенчмарк ещё раз. Возможно, часть проблем уже ушла.

Шаг 3. Определите тип своей базы

Хорошие маршруты зависят от того, как устроена база.

Шаг 4. Напишите initialize

Короткая заметка, которую агент получает сразу при подключении. Её прочтут все модели, в том числе слабые, поэтому пишите конкретно и коротко: команды, а не рассуждения. Хороший объём — до 1500 символов.

Что в ней должно быть:

1. Что это за база и чего в ней нет — одной-двумя строками.
2. Откуда заходить — индексная заметка, карты, хабы, с путями.
3. Как искать — рецепт для вашей базы: какие запросы работают, limit, когда expand, когда note_html.
4. Как отвечать — ссылка на заметку, цитата, формат.
5. Что делать, если не нашёл. Пишите это правило так, чтобы агент сначала искал: «если после двух-трёх поисков материала нет — так и скажи». Правило «нет материала — отвечай, что нет» без этой оговорки слабая модель может применить сразу, не поискав.
6. Где подробности: «перед сложным вопросом вызови instructions()».

Пример для базы-курса:

---
mcp_method: initialize
free: true
---
База знаний курса фотографии: от настройки камеры до обработки снимков. Про покупку техники и продажу фотографий здесь ничего нет.

Начни с `note_html(path="_instructions.md")`: там маршруты по типам задач. Для ситуаций «что делать, если…» открой карту из `maps/` целиком.

Ищи коротко, названием понятия или этапа: `search("выдержка", limit=8)`, а не вопросом целиком. Нашёл заметку — читай нужный раздел через `note_html(path=..., toc_path=[...])`.

Отвечай действием из курса со ссылкой на заметку и цитатой из неё. Если после 2–3 поисков материала нет — так и скажи, не отвечай из общих знаний.

Шаг 5. Напишите подробную заметку instructions

Её вызывают сильные модели сами и слабые — по подсказке из initialize. Здесь место для деталей:

• Маршруты по типам задач. «Вопрос „почему снимки смазаны“ → maps/smazannye-snimki.md → по развилке нужная заметка». Берите типы из вопросов бенчмарка.
• Рабочие запросы. Те формулировки, которые в бенчмарке нашли нужное, и те, что не сработали. «Не ищи „как снимать ночью“ — ищи „длинная выдержка“ или „ISO шум“».
• Словарь. Какими словами база называет вещи, если они отличаются от разговорных.
• Пробелы. Что в базе есть частично, чего нет совсем и куда в таком случае отправлять читателя.
• Формат ответа подробнее: структура, длина, как цитировать, как ссылаться.

Шаг 6. Разные инструкции для разных моделей и ролей

Параметр ?method= выбирает, какую заметку клиент получит вместо initialize. Это позволяет держать несколько вариантов:

• для слабых и дешёвых моделей — пошаговый вариант: «1. открой индекс; 2. найди…; 3. ответь с цитатой». Им нужна жёсткая последовательность;
• для сильных моделей — короткий: что это за база и где подробности. Остальное они найдут сами;
• для отдельных ролей — например, «консультант для новичков» и «справка для кураторов».

---
mcp_method: initialize_steps
free: true
---
Отвечай строго по шагам: …

Клиент со слабой моделью подключается к /_system/mcp?method=initialize_steps, остальные — к /_system/mcp. Каждый вариант проверяйте своим прогоном бенчмарка.

Шаг 7. Перепроверьте и держите в актуальном виде

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

• агент перестал искать и отвечает по инструкциям или сдаётся раньше времени — перепишите правило «если не нашёл», добавьте «сначала поищи»;
• агент ходит только по маршрутам и не находит то, чего в них нет — добавьте «если маршрута нет, ищи через search»;
• инструкции разрослись, и слабая модель теряется — сократите initialize, детали перенесите в instructions.

Инструкции устаревают вместе с базой: появились новые разделы, переименовались заметки, изменились маршруты. После крупных правок базы прогоняйте бенчмарк снова. Держите вопросы бенчмарка рядом с базой, чтобы проверка занимала минуты.

Промпт для агента: пусть инструкции напишет он

Шаги 1–5 можно поручить агенту, подключённому к вашей базе по MCP. Дайте ему эту страницу и промпт:

Ты помогаешь подготовить базу знаний к работе с агентами. База подключена к тебе по MCP.
Прочитай гайд «Инструкции для базы знаний» (приложен) и сделай по нему:

1. Изучи структуру базы через search, expand и note_html. Не читай существующие заметки
   с mcp_method, если они есть.
2. Предложи 20 вопросов читателя четырёх типов (прямые, ситуационные, про деталь,
   вопросы без ответа в базе). Для каждого — заметка-ответ и что должно быть в ответе.
   Проверь каждый ответ, открыв заметку.
3. Ответь на каждый вопрос сам, пользуясь только инструментами базы, и запиши путь:
   какие запросы работали, где ты свернул не туда, сколько вызовов понадобилось.
4. Составь список проблем базы (шаг 2 гайда) и предложи правки: индексы, карты,
   алиасы, заголовки.
5. Напиши черновик заметки initialize (до 1500 символов) и заметки instructions
   с маршрутами, рабочими запросами, словарём и пробелами.

Ничего не меняй в базе сам: верни вопросы, отчёт о проблемах и оба черновика.

Потом проверьте черновики бенчмарком (шаг 7) на слабой и сильной модели. Написанные агентом инструкции тоже надо мерить.

Чек-лист

• Есть 15–30 вопросов бенчмарка, в том числе 3–5 без ответа в базе.
• Бенчмарк прогнан без инструкций на слабой и сильной модели, ошибки выписаны.
• База поправлена там, где ошибки лечатся устройством: индекс, карты, алиасы, заголовки.
• initialize: до ~1500 символов, точки входа, рецепт поиска, формат ответа, правило «если после поиска не нашёл».
• instructions: маршруты, рабочие запросы, словарь, пробелы.
• Для слабых моделей или отдельных ролей есть свой ?method=, если он нужен.
• Бенчмарк прогнан с инструкциями, регрессий нет.
• Вопросы бенчмарка лежат рядом с базой, чтобы повторить проверку после правок.