ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Написать документацию промпта

1. Цель задачи

Научиться документировать промпт так, чтобы любой разработчик, data scientist или нетехнический участник команды мог за 5 минут понять его назначение, входные данные, ожидаемый вывод и известные ограничения. Создать единый стандарт описания промптов в проекте, который снизит время онбординга и поможет отлавливать регрессии при изменениях.

Ключевой результат Файл документации промпта в формате Markdown (или в Wiki компании), содержащий: заголовок, версию, описание, шаблон промпта, примеры input/output и раздел known issues, достаточный для самостоятельного использования новичком.

2. Исходные данные

Если нет реального промпта — симулируем:

1. Возьмите следующий промпт для примера (системный для суммаризации диалога поддержки):

   Ты — ассистент службы поддержки. Пользователь написал обращение.
   Извлеки из обращения: (1) тему, (2) эмоциональную тональность (positive/neutral/negative), (3) срочность (low/medium/high), (4) краткую суть в одном предложении.
   
   Обращение: {dialog_text}
   
   Ответь строго в формате JSON:
   {
     "topic": "...",
     "sentiment": "...",
     "urgency": "...",
     "summary": "..."
   }
   

2. Подготовьте 3–4 примера обращений с разной тональностью и срочностью.
3. Создайте пустой файл prompt_doc_template.md по образцу раздела 4.

3. Технологический стек

4. Этапы выполнения

Этап 1: Анализ промпта и сбор контекста (30 минут)

Действия

1. Определите имя и версию промпта
   Например: summary-assistant-v1.2

2. Выясните бизнес-контекст

   • Где используется промпт? (чат-бот, batch-обработка, …)
   • Кто использует результат? (операторы, аналитики, автоматическая классификация)
   • Какие ограничения по latency и cost? (максимум N токенов, используемая модель)

3. Запишите все переменные (placeholders), которые динамически подставляются в промпт.
   Для примера: {dialog_text}

4. Соберите минимум 3 успешных примера input + output (реальных или искусственных).

   • Пример 1: обычный запрос, нейтральный, средняя срочность.
   • Пример 2: негативная тональность, высокая срочность.
   • Пример 3: позитивная, низкая срочность.

5. Проверьте поведение на граничных случаях

   • Пустой {dialog_text} (или очень короткое сообщение)
   • Очень длинный диалог (превышение лимита контекстного окна)
   • Неанглийский язык (если модель только для английского)

Ожидаемый результат этапа Заполненный черновик разделов «Имя», «Версия», «Описание», «Входные переменные», «Примеры».

Этап 2: Написание раздела «Шаблон промпта» и «Параметры» (20 минут)

Действия

1. Вставьте точную копию промпта в блок кода (с плейсхолдерами как в production).
   Можно использовать {% raw %}...{% endraw %} в Jekyll/MkDocs, если нужно экранировать фигурные скобки.

2. Опишите каждый плейсхолдер в таблице:

   Параметр	Тип	Описание	Пример
   {dialog_text}	string	Текст обращения пользователя (не более 2000 токенов)	"Здравствуйте, не могу войти в личный кабинет, пишет ошибку 401."

3. Добавьте параметры вызова LLM (если они не зашиты в код):

   • model: gpt-4o
   • temperature: 0.0
   • max_tokens: 150
   • response_format: json_object

Ожидаемый результат этапа Полный раздел «Шаблон промпта» с пояснениями.

Этап 3: Написание раздела «Ожидаемый вывод» и «Примеры» (30 минут)

Действия

1. Опишите структуру ответа (JSON схема для наглядности):

   {
     "type": "object",
     "properties": {
       "topic": {"type": "string", "description": "Тема обращения на русском, не более 10 слов"},
       "sentiment": {"type": "string", "enum": ["positive", "neutral", "negative"]},
       "urgency":   {"type": "string", "enum": ["low", "medium", "high"]},
       "summary":   {"type": "string", "description": "Суть одним предложением до 20 слов"}
     },
     "required": ["topic", "sentiment", "urgency", "summary"]
   }
   

2. Приведите 3 примера в форме таблицы:

   Input (dialog_text)	Output (ожидаемый JSON)
   "Спасибо за быстрый ответ, всё заработало!"	{"topic": "Благодарность", "sentiment": "positive", "urgency": "low", "summary": "Пользователь благодарит за помощь, проблема решена."}
   "Уже час не могу оплатить заказ. Код ошибки 500. Срочно!"	{"topic": "Ошибка оплаты", "sentiment": "negative", "urgency": "high", "summary": "Пользователь не может оплатить заказ из-за ошибки 500, требуется срочное вмешательство."}
   "Подскажите, работает ли доставка в выходные?"	{"topic": "Условия доставки", "sentiment": "neutral", "urgency": "low", "summary": "Пользователь интересуется возможностью доставки в выходные дни."}

Ожидаемый результат этапа Раздел «Ожидаемый вывод» с JSON-схемой и таблица примеров.

Этап 4: Раздел «Известные проблемы (Known Issues)» и «Правила обновления» (20 минут)

Действия

1. Перечислите все известные баги и ограничения, которые вы обнаружили при тестировании.
   Для примера:

   • Если {dialog_text} короче 5 символов, модель может вернуть "topic": "Неизвестно".
   • При очень длинном диалоге (> 1500 токенов) модель иногда обрезает summary.
   • Неанглийские эмоции (например, «отлично») могут не попасть в sentiment.

2. Опишите, как вносить изменения в промпт:

   • Версионирование через Git tag (например, prompt/summary-assistant/v1.3).
   • Перед изменением обязательно обновить документацию.
   • Добавить changelog в начало файла.

3. Добавьте секцию «Changelog» с последними тремя изменениями:

   Версия	Дата	Изменение
   v1.2	2025-02-10	Добавлен параметр urgency
   v1.1	2025-01-15	Исправлен баг: при пустом input возвращается fallback JSON

Ожидаемый результат этапа Раздел известных проблем и правила обновления.

Этап 5: Ревью и финализация (30 минут)

Действия

1. Прочитайте документацию вслух от лица новичка. Засеките 5 минут – понимает ли он задачу?
2. Попросите коллегу (или ChatGPT) проверить на:
   • Полноту (все ли входные параметры описаны)
   • Понятность (нет ли неоднозначных формулировок)
   • Соответствие фактическому поведению промпта (запустите примеры)
3. Исправьте замечания и зафиксируйте версию документа (например, docs/prompts/summary-assistant.md).
4. Запушьте в репозиторий или опубликуйте в Wiki.

Ожидаемый результат этапа Готовый файл документации, прошедший ревью.

5. Критерии приемки (Definition of Done)

• Файл документации создан в docs/prompts/ или эквивалентном месте.
• Содержит YAML frontmatter с полями: name, version, author, created.
• Описана цель промпта (2-3 предложения) и бизнес-контекст.
• Приведён полный шаблон промпта в блоке кода с пояснением плейсхолдеров.
• Указана JSON-схема или структура ответа.
• Есть минимум 3 примера input → output в таблице.
• Есть раздел «Known Issues» с ограничениями.
• Есть changelog с последними изменениями.
• Время на прочтение новичком ≤ 5 минут (проверено по таймеру).
• Документация прошла ревью хотя бы одного разработчика (галочка или комментарий в PR).

6. Ожидаемый результат

Готовый файл документации промпта (например, summary-assistant.md) со следующим содержанием:

• Frontmatter (YAML): имя, версия, автор, дата создания.
• Раздел «Описание»: коротко о том, что делает промпт.
• Раздел «Шаблон промпта»: точный код с плейсхолдерами.
• Раздел «Входные параметры»: таблица с типами и ограничениями.
• Раздел «Параметры модели»: model, temperature, max_tokens.
• Раздел «Ожидаемый вывод»: JSON-схема.
• Раздел «Примеры»: таблица 3+ примеров.
• Раздел «Known Issues»: список ограничений.
• Раздел «Changelog»: история изменений.
• Раздел «Руководство по обновлению»: правила версионирования.

Дополнительные опциональные артефакты

• Автоматизированные тесты (promptfoo) для примеров.
• Интеграция документации в центральную Wiki (MkDocs, Notion).

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание При наличии готового шаблона и знакомстве с промптом время сокращается до 1–1,5 часов.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я описал бизнес-цель промпта так, что её поймёт нетехнический коллега.
• Я указал все переменные, которые подставляются в промпт, с примерами.
• Я привёл не менее трёх примеров input → output.
• Я явно перечислил ограничения (known issues) и не замолчал о проблемах.
• Я проверил, что документация читается за 5 минут (или меньше).