Библиотека промптов для команды: структура и правила

Почему шаблоны расползаются по репозиториям

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

Проблема в том, что промпт часто живет рядом с кодом конкретного сервиса, а не рядом с другими шаблонами. Разработчик меняет текст там, где ему проще: в репозитории чат-бота, CRM-ассистента или внутреннего инструмента. До соседних репозиториев эта правка не доходит. Люди думают, что меняют локальную копию, хотя на деле правят общий рабочий шаблон.

В большой команде картина почти всегда одинаковая. Кто-то копирует удачный шаблон вместе с параметрами модели. Кто-то меняет стиль ответа под свой продукт. Кто-то сокращает системный промпт ради цены или задержки. А кто-то вообще не знает, какой файл считать основным.

Дальше тексты начинают расходиться не только по смыслу, но и по мелочам, которые сильно бьют по качеству. В одном месте модель отвечает сухо, в другом слишком разговорно. Где-то есть правила по формату JSON, а где-то их уже удалили. Один сервис просит не придумывать факты, другой потерял это ограничение после срочной правки.

Если команда работает с несколькими моделями и провайдерами через один слой, копий становится еще больше. Один и тот же шаблон лежит в сервисе поддержки, в классификаторе обращений и в генерации писем. Логика одна, а файлов три. Когда модель начинает ошибаться, люди спорят не о причине, а о том, какой вариант промпта сейчас стоит в продакшене.

Есть и организационная причина. У шаблона часто нет владельца. Кодом владеет команда сервиса, а текстом промпта вроде бы все и никто. Поэтому мелкие правки делают без общего правила: кто-то меняет формулировку, кто-то добавляет блок инструкций, кто-то переименовывает переменные. История решений теряется очень быстро.

Из-за этого библиотека промптов не складывается сама собой. Если не договориться о месте хранения и праве на изменения, команда получает не библиотеку, а набор похожих файлов с разными версиями правды. И чем дольше это тянется, тем дороже любая правка. Нужно не улучшить один шаблон, а найти все его копии и понять, какие из них еще живы.

Что считать единицей библиотеки

Единица библиотеки - не просто кусок текста в файле. Это один шаблон для одной задачи с понятными границами. Если промпт пишет краткое резюме обращения, он не должен заодно классифицировать тон, искать PII и готовить ответ клиенту. Для этого лучше завести отдельные шаблоны.

Удобно считать единицей не текст, а небольшой контракт: зачем нужен шаблон, что он получает на вход, что должен вернуть и в каких рамках работает. Тогда команда обсуждает не "удачную формулировку", а поведение шаблона. Это сразу снижает число дублей.

У каждого шаблона полезно хранить пять вещей: цель, сам текст, входные переменные, ожидаемый формат ответа и ограничения с тестовыми примерами.

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

Входные переменные лучше описывать явно. Не просто {text} и {context}, а что именно туда кладет сервис, какой объем допустим, какие поля обязательны. Рядом стоит держать маленький пример заполнения. Он экономит часы на догадки и споры о том, как шаблон должен жить в коде.

Формат ответа нужно фиксировать так же строго, как API-контракт. Если нужен JSON с полями category, summary и risk_score, это надо записать рядом с шаблоном, а не держать "по договоренности". Когда команда гоняет один и тот же шаблон через несколько моделей, именно формат ответа и тесты быстрее всего показывают, где поведение поплыло.

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

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

Как разложить библиотеку по папкам

Хорошая структура папок решает простую задачу: человек должен найти нужный шаблон за полминуты, а не вспоминать, в каком сервисе его когда-то положили. Поэтому раскладывать промпты лучше по сценарию использования. Не по папкам sales, support или team-a, а по задачам вроде classification, extraction, summarization, chat, moderation.

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

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

Черновики стоит держать отдельно от рабочих версий. Рабочая библиотека должна быть скучной и предсказуемой. Если смешать экспериментальные варианты с боевыми, разработчики начнут брать не тот файл просто потому, что он новее или лежит ближе.

Простая схема часто работает лучше всего:

prompts/
  shared/
    classification/
    extraction/
    safety/
  product/
    onboarding/
    support_reply/
    search_routing/
  drafts/
    classification/
    support_reply/
  tests/
    fixtures/
    eval_cases/

Еще один частый источник путаницы - когда в одной папке лежат сам промпт, тесты и клиентский код. Промпт меняют одни люди, тестовые кейсы пополняют другие, а код вызова модели живет по своим правилам. Когда все свалено вместе, папка быстро превращается в ящик с проводами.

Лучше держать эти части рядом, но не вперемешку. Например, prompts/ для шаблонов, tests/ для проверок и обычный кодовый каталог для обвязки. Тогда структура остается читаемой: где сам текст, где его проверяют, а где к нему подключаются из приложения.

Как назвать шаблоны и версии

Если у вас общая библиотека, имя шаблона должно отвечать на один вопрос: что он делает. Не из какого сервиса он пришел и не кто его написал, а какую задачу решает. Поэтому имя лучше начинать с действия: classify, extract, answer, rewrite, route.

Такой порядок сразу убирает шум. extract_invoice_fields понятнее, чем billing_prompt_final, а answer_support_faq лучше, чем assistant_v7_new.

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

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

С версиями тоже лучше без творчества. Короткая последовательность v1, v2, v3 почти всегда выигрывает у дат, суффиксов и меток вроде new, last или fixed. Если шаблон поменял формат ответа, правила извлечения или логику проверки, повышайте версию. Если вы просто исправили опечатку в описании, новую версию можно не заводить.

Статус лучше держать явно рядом с именем, а не в голове автора. Обычно хватает трех меток: draft, active, retired. Их можно хранить в метаданных файла, в реестре библиотеки или даже в имени, если у вас пока нет отдельного каталога.

И еще одна маленькая договоренность, которая экономит много времени: не переименовывайте старую версию после выпуска новой. Пусть v2 остается v2, даже если команда уже перешла на v3. Так проще сравнить ответы, откатить изменение и понять, какой шаблон живет в продакшене.

Кто отвечает за каждый шаблон

Если у шаблона нет одного владельца, он быстро превращается в общий файл, который правят все и никто не держит в голове целиком. Для большой команды это почти всегда заканчивается спорными правками, тихими копиями и разными версиями одного и того же промпта.

У каждого шаблона должен быть один владелец. Не группа, не роль вроде "ML-команда", а конкретный человек. Он решает, когда правка нужна, проверяет совместимость с текущим сценарием и следит, чтобы шаблон не дублировали под новым именем без причины.

Автор и владелец часто не совпадают, и это нормально. Автор написал первую версию. Владелец отвечает за жизнь шаблона после запуска: принимает изменения, следит за качеством, убирает устаревшие варианты. Если шаблон живет месяцами и проходит через несколько релизов, разделять эти роли даже полезно.

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

Срок нужен не для бюрократии. Он нужен, чтобы команда не ждала неделю из-за одной строки в системном промпте. Для шаблонов с высоким риском, например для клиентских ответов или извлечения персональных данных, срок можно сделать короче и добавить второго согласующего.

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

Передачу владения тоже нужно делать явно. Если сервис переходит в другую команду, вместе с кодом и алертами стоит передать и шаблоны, которые этот сервис использует. На практике про них часто забывают. Потом одна команда думает, что шаблон уже не ее, а другая еще не считает его своим.

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

Как внедрить библиотеку шаг за шагом

Когда шаблоны уже разошлись по сервисам, не пытайтесь сразу все переписать. Сначала соберите факты. Иначе команда потратит неделю на перенос, а дубли останутся на месте.

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

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

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

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

Библиотека начинает работать только тогда, когда у шаблона есть хозяин. Если владелец не назначен, спорные правки копятся, а новые версии снова уезжают в соседние репозитории.

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

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

Пример для команды с тремя сервисами

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

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

Рабочий вариант в такой ситуации простой: оставить один базовый шаблон и сделать три надстройки поверх него. В базовом шаблоне лежат общие правила: роль модели, стиль формулировок, ограничения по данным, словарь терминов продукта и общие инструкции по безопасности. Надстройки меняют только то, что относится к конкретному сервису.

prompts/
  base/
    system.v1.md
  chat/
    tone-support.v1.md
  search/
    output-json.v1.md
  mail/
    extract-email.v1.md

Чат собирает итоговый промпт из base/system.v1.md и chat/tone-support.v1.md. Поиск берет тот же базовый файл, но добавляет правило про строгий JSON с нужными полями. Сервис писем подключает свою надстройку, где модель извлекает тему, срочность, тип запроса и автора письма.

Такой подход экономит время на правках. Если команда меняет общий запрет на передачу персональных данных или обновляет формулировку по тону, достаточно один раз исправить базовый шаблон. Изменение уйдет во все три сервиса, а локальные отличия не сломаются.

На практике это еще и упрощает ревью. Люди быстро видят, где общая логика, а где поведение конкретного сервиса. Если команда запускает все через один LLM шлюз, этот порядок особенно удобен: код интеграции можно почти не трогать, а изменения остаются на уровне шаблонов.

Где команды чаще ошибаются

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

Первая частая ошибка - делить библиотеку по людям, а не по задачам. Папки вроде /petya, /masha или /team-a сначала кажутся удобными, но быстро ломаются. Люди переходят между проектами, а задачи остаются теми же: классифицировать обращение, извлечь поля из письма, сделать короткое резюме. Когда структура привязана к задаче, а не к автору, дублей обычно меньше.

Вторая ошибка - хранить одинаковые шаблоны под разными именами. Сегодня это ticket_router_v2, завтра support_classifier_final, а в третьем репозитории просто prompt.txt. С виду это три разных файла. На деле текст отличается на пару строк, и никто уже не помнит, какой вариант реально идет в продакшене.

Особенно дорого обходятся правки без новой версии. Разработчик меняет системный промпт прямо в рабочем сервисе, потому что "надо срочно поднять точность". На следующий день ответы меняются, метрики плывут, а команда спорит не о причине, а о том, кто что трогал.

Еще одна типичная ошибка - держать правила в голове. У шаблона нет короткого описания, нет примера входа, нет ожиданий по выходу, нет пометки, где его можно использовать. Новый человек открывает файл и правит его наугад. После пары таких правок шаблон уже решает немного другую задачу, хотя название осталось прежним.

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

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

Если библиотека уже расползлась, не переписывайте все сразу. Начните с шаблонов, из-за которых команда чаще всего спорит или откатывает изменения. Обычно после этого копий становится заметно меньше.

Короткая проверка перед публикацией

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

Название должно сразу объяснять задачу. По имени человек должен понять сценарий без открытия файла. У шаблона должны быть указаны владелец и статус. Достаточно знать, кто отвечает за правки и можно ли брать шаблон в новую работу.

Переменные тоже стоит называть одинаково во всех версиях. Если один шаблон ждет {{customer_name}}, а другой {{client_name}}, команда быстро придет к лишним адаптерам и путанице.

Еще один обязательный элемент - пример входа и ожидаемого ответа. Не красивый демонстрационный кейс, а обычный рабочий пример. Он сразу показывает, что подается на вход и какой результат считается нормальным.

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

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

Если по каждому пункту ответ ясен, шаблон можно публиковать. Если хотя бы один пункт вызывает вопрос, лучше вернуть файл на доработку. Неясный шаблон почти всегда заканчивается новой копией в соседнем репозитории.

Что делать дальше

Не пытайтесь собрать всю историю промптов за один заход. Такой старт почти всегда вязнет в спорах о старых шаблонах, которые уже никто не использует. Лучше взять 10-20 самых частых промптов, на которых команда тратит больше всего времени или чаще всего ловит ошибки.

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

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

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

Отдельно свяжите библиотеку с eval. Любая правка шаблона должна сразу проходить проверку на ваших типовых кейсах. Иначе один человек "чуть улучшит" формулировку, а через неделю другой сервис начнет отвечать хуже. Даже базовый набор из 15-20 тестовых сценариев уже заметно снижает риск.

Если команда гоняет одни и те же шаблоны через разные модели и провайдеров, заранее выберите единый эндпоинт и единый журнал запросов. Без этого трудно понять, какой шаблон дал сбой, где выросла цена и какая версия ушла в продакшен. Для команд в РФ это часто удобно решают через RU LLM: можно работать с разными моделями через один совместимый интерфейс и не разводить отдельную интеграцию под каждого провайдера.

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