Документирование промпта

Документирование промпта

Ты написал промпт, протестировал, итеративно довёл до целевых метрик. Последний шаг перед production — документирование. Хорошая документация превращает твой промпт из «работает, но непонятно как» в production-артефакт, с которым могут работать другие.

Что документировать

Минимальный набор для production-промпта:

Шаблон документации

Для нашего промпта генерации описаний товаров:

---
prompt_id: product_description_generator
version: 3.0
date: 2026-04-30
author: @stepan
status: active
---

# Генератор описаний товаров

## Назначение
Генерирует короткое (3–5 предложений) описание товара для карточки
в интернет-магазине электроники. На вход получает характеристики товара,
на выходе — продающий текст на русском языке.

## Входные данные
Структурированный текст с полями:
- Название (обязательно)
- Бренд (опционально)
- Категория (опционально)
- Характеристики (опционально, произвольный текст)
- Цена (опционально)

## Выходные данные
Текст из 3–5 предложений на русском языке.

## Полный промпт
<role>
Ты — профессиональный копирайтер интернет-магазина электроники...
</role>
... (полный текст промпта)

## Примеры

### Пример 1 — богатый вход
Вход: ... (как в уроке 12.2)
Выход: ...

### Пример 2 — бедный вход
Вход: ...
Выход: ...

## Метрики (eval set: 10 товаров)
| Метрика | Значение | Цель |
|---------|---------|------|
| Точность (нет выдумок) | 100% | 100% |
| Полнота (фичи упомянуты) | 91% | ≥ 90% |
| Длина (3–5 предл.) | 90% | ≥ 90% |
| Средняя оценка тона | 4.2/5 | ≥ 4.0 |

## История версий
| Версия | Дата | Изменения | Точность |
|--------|------|-----------|---------|
| v1 | 2026-04-28 | Baseline: роль + инструкции + few-shot | 60% |
| v2 | 2026-04-29 | Добавлен список типичных галлюцинаций | 80% |
| v3 | 2026-04-30 | Самопроверка + правила для бедных входов | 100% |

## Ограничения
- Не работает с товарами вне категории «электроника» (стиль заточен
  под эту категорию).
- Требует хотя бы одного поля кроме «Название».
- Для товаров с одной характеристикой описание может быть короче 3
  предложений, но это допустимо.
- Промпт — генератор текста. Перед публикацией на сайте описания должны
  проверяться редактором (защита от галлюцинаций не 100%).

## Инструкция по использованию
1. Подготовь product_data в формате:
   Название: ...
   Бренд: ...
   ...
2. Вставь product_data в секцию <product_data> промпта.
3. Отправь промпт модели.
4. Проверь описание перед публикацией:
   - Все ли факты соответствуют входу?
   - 3–5 предложений?
   - Нет ли маркетинговых клише?

Документирование метрик

Метрики — это не просто цифры. Они должны отвечать на вопросы:

• На чём измерено? Eval set: 10 товаров из каталога электроники.
• Когда измерено? 2026-04-30, версия 3.0.
• Как измерено? Автоматическая проверка фактов + ручная оценка тона.
• Что означает «хорошо»? Целевые значения по каждому критерию.

Без этой информации цифры бесполезны — ты не знаешь, можно ли им доверять.

Куда сохранять

Документация живёт рядом с файлом промпта:

prompts/
  product_description/
    v1.0_2026-04-28.md     ← файл промпта
    v2.0_2026-04-29.md
    v3.0_2026-04-30.md     ← текущая версия
    eval_set.json           ← оценочный набор
    README.md               ← документация (шаблон выше)

Файл README.md — это сводный документ: метаданные, текущие метрики, история версий, примеры. Каждый файл версии (v3.0_2026-04-30.md) содержит ПОЛНЫЙ промпт и метаданные конкретно этой версии.

Типичная ошибка: «документация в голове»

Разработчик помнит, что промпт v3 использует самопроверку, а v2 — список запретов. Он помнит, почему выбрали именно такую структуру, и знает, что точность — 100%. А потом он уходит в отпуск или меняет проект.

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

Представь, что новый человек должен за 10 минут понять:

• Что делает этот промпт.
• Как его использовать.
• Какое качество ожидать.
• Куда смотреть, если что-то сломалось.

Проверь себя

Ты получил в наследство промпт для классификации обращений. Никакой документации нет — только файл с текстом промпта. Какие пять вопросов ты задашь автору? Что будешь выяснять через тестирование?

Итог

• Документирование превращает промпт из «поделки» в production-артефакт.
• Минимальный набор: метаданные, назначение, вход/выход, полный промпт, метрики, история версий, ограничения.
• Метрики без контекста (eval set, дата, метод измерения) — бесполезны.
• Храни документацию рядом с файлами версий промпта.
• Тест на качество: новый человек должен разобраться за 10 минут без устных пояснений.

Что дальше

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