Clarify prompt

Clarify Prompt

Трансформация сырых, нечётких описаний задач в чистые, структурированные промты, которые AI-агент может выполнить без догадок и переспрашиваний.

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

Люди описывают задачи так, как думают: с отступлениями, пропусками, неявными допущениями и «ты ж понимаешь». AI-агент этого не понимает. Этот скилл — мост между человеческим описанием и машинной инструкцией.

5 принципов трансформации

1. Каждое неявное допущение — явная инструкция

Если человек пишет «ну ты знаешь где это» — агент не знает. Превращай подразумеваемое в прямое указание или инструкцию найти самостоятельно. Пример: «точное наименование не помню, посмотри в коде» → «Перед началом: открой код шаблона, найди точные имена полей, используй реальные имена из кода, а не предположения».

2. Разделяй контекст, задачу и ожидаемый результат

Три блока, всегда разделённые:

• Контекст — что уже есть, как устроена система, откуда данные
• Задача — что конкретно нужно сделать (пронумерованные шаги)
• Ожидаемый результат — как выглядит итог, включая edge-cases

3. Устраняй неоднозначность

Каждое предложение должно иметь одну интерпретацию. Сигналы неоднозначности:

• «возможно», «вроде», «наверное», «может быть» → конкретика или инструкция «проверь и определи сам»
• «и т.д.», «и прочее», «что-то такое» → перечислить явно или убрать
• «нормально», «красиво», «хорошо» → описать конкретные критерии

4. Добавляй граничные случаи

Человек описывает happy path. Промт должен описывать и edge cases: что делать если данных нет? если данные невалидны? какие ограничения области действия?

5. Давай агенту предварительные шаги

Если задача требует изучения кодовой базы, данных или документации — добавь явный шаг «сначала изучи X, найди Y, и только потом приступай».

Порядок работы

Шаг 1. Анализ входного текста. Выдели: ядро задачи (одно предложение), контекст системы, пробелы (что подразумевается, но не сказано), неоднозначности, отсутствующие edge-cases.

Шаг 2. Уточнение (если необходимо). Если пробелы критичны для качества промта — задай уточняющие вопросы, не больше 3-5 за раз. Если пробелы некритичны или агент может заполнить их в процессе — не спрашивай, а добавь в промт инструкцию «определи самостоятельно из кода/данных». Не блокируй пользователя вопросами там, где можно дать агенту инструкцию разобраться.

Шаг 3. Формирование промта по структуре ниже.

Шаг 4. Самопроверка по чек-листу ниже.

Шаблон структуры промта

## Задача: [краткое название в 3-7 слов]

### Контекст
[Система, сущности, источники данных. Всё что нужно знать ДО работы.]

### Предварительные шаги
[Что агент должен изучить/найти/проверить перед началом.
Только если задача требует предварительного исследования.]

### Что нужно сделать
[Пронумерованные шаги. Каждый шаг — одно конкретное действие.]

### Ожидаемый результат
[Как выглядит финал: элементы UI, поля, форматы данных.]

### Граничные случаи
[Что делать при пустых данных, ошибках, нетипичных ситуациях.]

### Ограничения
[Область действия, что НЕ нужно трогать, технические рамки.]

Не все блоки обязательны. Используй только нужные для конкретной задачи. Для простых задач хватит «Контекст» + «Что нужно сделать».

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

• Каждое предложение имеет одну интерпретацию?
• Нет слов «вроде», «возможно», «наверное», «и т.д.»?
• Контекст отделён от задачи?
• Шаги пронумерованы и атомарны (одно действие = один шаг)?
• Описаны граничные случаи (пустые данные, ошибки)?
• Если нужно исследовать код/данные — есть явный предварительный шаг?
• Промт не содержит лишней информации, не относящейся к задаче?
• Язык промта совпадает с языком исходного текста пользователя?

Адаптация под контекст

• Задача на английском → выдавай промт на английском. Структура та же, заголовки: Context, Prerequisites, Steps, Expected Result, Edge Cases, Constraints.
• Задача не про код (тексты, анализ данных, исследования, дизайн) → структура адаптируется: вместо «предварительных шагов» может быть «источники», вместо «граничных случаев» — «ограничения и исключения».
• Пользователь просит «просто улучшить» → не переспрашивай «а что именно». Применяй все 5 принципов, покажи результат. Если нашёл критичные пробелы — укажи их после промта блоком «Вопросы для уточнения (необязательно)».

Развёрнутые примеры

Два полных примера трансформации (задача с неявным контекстом, задача с размытыми требованиями) — в references/examples.md. Читай их когда нужен образец готового промта по этой методике.