Модуль 03 — Спека и промпт

Время: 5 часов · Формат: теория 100 мин + практика 200 мин

Теория

1. Промпт — это не просьба, а спецификация

Разница между «сделай красиво» и «сделай так» — в наличии проверяемых критериев.

Задача без спеки:   "добавь авторизацию"
Задача со спекой:   "эндпоинт POST /login, принимает {email, password},
                     возвращает 200 {token} или 401 {error},
                     пароль хэшируется bcrypt, токен живёт 24ч,
                     тесты: валидный вход, неверный пароль, отсутствующий email"

Второе можно проверить. Первое — только «на глаз».

2. Анатомия спеки

Минимальная рабочая спека — 6 блоков:

## Контекст
Что уже есть, где это лежит, что нельзя ломать.

## Цель
Одно предложение: что должно появиться.

## Требования
Пронумерованный список проверяемых утверждений.

## Ограничения
Что запрещено: зависимости, файлы, паттерны, стиль.

## Критерии приёмки
Конкретные проверки: команды, тесты, сценарии.

## Не входит в задачу
Явное «мы этого не делаем» — защита от расползания.

Блок «не входит» экономит больше всего: агент любит «улучшить заодно».

3. Формулировки, которые работают

Работает	Не работает
«функция `parse_date(s: str) -> date`»	«функция для дат»
«вернуть `None`, если не распарсилось»	«обработать ошибки»
«как в `services/billing.py`»	«в нашем стиле»
«не более 50 строк»	«компактно»
«сначала план, код не писать»	«сделай хорошо»

Правило: каждое прилагательное замените на проверяемое условие.

4. Plan-first: самый дешёвый приём

Попросите план до кода:

Не пиши код. Составь план: какие файлы затронешь, какие функции добавишь,
как проверим. Укажи риски и то, что может сломаться.

Что это даёт:

ошибки в понимании видны за 30 секунд, а не за 300 строк;
план можно поправить словами;
план становится чек-листом приёмки;
экономится контекст.

Плохой план — повод переформулировать задачу, а не «объяснять модели, что она неправа».

5. Декомпозиция

Большая задача → цепочка проверяемых шагов:

1. Добавить модель данных + миграцию
2. Добавить слой доступа
3. Добавить эндпоинт + тесты
4. Подключить к UI
5. Убрать старый код

Каждый шаг: свой дифф, свой коммит, зелёные тесты. Так ошибка локализуется в одном шаге, а не «где-то в 800 строках».

6. Примеры (few-shot) и формат

Хотите конкретный стиль — дайте один пример готового кода. Модель копирует структуру надёжнее, чем понимает описание.

Хотите конкретный формат ответа — скажите явно: «только дифф», «только файл X», «таблица», «без объяснений».

7. Чего избегать

Двойные требования: «сделай быстро и качественно».
Скрытые требования: «ну ты понял» → модель поняла по-своему.
Задачи-монстры: 5 целей в одном запросе.
Просьбы «перепиши всё»: нечего проверять, всё ломается сразу.

8. Промпт как артефакт

Хорошая спека живёт дольше сессии: её можно положить в docs/specs/, обсудить в ревью, переиспользовать. Промпт, который «сработал», — это актив проекта, а не мусор в истории.

Чек-лист понимания

Чем спека отличается от просьбы? Назовите признак.
Зачем блок «не входит в задачу»?
Почему plan-first дешевле, чем сразу код?
Что делать, если план плохой — и чего делать нельзя?

Практика

См. practice.md.