Документирование и передача знаний

Структура документации промпта

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

Минимальный набор метаданных:

---
id: customer_ticket_classifier_v2
title: "Классификация обращений в поддержку"
author: ivan.petrov
created: 2024-01-10
last_tested: 2024-02-15
model: gigachat-pro
status: production
---

## Описание
Классифицирует обращения клиентов по категориям и приоритету для автоматической маршрутизации.

## Use cases
✅ Первичная сортировка тикетов
✅ Определение срочности обращения
✅ Маршрутизация к специализированным командам

❌ НЕ использовать для:
- Обращений на иностранных языках (точность может снижаться)
- Технических логов без контекста
- Обращений с несколькими несвязанными вопросами

## Входные параметры
- `ticket_text` (string, required): текст обращения, 10-2000 символов
- `customer_tier` (enum, optional): ["basic", "premium", "enterprise"]
- `previous_category` (string, optional): категория предыдущего обращения этого клиента

## Выходной формат
JSON с полями:
- `category`: одна из [billing, technical, feature_request, complaint, other]
- `priority`: [low, medium, high, critical]
- `confidence`: float 0-1
- `reasoning`: краткое объяснение классификации

## Примеры

### Пример 1: Технический вопрос
**Вход:**
```json
{
  "ticket_text": "Не могу войти в личный кабинет, пишет 'неверный пароль', хотя точно правильный",
  "customer_tier": "premium"
}

Выход:

{
  "category": "technical",
  "priority": "high",
  "confidence": 0.95,
  "reasoning": "Проблема с доступом к аккаунту, блокирует работу, премиум-клиент"
}

Пример 2: Запрос функции

Вход:

{
  "ticket_text": "Было бы здорово добавить экспорт в Excel"
}

Выход:

{
  "category": "feature_request",
  "priority": "low",
  "confidence": 0.89,
  "reasoning": "Предложение новой функциональности, не блокирует текущую работу"
}

Known issues и workarounds

Issue #1: Смешанные обращения (жалоба + технический вопрос) - Проявление: Низкая confidence (<0.7), непредсказуемая категория - Workaround: Добавить в промпт инструкцию выбирать категорию по основной проблеме

Issue #2: Сарказм и негативная тональность - Проявление: "Отличная работа, уже неделю жду ответа" → category: complaint, но confidence может быть ниже - Workaround: Добавлен анализ контекста и временных упоминаний

Issue #3: Аббревиатуры и жаргон - Проявление: "ЛК не открывается" может быть не распознан как технический вопрос - Workaround: Добавлен словарь распространённых аббревиатур в системный промпт

Рекомендуемые параметры

{
    "temperature": 0.2,  # Низкая для стабильной классификации
    "top_p": 0.8,
    "max_tokens": 200
}

## Best practices для команды

**1. Шаблон для документирования находок:**

```markdown
## Prompt Discovery Log

**Дата**: 2024-02-20
**Автор**: maria.ivanova
**Задача**: Генерация описаний товаров для маркетплейса

### Что пробовали
1. Базовый промпт: "Напиши описание товара {name}"
   - Результат: Слишком общие описания, нет SEO-оптимизации
   - Оценка: 3/10

2. С примерами (few-shot):
   - Результат: Лучше, но не адаптируется к категории товара
   - Оценка: 6/10

3. С ролью + структурой + примерами:
   - Результат: Качественные описания, учитывает категорию
   - Оценка: 9/10
   - **→ Кандидат в библиотеку**

### Финальный промпт
[Полный текст промпта]

### Метрики
- Время генерации: ~2-3s
- Средняя длина: ~450 символов
- Acceptance rate: высокий (большинство описаний одобрены без правок)

### Следующие шаги
- [ ] Оформить как шаблон
- [ ] Протестировать на разных категориях
- [ ] Добавить в библиотеку после review

2. Формат для передачи контекста:

При передаче промпта коллеге или другой команде, используйте структуру:

## Quick Start

**Что делает**: [одно предложение]
**Когда использовать**: [конкретный сценарий]
**Как запустить**: [минимальный пример кода]

## Детали
[Полная документация]

Это позволяет быстро оценить релевантность, не погружаясь в детали.

3. Документирование edge cases:

Вместо общих фраз "может работать нестабильно" документируйте конкретные случаи:

## Edge Cases

| Ситуация | Поведение | Рекомендация |
|----------|-----------|--------------|
| Входной текст <10 слов | Confidence может быть низким | Отклонить, попросить уточнить |
| Текст >2000 символов | Обрезается, теряется контекст | Разбить на части или суммаризовать |
| Эмодзи и спецсимволы | Обычно игнорируются | Можно не очищать |
| Смешанный язык (рус+англ) | Обычно работает нормально | OK для технических терминов |

4. Связывание с метриками продукта:

## Impact Metrics

**До внедрения промпта:**
- Время обработки тикета: ручная сортировка
- Ошибки маршрутизации: присутствовали

**После внедрения:**
- Время обработки: автоматическая классификация
- Ошибки маршрутизации: снижены
- Экономия времени: значительная

**Мониторинг:**
- Dashboard: [ссылка на систему мониторинга]
- Alerts: confidence <0.7 → ручная проверка

Ускорение разработки через переиспользование

Паттерн "Композиция из проверенных блоков":

# building_blocks.py
class PromptLibrary:
    ROLES = {
        "analyst": "Ты — аналитик с опытом {domain}",
        "editor": "Ты — редактор, специализирующийся на {style}",
    }

    CONSTRAINTS = {
        "factual": "Используй только фактическую информацию, не додумывай.",
        "concise": "Будь краток, максимум {max_words} слов.",
        "structured": "Структурируй ответ по пунктам.",
    }

    OUTPUT_FORMATS = {
        "json": "Ответ в JSON:\n{schema}",
        "markdown": "Ответ в Markdown с заголовками.",
    }

    @staticmethod
    def compose(role_key, task, constraints_keys, output_key, **params):
        role = PromptLibrary.ROLES[role_key].format(**params)
        constraints = "\n".join([
            PromptLibrary.CONSTRAINTS[k].format(**params) 
            for k in constraints_keys
        ])
        output = PromptLibrary.OUTPUT_FORMATS[output_key].format(**params)

        return f"{role}\n\n{task}\n\nТребования:\n{constraints}\n\n{output}"

# Использование
prompt = PromptLibrary.compose(
    role_key="analyst",
    task="Проанализируй отзывы и выдели ключевые проблемы",
    constraints_keys=["factual", "structured"],
    output_key="json",
    domain="e-commerce",
    schema='{"problems": ["..."]}'
)

Такой подход сокращает время создания нового промпта.

Документация промпта — это не формальность, а инструмент масштабирования. Хорошо документированный промпт содержит: чёткие границы применимости (use cases + anti-patterns), конкретные примеры входов/выходов, known issues с workarounds, и связь с бизнес-метриками. Стандартизированный формат документации + процесс логирования находок превращают индивидуальный опыт в командное знание, ускоряя разработку новых решений через композицию проверенных блоков.