Перевод с разбором · для Вани

Чётко и прямо

Зачем тебе это нужно

На задачах со строгой структурой (парсинг заявок, формирование сметы, расчёт прибыли) расплывчатый промпт — главный враг качества. Если модель получит «распознай заявку» — она иногда вернёт JSON, иногда список, иногда «я не уверена, уточните». Если получит «распознай и верни JSON по схеме X» — поведение станет предсказуемым. Это базовое правило: чем точнее инструкция, тем стабильнее результат.

Главная идея

LLM хорошо слушаются чётких, явных инструкций. Моделируй запрос как спецификацию задачи: вход, желаемый выход, формат, ограничения. Как API-контракт.

Золотое правило. Покажи промпт коллеге без контекста и попроси выполнить. Растеряется он — растеряется и модель.

Практические приёмы

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

Пример: парсинг заявки на лестницу

Менее эффективно:

Разбери эту заявку и верни данные.

Что здесь происходит: формат не задан. Одна модель вернёт JSON, другая — прозу, третья — сокращённый список.

Более эффективно:

Ты парсер заявок на деревянные лестницы для частных домов.

Верни JSON со следующими полями:
- customer_name (строка)
- address (строка или null)
- floors (число этажей, 2 или 3)
- wood_type (oak | pine | ash | unknown)
- approx_run_length_mm (число или null) — приблизительная длина марша
- notes (строка) — всё остальное, что клиент упомянул

Если поле не упомянуто — ставь null (или unknown для wood_type).
Не выдумывай значения. Не добавляй лишних полей.

Заявка клиента:
«Здравствуйте! Нужна лестница на второй этаж, дубовая. Адрес — Мирный, Лесная 12.
Примерно 3 метра. Звоните Ивану +7...»

Что здесь происходит: задана роль, схема выхода с типами, поведение при отсутствии данных, явный запрет выдумывать. Теперь модель не может промахнуться по формату, а твой Kotlin-код спокойно парсит результат в data class через kotlinx.serialization.

Добавляй контекст — зачем это

Если ты объясняешь почему правило важно — модель лучше обобщает на соседние ситуации:

Никогда не округляй длину марша. Мы работаем в миллиметрах, ошибка в
10 мм даёт заметный косяк на месте.

— лучше, чем просто «не округляй». Теперь модель сама сохранит точность и в других местах (ширина проступи, высота подступёнка).

Говори, что делать, а не чего не делать

Вместо «не используй markdown в JSON» — «верни только валидный JSON, без обёртки в ```json```, без комментариев». Дай модели цель, а не только стенки.

Что это значит для твоей системы

• Для каждого промпта заведи отдельный файл (src/main/resources/prompts/parse_order.txt). Версионирование в git.
• Явно описывай схему JSON в тексте промпта. Для надёжности включай structured outputs на стороне API (см. статью про XML и структурированные выходы).
• Не оставляй формат свободным. Каждое поле — тип, значения по умолчанию, поведение при отсутствии данных.
• Вместе с промптом заводи test-файл с 10–20 реальными заявками и ожидаемыми выходами. Прогоняй при каждой правке.

Полная версия — в docs/be-clear-and-direct.html.