contracts/History/topics/prompt-strategy.md

Prompt Management Strategy

Дата: 2026-06-23 | Версия: v1.0 | Контекст: v1.0.109, обсуждение архитектуры промптов

---

А. Несколько промптов — зачем и как

Смешиваются две разные потребности — их нельзя путать:

1. Версионирование одного промпта (ОБЯЗАТЕЛЬНО)

Это не «несколько промптов», а история эволюции одного.

Почему критично:

• prompt_version уже кладётся в spec_events (provenance, Opus раунд 2).
• Значит промпт обязан быть иммутабельным — правка «на месте» сломает трассировку: старые события будут ссылаться на текст, которого больше нет.
• Правка = новая версия, а не перезапись. Откат, аудит «какая версия породила какой результат», сравнение версий — бесплатно.

2. Несколько РАЗНЫХ промптов одновременно

Сценарий	Вердикт
По роли в пайплайне — разные LLM-вызовы (извлечение услуг vs сравнение vs резолв имён)	✅ У каждого свой промпт. Настоящая причина «несколько» — по задаче.
Варианты для эксперимента — форкнул активный, сделал строже, прогнал на тестах, сравнил	✅ Loop «дублировать → изменить → протестировать → активировать» — правильно.
Каталог из 20 промптов «на всякий случай»	❌ Ловушка. Для узкого домена (colocation/ЦОД) нужен ОДИН хороший промпт на задачу.

Рекомендуемая модель: prompt-as-version (не prompt-as-document)

Одна таблица, один активный на role, вся история — строки:

Поле	Тип	Смысл
id	UUID PK	Версия (иммутабельная)
role	VARCHAR	Шаг пайплайна: extract, diff
name	VARCHAR	Человеческое имя («default-v3», «strict-prices»)
body	TEXT	Тело промпта с плейсхолдерами
parent_id	UUID FK→prompts.id	От какой версии форкнут
is_active	BOOLEAN	UNIQUE(role, is_active) с частичным индексом WHERE is_active
created_at	TIMESTAMP
created_by	VARCHAR	Мульти-юзер
notes	TEXT	Что изменили и зачем

Операции:

• Править = INSERT новой строки с parent_id на предыдущую. Не UPDATE.
• Активировать = переключить is_active (старая теряет флаг).
• Дублировать = копия под новым name (форк).
• Откат = активировать старую версию.

Никогда не UPDATE текста на месте.

---

Б. Как составлять промпт

Стартовый шаблон — ОБЯЗАТЕЛЕН

Пустое поле ввода — катастрофа для качества. Всегда форкать от выверенного дефолта, не с нуля.

Структура (8 секций, порядок важен)

Для доменной задачи без structural output (gpt-oss-120b):

┌─────────────────────────────────────────────┐
│ 1. РОЛЬ / КОНТЕКСТ                          │
│    «ты эксперт по договорам colocation       │
│     и облачных услуг ЦОД»                    │
├─────────────────────────────────────────────┤
│ 2. ЗАДАЧА                                   │
│    «сравни текущую спецификацию с документом,│
│     верни операции изменений»                │
├─────────────────────────────────────────────┤
│ 3. ДОМЕННЫЙ ГЛОССАРИЙ                       │
│    стойко-место, кВт мощности, colocation,   │
│    единицы измерения, типы услуг.            │
│    Без этого модель путает домен.            │
├─────────────────────────────────────────────┤
│ 4. ФОРМАТ ВХОДА                             │
│    Как подаётся spec_current (с ID r1..rN),  │
│    как подаётся текст документа.             │
├─────────────────────────────────────────────┤
│ 5. КОНТРАКТ ВЫВОДА                          │
│    Строгая JSON-схема ops: поля, типы,       │
│    обязательность. КРИТИЧНО — structural     │
│    output нет, схема держится промптом.      │
├─────────────────────────────────────────────┤
│ 6. ПРАВИЛА / ОГРАНИЧЕНИЯ                    │
│    «ссылайся только на id из spec_current»,  │
│    «верни source_quote», «верни confidence», │
│    «name существующих строк не переписывай»  │
├─────────────────────────────────────────────┤
│ 7. FEW-SHOT ПРИМЕРЫ (2-3)                   │
│    ⭐ САМЫЙ МОЩНЫЙ РЫЧАГ для бесплатной      │
│    модели без fine-tune. Примеры учат и      │
│    формату, и поведению лучше инструкций.    │
│    Вход→Выход на ВАШЕМ домене (ЦОД).        │
├─────────────────────────────────────────────┤
│ 8. EDGE-CASES                               │
│    Как помечать неоднозначность, что делать  │
│    при low-confidence.                       │
└─────────────────────────────────────────────┘

Принцип разделения: статика vs рантайм

[версионируемая часть — в БД]     [рантайм-инъекция — в коде]
роль + глоссарий + правила     +  {spec_current} + {document_text}
+ few-shot + контракт вывода

• Статическая инструкция (секции 1-8) → версионируется в prompts.body.
• Динамические данные ({spec_current}, {document_text}, {date}) → подставляются в рантайме через плейсхолдеры.
• В БД хранится тело промпта с плейсхолдерами, не с конкретными данными.

---

В. Prompt CI — как с этим работать

 ┌──────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐
 │ Дублировать │ → │ Изменить  │ → │ Прогнать на │ → │ Активировать │
 │ (форк)     │    │ (новая v) │    │ golden-наборе│   │ (is_active) │
 └──────────┘    └──────────┘    └───────────┘    └──────────┘

1. Форкнуть активный промпт → новый id, is_active=false
2. Изменить тело
3. Прогнать на golden-наборе (3-5 реальных ДС с известным результатом)
4. Сравнить метрики (precision/recall по ops)
5. Если лучше — активировать. Если хуже — оставить как эксперимент или удалить.

---

Г. Текущее состояние (v1.0.109)

Промпты жёстко зашиты в llm_prompt.py:

• _build_initial() — для первого документа
• _build_diff() — для сравнения (основной)

Что уже хорошо:

• JSON-контракт вывода описан
• target_id (r1..rN) вместо target_hash
• Правила: mode full_replace, UPDATE только изменённые поля, UNRESOLVED для неоднозначного

Чего не хватает (по приоритету):

1. Few-shot примеры на домене ЦОД — самый большой рычаг качества
2. Доменный глоссарий — чтобы модель понимала единицы измерения и термины
3. source_quote в контракте вывода — для provenance
4. confidence в контракте вывода — самооценка модели
5. Edge-cases инструкция — как вести себя при неоднозначности

---

Д. План миграции (если делать)

Шаг	Что	Сложность
1	Таблица prompts в PostgreSQL (Lucee datasource baza)	Низкая
2	CRUD в api.cfm для prompts (list, get, create, set_active)	Средняя
3	llm_prompt.py → читает активный промпт из Lucee API вместо хардкода	Средняя
4	prompt_version в spec_events — ссылка на prompts.id	Низкая
5	UI для prompts в index.cfm (список версий, редактор, активация)	Высокая
6	Golden-набор: 3-5 ДС + эталонные ops	Ручная работа
7	Prompt CI: скрипт прогона на golden-наборе + сравнение метрик	Средняя

Первый практический шаг (максимум пользы, минимум кода): добавить few-shot примеры в текущие промпты прямо в llm_prompt.py, не дожидаясь таблицы prompts.