workshop day 3 · hackathon
Hackathon — Active English Trainer
Два дня вы строили инфраструктуру: бот, БД, AI-интеграции. Сегодня — 6 часов на продукт. Никаких новых концепций, только применение того, что уже знаете. Это и есть хакатон.
Что такое хакатон (если вы здесь впервые)
Хакатон — это спринт, где команда за фиксированное время превращает идею в работающий прототип. Не идеальный продукт. Не «продакшн-качество». Прототип, который можно показать.
| Хакатон ≠ это | Хакатон = это |
|---|---|
| Написать «красивый» код | Написать **работающий** код |
| Покрыть всё тестами | Показать живое демо |
| Идеальный UI | Понятная демонстрация ценности |
| Сделать всё из брифа | Сделать MVP + 1 фичу-вау |
| Сидеть молча и думать | Спрашивать, гуглить, использовать AI |
Кейс: «Мёртвые слова»
Вы уже сделали словарь. Поздравляю — вы создали кладбище слов.
500 слов в базе. Ни одно не используется. Ты добавил ephemeral три месяца назад и с тех пор ни разу не вспомнил. ЕНТ или IELTS не спросит вас: «Сколько слов у тебя в таблице?» Он спросит, можете ли вы их использовать.
Цель дня: превратить пассивную БД из Day 2 в Active English Trainer — ИИ-репетитора, который вытаскивает слова из мёртвой базы в реальный контекст.
MVP Scope: две обязательные команды
Это минимум, чтобы участвовать в оценке. Без этих двух команд работающий бот не считается.
| Команда | Что делает | Главная техника | Сложность |
|---|---|---|---|
| `/speaking` | Берёт слова из словаря и заставляет юзера их использовать | SELECT random + AI вопрос + state machine | 🟢 средне |
| `/new_word` | AI предлагает новое слово, проверяет, добавляет в БД | SELECT last 50 + AI JSON + INSERT | 🟡 средне+ |
Фича 1: /speaking — активация словаря
Идея: пассивное знание становится активным только через применение. Бот заставляет юзера произнести (написать) фразу, в которой обязательно надо использовать слова из его собственного словаря.
Что должно произойти под капотом
Что нужно добавить в БД
alter table words
add column if not exists last_practiced_at timestamptz;
State machine — почему она нужна
После того как бот задал вопрос, следующее сообщение юзера — это не команда, а ответ на вопрос. Бот должен это понимать. Без state machine любое сообщение будет восприниматься как новый запрос.
Фича 2: /new_word — умное пополнение
Идея: обычные приложения дают случайные слова из топ-1000. У нас бот знает что юзер уже учил и предлагает только новое и полезное.
Что должно произойти под капотом
Bonus: дополнительные фичи (приветствуются)
MVP закрыт за 3 часа? Молодцы. Теперь делаем вау-фичу, которая запомнится жюри. Используем то, что уже умеем с Day 2 (Whisper, Vision) — или придумываем своё.
| Фича | Что использует | Идея |
|---|---|---|
| `/speaking` голосом | Whisper | Юзер отвечает voice message → транскрипция → та же проверка. Главное упражнение — **говорить вслух**, а не печатать. |
| `/photo_quiz` | Vision | Фото комнаты → AI находит 5 объектов → бот делает квиз → правильные ответы идут в словарь. |
| `/translate` | LLM | Юзер пишет фразу на русском → бот переводит и сохраняет в словарь все новые слова из перевода. |
| `/streak` | Только БД | Считает сколько дней подряд юзер делал хотя бы одну активность. Ничего AI-шного, но **сильно увеличивает retention**. |
| `/weekly_review` | SELECT + LLM | Раз в неделю бот показывает 10 слов, которые юзер давно не практиковал (`last_practiced_at < NOW() - 7 days`), и делает мини-квиз. |
| `/grammar_check` | LLM | Юзер пишет любой текст → бот находит **одну** главную ошибку и объясняет. Не больше одной — иначе перегруз. |
| `/role_play` | LLM + state | AI играет роль (официант, кассир, пограничник), юзер ведёт диалог на английском. Используются слова из словаря. |
Как подходить к работе (для тех, кто впервые)
Шаг 1: распределите роли (10 минут)
| Роль | Что делает |
|---|---|
| 🧠 Lead / архитектор | Держит общую картину, решает споры, следит за временем |
| 🛠️ Backend | Хендлеры grammY, session, state machine |
| 🗄️ Data / SQL | Миграции таблицы, запросы к Supabase |
| 🤖 AI / Prompts | Промпты, JSON-парсинг, обработка ответов модели |
В команде 2 человека? Один — Backend+Data, второй — AI+Lead. Распределяйте по сильным сторонам.
Шаг 2: нарисуйте state machine на бумаге (15 минут)
Шаг 3: пишите по одной команде целиком
Сделай /speaking от начала до конца — SELECT, OpenAI вызов, state, проверка ответа. Только потом начинай /new_word. Не пытайся писать обе команды параллельно — потеряешься.
Шаг 4: тестируйте каждые 15 минут в Telegram
Не пиши 200 строк и потом запускай. Пиши 30 строк → запускай → проверяй в живом боте → следующие 30 строк.
Как использовать AI (ChatGPT / Copilot / Cursor)
AI на хакатоне — это множитель, а не замена мозга. Если ты не понимаешь что просишь — AI выдаст красивый, но неправильный код.
| ❌ Плохой запрос к AI | ✅ Хороший запрос к AI |
|---|---|
| «сделай мне бота» | «У меня есть grammY-бот с session middleware. Напиши хендлер `bot.command('speaking', ...)`, который делает SELECT 5 случайных строк из таблицы words по user_id через мою функцию `dbSelect(...)`» |
| «не работает, помоги» | «Получаю TypeError: Cannot read property 'state' of undefined в этой строке: [код]. Что я упустил?» |
| «напиши промпт для английского» | «Напиши system prompt для OpenAI, который принимает массив из 5 английских слов уровня B2 и возвращает один вопрос на английском для 17-летнего казахстанского школьника, в котором обязательно нужно использовать все эти слова» |
Do и Don't — чек-лист хакатона
| ✅ Делай | ❌ Не делай |
|---|---|
| Закоммить рабочую версию каждый час | Не пушь только в конце — потеряешь всё |
| Сначала MVP, потом красота | Не начинай с дизайна сообщений |
| Тестируй в Telegram каждые 15 минут | Не пиши 2 часа без запуска |
| Спрашивай ментора, если стоишь >20 минут | Не сиди молча с багом 2 часа |
| Используй AI для бойлерплейта | Не доверяй AI промпты для AI |
| Подготовь демо-сценарий заранее | Не импровизируй на презентации |
| Закрой одну фичу полностью | Не делай 3 фичи на 60% каждая |
| Логируй ошибки (`console.error`) | Не глотай ошибки в `catch {}` |
Таймлайн на 6 часов
| Время | Этап | Цель |
|---|---|---|
| 09:00–09:30 | 🗺️ Planning | Прочитали бриф, поделили роли, нарисовали state machine |
| 09:30–11:00 | 🔧 `/speaking` | Полностью работающая команда, протестирована в Telegram |
| 11:00–12:30 | 🔧 `/new_word` | Полностью работающая команда + INSERT работает |
| 12:30–13:00 | 🍕 Обед | Без обеда нет продуктивности |
| 13:00–14:30 | 🧪 Polish + edge cases | Пустой словарь, кривой JSON, юзер пишет фигню — всё обработано |
| 14:30–15:30 | ⭐ Bonus-фича | Одна дополнительная команда, **только если MVP стабилен** |
| 15:30–15:45 | 🎤 Demo prep | Сценарий демо на 3 минуты, кто что говорит |
| 15:45–16:00 | 🏆 Презентации | Живой бот, не слайды |
Как мы будем оценивать
| Критерий | Вес | Что смотрим |
|---|---|---|
| Работа с БД | 20% | SELECT/INSERT/UPDATE корректны, нет дублей, `last_practiced_at` обновляется |
| Качество AI-промптов | 30% | Промпты дают стабильный результат, JSON парсится, нет «галлюцинаций» |
| UX в Telegram | 20% | State machine не ломается, edge cases обработаны, сообщения читаемы |
| Bonus-фича | 20% | Реально работает и интегрирована в логику, а не «кнопка для галочки» |
| Демо и питч | 10% | Понятная архитектура за 3 минуты, реальный сценарий, не тест-кейс |
Как делать демо за 3 минуты
- 30 секунд: что за бот, какую проблему решает («пассивный словарь — кладбище слов»)
- 90 секунд: живая демонстрация — открой Telegram, пройди сценарий:
/speaking→ ответ → фидбэк, потом/new_word→ ответ → INSERT - 30 секунд: покажи bonus-фичу
- 30 секунд: что было сложно технически, что узнали нового
Финальная установка
За два дня вы написали 400+ строк кода. Сегодня — день, когда из этого кода получается продукт, которым реально можно пользоваться перед IELTS.
Удачи. Кодите. Спрашивайте. Тестируйте.