Версионирование промптов для релизов без сюрпризов

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

Промпт ломается не потому, что текст "стал хуже". Чаще одна маленькая правка меняет поведение модели сразу в нескольких местах. Вы убрали уточнение, переставили абзац, добавили фразу про краткость - и ассистент уже реже задает встречные вопросы, хуже держит формат ответа или начинает пропускать важные детали.

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

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

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

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

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

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

Что считать версией промпта

Версия промпта - это не только новый текст в поле system. Если вы меняете температуру, формат ответа или набор примеров, поведение модели тоже меняется. Значит, это уже новая версия.

Удобно смотреть на промпт как на контракт между приложением и моделью. В него обычно входят:

• system-промпт с правилами и ролью
• user-шаблон с переменными и местами, куда подставляются данные
• примеры ответов, если вы используете few-shot
• параметры и ограничения: модель, temperature, max_tokens, JSON-схема, запреты на темы или длину ответа

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

Что должно лежать рядом с версией

Рядом с текстом промпта храните настройки, от которых зависит результат. Для одной и той же формулировки переход с temperature 0.1 на 0.7 может изменить тон, длину и точность ответа сильнее, чем правка пары строк. То же касается имени модели.

Отдельно фиксируйте формат ответа. Если приложение ждет строгий JSON с полями status и reason, это часть версии. Если вчера модель писала свободный текст, а сегодня должна вернуть JSON, у вас уже другой релиз промптов, даже если смысл инструкции почти не изменился.

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

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

Как устроить репозиторий

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

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

Такой каркас обычно работает лучше всего:

prompts/
  support_chat/
    prod/
      system.md
      developer.md
      params.yaml
    tests/
      cases.yaml
      fixtures/
    rules.md
    drafts/
  invoice_extraction/
    prod/
    tests/
    rules.md
    drafts/

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

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

Черновики и продовые версии не смешивайте. Папки drafts и prod решают больше проблем, чем кажется. Редактор сразу понимает, что можно менять свободно, а что участвует в релизе. Если текст не прошел ревью, он не попадает в prod. И откат потом делать проще: команда возвращает прошлую рабочую версию, а не ищет ее среди папок вроде final_final_new.

Хороший репозиторий выглядит скучно и предсказуемо. Для релизов это почти всегда плюс.

Как назвать файлы и версии

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

Хороший шаблон обычно такой:

• support/refund_request/system.md
• sales/lead_qualify/user.md
• risk/pii_redaction/system.md
• routing/model_fallback/policy.md

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

С версиями работает та же логика. Не усложняйте. Для стабильных состояний хватит простых тегов: v1, v1.1, v2. Если команда выкатывает промпты вместе с кодом, удобно привязывать тег к релизу приложения, но у самого промпта все равно должна быть своя понятная версия. Тогда легче сказать: "на проде стоит support/refund_request/system.md версии v1.2", а не искать, какой из пяти файлов с суффиксом final оказался живым.

Срочные правки сильнее всего портят порядок. Люди спешат и создают copy-final, final-2, really-final, а потом никто не помнит, что именно ушло в прод. Лучше держать один основной файл и менять только его версию. Если правка срочная, добавьте тег hotfix-2026-04 или v1.2.1, но не плодите клоны.

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

Так проще сравнивать версии и разбирать сбои. Команда видит, что изменилось: сам текст, параметры или выбор модели.

Как менять промпт по шагам

Когда команда правит промпт без порядка, мелкая правка легко превращается в долгий разбор инцидента. Намного спокойнее относиться к промпту как к коду: менять понемногу, проверять на одном и том же наборе примеров и держать быстрый откат под рукой.

Рабочий процесс обычно такой:

1. Сначала запишите цель изменения одной фразой. Не "сделать лучше", а, например, "сократить длину ответа до 5 предложений для заявок в поддержку".
2. Потом добавьте тесты на старые сбои. Если модель раньше путала язык ответа, пропускала обязательное поле или уходила в лишние объяснения, эти случаи должны появиться в наборе проверок до правки текста.
3. Меняйте только одну вещь за раз. Если вы сразу перепишете роль, формат вывода и правила отказа, никто не поймет, что именно дало эффект.
4. Сравните старую и новую версии на одном наборе входов. Иначе у вас будут две красивые таблицы, которые нельзя честно сопоставить.
5. Выпустите новую версию сначала на малую долю трафика. Даже 5% запросов часто хватает, чтобы увидеть рост ошибок, задержки или неожиданный стиль ответа.

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

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

Если трафик к LLM идет через единый шлюз, канареечный запуск делать проще: одна и та же нагрузка проходит по одинаковому пути, а вы сравниваете только поведение промпта. В AI Router для этого можно оставить тот же endpoint и код, а развести версии на уровне релиза и логов.

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

Как тестировать перед выкладкой

Один и тот же промпт может пройти ручную проверку и все равно сломать прод через день. Обычно причина простая: команда смотрит на общий смысл ответа, но не проверяет то, без чего цепочка дальше не работает. Если ответ должен вернуть intent, language и короткое summary, тест должен проверить именно эти поля, а не только ощущение, что "в целом ответ нормальный".

Перед merge полезен короткий smoke-набор. Это 10-20 запросов, которые проходят за пару минут и быстро ловят грубые ошибки: пустой JSON, лишний текст вокруг структуры, смену тона, потерю обязательного поля. Такой набор не доказывает, что промпт хорош. Зато он хорошо ловит поломки после маленькой правки.

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

Что нужно зафиксировать

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

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

Что сохранять после прогона

Храните не только итог "прошло / не прошло". Сохраняйте удачные и провальные ответы рядом с тест-кейсом. Потом их легко сравнить по diff и понять, что именно изменилось: структура, полнота, тон или длина.

Минимальный набор перед выкладкой выглядит так:

• smoke-тест на малом наборе перед merge
• регрессии на старых проблемных примерах
• проверка обязательных полей и формата ответа
• фиксированные параметры модели для честного сравнения
• сохраненные примеры хороших и плохих ответов

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

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

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

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

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

Хуже всего, когда старые примеры удаляют "за ненадобностью". Вместе с ними команда теряет память о прошлых сбоях. Через месяц кто-то снова вносит правку, возвращает старую проблему и искренне думает, что нашел удачное улучшение.

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

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

Обычно риск растет, если вы видите такие признаки:

• в одном PR меняются и инструкции, и модель, и параметры
• тестовый набор меньше десяти примеров, и в нем нет сложных случаев
• рабочая версия промпта живет не в Git, а в чате или админке без истории
• команда не хранит прошлые неудачные кейсы
• никто не знает, какой commit вернуть за пять минут

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

Пример из обычного релиза

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

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

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

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

После отката команда смотрит diff и быстро находит, что исчезло. Вместе с лишним текстом разработчик удалил короткую инструкцию, которая требовала заполнять поле reason при каждом отказе. Это не "умное поведение модели", а обычная ошибка в редактировании.

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

Это и есть рабочая схема. Команда меняет промпт маленькими частями, ловит поломку до выкладки, быстро откатывается и выпускает точечную правку вместо нервного ручного ремонта.

Короткая проверка перед релизом

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

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

Проверьте пять вещей.

• У правки есть один ответственный. Это не "вся команда", а конкретный человек, который может объяснить цель в одном предложении. Например: "снизить число отказов на запросах с длинным контекстом".
• Diff чистый. Если в нем вместе лежат новая инструкция, переименование файлов и случайная правка примеров, ревью теряет смысл. Хороший diff показывает только то, что влияет на поведение.
• Эталонный набор тестов зеленый. Нужен понятный прогон: те же входы, те же ожидаемые признаки ответа и те же условия запуска. Если один тест стал лучше, а два старых просели, релиз рано выпускать.
• Команда знает точку отката. Номер версии, тег или commit должны быть записаны заранее. В момент сбоя никто не хочет вспоминать, какой из трех "final" файлов был последним рабочим.
• Метрики на первые сутки выбраны до релиза. Обычно хватает 3-4: доля успешных ответов, средняя длина ответа, число ручных эскалаций, цена или задержка. Иначе после выкладки все смотрят на разное и спорят о впечатлениях.

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

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

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

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

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

До следующего релиза соберите маленький набор тестов. Не нужен огромный архив. Для старта хватит 10-15 примеров:

• 5 обычных запросов, которые проходят каждый день
• 2 длинных или шумных входа
• 2 случая с неоднозначной формулировкой
• 1-2 плохих ввода, на которых модель часто срывается
• 1 пример, который раньше уже ломался в проде

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

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

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

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