Как писать мини-ТЗ

для задачи, которую жалко переделывать

Что это

Мини-ТЗ — это третий уровень детализации из статьи 3.3, расписанный полностью. Нужен там, где задача трогает несколько файлов, меняет структуру данных или плохо откатывается.

Это те же четыре части запроса (статья 3.2), просто развёрнутые. Ничего нового учить не надо — надо аккуратно заполнить то, что обычно держат в голове.

Как выглядит в коде

Структура

Задача        одна фраза: что должно появиться
Зачем         какую проблему решаем
Контекст      как устроено сейчас, что уже есть
Что сделать   по пунктам, в порядке выполнения
Ограничения   чего не делать, что не трогать
Готово, когда проверяемые условия списком
Вне задачи    что сознательно не делаем сейчас

Два раздела из семи обычно пропускают, а они самые полезные.

«Зачем» даёт ИИ возможность предложить решение лучше твоего. Если он знает только что делать, он сделает буквально; если знает зачем — может сказать «это решается проще вот так».

«Вне задачи» ограничивает аппетит. Без него ИИ достраивает задачу до «правильной»: попросил кеш — получил кеш с инвалидацией, метриками и настройкой через конфиг.

Пример целиком

Задача: перенести хранение подписок из JSON-файла в SQLite.

Зачем: при 300+ подписках файл перезаписывается целиком на каждое
изменение, бот на секунду подвисает. Плюс при сбое во время
записи файл бьётся.

Контекст: подписки в data/subs.json, структура
{user_id: [city, ...]}. Читаются load_subs(), пишутся save_subs(),
обе в storage.py. Вызовов — пять, все в handlers/.
SQLite в проекте уже используется для логов, подключение
через get_conn() в db.py.

Что сделать:
1. Таблица subscriptions: user_id INTEGER, city TEXT,
   created_at TEXT. Уникальность по паре (user_id, city).
2. Переписать load_subs/save_subs на SQLite.
   Сигнатуры и возвращаемые типы не менять.
3. Миграция при старте: если есть data/subs.json и таблица
   пуста — перенести данные, файл переименовать в subs.json.bak.

Ограничения:
- только модуль sqlite3/aiosqlite, без ORM
- хендлеры не трогать вообще
- формат логов не менять

Готово, когда:
- на пустой базе бот стартует без ошибок
- подписки из старого JSON видны после перезапуска
- все пять мест вызова работают без правок
- повторный старт не дублирует данные

Вне задачи: индексы, оптимизация запросов, перенос логов,
админские команды для просмотра подписок.

Двадцать пять строк — и задача, которую иначе переделывали бы трижды, делается с первого раза.

Как сказать ИИ

Сколько времени это занимает

Десять-пятнадцать минут. Окупается на первой же развилке, которую ИИ иначе закрыл бы сам.

Если на мини-ТЗ уходит час — задача слишком большая. Разбей её на две и напиши ТЗ на первую.

Хорошее сочетание

Мини-ТЗ + план (статья 3.10) — самая надёжная связка для крупной задачи:

<мини-ТЗ>

Код пока не пиши. Распиши планом, как будешь это делать,
и скажи, где в моём ТЗ не хватает информации.

Вторая фраза ценна: ИИ укажет дыры в твоём ТЗ до того, как они превратятся в неверный код.

Когда мини-ТЗ не нужно

На всём, что откатывается одной командой. Мини-ТЗ на добавление функции — это бюрократия, а не аккуратность.

На что смотреть

«Готово, когда» написано прилагательными. «Работает стабильно», «быстро», «удобно» — это не критерии. Если условие нельзя проверить, оно ничего не ограничивает (статья 3.2).

Раздел «Контекст» пересказывает код. Не надо переписывать туда функции — достаточно сказать, где смотреть. ИИ прочитает сам, если у него есть доступ к проекту.

ТЗ есть, а результат не сверили. Главная ценность ТЗ проявляется в конце: пройди по списку «Готово, когда» и отметь каждый пункт. Это две минуты и единственный способ узнать, сделано ли.

Задача выросла по ходу дела. Появились пункты, которых не было, — это не повод дописывать ТЗ на ходу. Доделай текущее, потом поставь вторую задачу.

Шпаргалка