Нейросеть для создания Telegram-бота — это ИИ-агент для кода: Cursor, Claude Code или другой. Он пишет бота в вашем проекте, а вы ставите задачу и проверяете результат. Важно не путать два разных бота:
- бот, написанный нейросетью, — обычный бот с командами и кнопками, код которого написал агент. Этому посвящена страница;
- бот с нейросетью внутри — бот, который отправляет сообщения пользователя языковой модели и пересылает её ответы. Его тоже можно написать с агентом, коротко об этом — в конце страницы.
Пример ниже — бот студии йоги: показывает расписание и принимает заявки на занятия. Он продолжает пример с сайтом студии, но подойдёт как образец для любого бота с командами и короткой анкетой.
Что понадобится#
- Токен бота. Откройте в Telegram @BotFather, отправьте команду
/newbotи следуйте подсказкам: в конце BotFather выдаст токен. Документация Telegram просит обращаться с ним как с паролем и никому не показывать. - Python 3.10 или новее. Этого требует aiogram 3 — асинхронная библиотека для Telegram Bot API на Python. На 12 октября 2026 года актуальная версия в документации — 3.31.0.
- ИИ-агент для кода. Факты о каждом — в каталоге инструментов, чем можно пользоваться бесплатно — в подборке бесплатные нейросети для программирования.
- Где запускать. Для разработки хватит своего компьютера, для постоянной работы нужен сервер. Об этом — в шаге 6.
Почему aiogram 3, а не другая библиотека? Ограничения нет: на Python популярна и python-telegram-bot, на JavaScript и TypeScript — grammY. Важно выбрать одну и указать её в ТЗ и AGENTS.md. Иначе агент может смешать примеры из разных библиотек или из старой версии aiogram 2, код которой с третьей версией несовместим.
Шаг 1. ТЗ бота#
ТЗ бота описывает команды, сценарии по шагам, данные и то, чего бот не делает. Скопируйте и замените под свою задачу.
Цель: Telegram-бот студии йоги. Показывает расписание и принимает заявки
на пробное занятие, заявки приходят администратору в Telegram.
Команды:
- /start — приветствие и две кнопки: «Расписание» и «Записаться»;
- /schedule — расписание на неделю из файла данных;
- /cancel — прервать запись на любом шаге.
Сценарий записи:
1. Бот спрашивает имя.
2. Бот показывает кнопки с занятиями из расписания.
3. Бот просит телефон (кнопка «Отправить номер» или ввод вручную).
4. Бот показывает итог и кнопки «Подтвердить» / «Изменить».
5. После подтверждения бот отправляет заявку в чат администратора
и отвечает пользователю: «Заявка отправлена, вам позвонят».
Что не входит:
- оплата, база данных, личный кабинет;
- рассылки;
- ответы нейросети на произвольные вопросы.
Технические требования:
- Python 3.10+, aiogram 3, получение сообщений через polling;
- расписание в файле data/schedule.json, чтобы его можно было менять без кода;
- токен и ID чата администратора — только в .env.
Готово, когда:
- бот запускается командой python bot.py без ошибок;
- /start, /schedule и /cancel отвечают;
- тестовая заявка приходит в чат администратора со всеми полями;
- на любом шаге записи /cancel возвращает к началу;
- в коде и репозитории нет токена.
Почему так:
- Сценарий по шагам — главная часть ТЗ бота. Агент реализует ровно эти шаги, а не придумывает свою анкету.
/cancelна любом шаге — частая забытая мелочь. Без неё пользователь застревает в середине анкеты.- «Ответы нейросети» в списке «не входит» — иначе агент может решить, что «бот с ИИ» значит подключить модель.
Как устроен шаблон ТЗ и зачем каждый раздел — на странице ТЗ для нейросети.
Шаг 2. AGENTS.md для бота#
ТЗ описывает, что сделать. AGENTS.md описывает, как работать в этом проекте всегда. Положите файл в корень проекта: его читают Cursor, Codex, Claude Code (если в проекте нет CLAUDE.md) и другие агенты.
# AGENTS.md
## О проекте
Telegram-бот студии йоги: расписание и запись на пробное занятие.
Python 3.10+, aiogram 3, polling.
## Команды
- Окружение: python -m venv .venv и активировать его
- Зависимости: pip install -r requirements.txt
- Запуск: python bot.py
## Структура
- bot.py — запуск: Bot, Dispatcher, подключение роутеров, start_polling
- handlers/ — один файл на тему: start.py, schedule.py, signup.py
- states.py — состояния анкеты записи (aiogram FSM)
- data/schedule.json — расписание, бот только читает его
- config.py — чтение настроек из окружения
## Правила
- Только aiogram 3. Не используй примеры и синтаксис aiogram 2.
- Обработчики подключай через Router, новый обработчик — в своём файле.
- Не меняй polling на вебхук без моей просьбы.
- Новые зависимости — только с объяснением и в requirements.txt.
## Секреты
- Токен только в .env, переменная BOT_TOKEN. ID чата администратора — ADMIN_CHAT_ID.
- .env в .gitignore. Проверь это перед любым коммитом.
- Не выводи токен в лог и в ответы.
## Перед тем как сказать «готово»
- python bot.py запускается без ошибок.
- Опиши, какие команды отправить боту, чтобы проверить изменение.
- Перечисли изменённые файлы.
Чем этот файл отличается от общего примера на странице AGENTS.md: в нём есть структура конкретного бота (FSM, файл расписания, ID администратора) и проверка, которую можно выполнить в чате с ботом.
Шаг 3. Промты для Telegram-бота по шагам#
Не просите «сделай бота» одним промтом. Четыре шага дают точки проверки.
3.1. План. Включите режим плана (в Cursor и в Claude Code — Shift+Tab) и отдайте ТЗ:
Прочитай ТЗ в @docs/spec.md и AGENTS.md. Код пока не пиши.
Задай вопросы по всему, что неясно. Потом предложи план:
какие файлы создашь и в каком порядке, у каждого шага — как я проверю результат.
3.2. Каркас и /start.
Шаг 1 плана: создай структуру проекта, requirements.txt, config.py,
.env.example без настоящих значений и обработчик /start с двумя кнопками.
Проверь, что .env есть в .gitignore. Скажи, какую команду отправить боту для проверки.
3.3. Расписание и запись.
Шаг 2 плана: /schedule читает data/schedule.json. Затем анкета записи
по сценарию из ТЗ на aiogram FSM, с /cancel на любом шаге.
Заявку отправляй в чат ADMIN_CHAT_ID из .env. Других функций не добавляй.
Перечисли сценарии, которые мне нужно пройти в чате с ботом.
3.4. Ошибки и логи.
Добавь логирование: запуск бота, ошибки в обработчиках, отправка заявки.
Токен и телефоны в лог не пиши. Бот не должен падать молча из-за ошибки
в одном обработчике. Покажи, где смотреть лог.
Если агент застрял на одной ошибке — возьмите промт для исправления ошибки. Подробнее о режиме плана — в промте «сначала план».
Шаг 4. Токен и .env#
Токен — это полный доступ к боту. Кто его знает, тот может отвечать от имени бота.
- Храните токен в файле
.env, а в код читайте его из окружения. Так сделано и в официальном примере aiogram:getenv("BOT_TOKEN"). - Добавьте
.envв.gitignoreдо первого коммита. В репозиторий кладите.env.exampleс пустыми значениями. - Если токен всё-таки попал в репозиторий или в переписку, отзовите его в @BotFather и получите новый: в BotFather это можно сделать в любой момент.
Шаг 5. Polling или вебхук#
У Telegram Bot API два способа доставлять сообщения боту, и они взаимоисключающие:
- Long polling (getUpdates). Бот сам спрашивает Telegram о новых сообщениях. Не нужны ни домен, ни HTTPS — достаточно, чтобы программа была запущена.
- Вебхук. Telegram отправляет каждое сообщение на HTTPS-адрес вашего сервера. Нужен адрес с сертификатом, поддерживаются порты 443, 80, 88 и 8443.
Пока установлен вебхук, getUpdates не работает. Сообщения, которые бот ещё не забрал, Telegram хранит не дольше 24 часов.
Что выбрать для первого бота — polling. Документация grammY советует так же: если нет веской причины для вебхука, берите long polling, у него нет серьёзных недостатков, а чинить приходится меньше. Вебхук уместен, когда бот работает на serverless-платформе или на сервере, где уже есть HTTPS. В aiogram есть отдельный раздел документации про вебхуки, когда он понадобится.
Шаг 6. Где запустить бота#
Бот с polling отвечает, только пока запущена программа. Документация Telegram описывает перенос бота на сервер так: упаковать код, арендовать VPS или аналогичный сервер, который всегда включён, загрузить туда файлы и запустить. Для автоматического перезапуска программу оформляют как службу (на Linux — через systemd) или запускают в Docker-контейнере.
Промт для этого шага:
Подготовь бота к запуску на Linux-сервере: инструкцию по установке
(Python, venv, зависимости), файл службы systemd с автоперезапуском,
чтение переменных из .env. Ничего не запускай на сервере сам —
дай мне команды по порядку и объясни каждую одной фразой.
Главное правило: бот с одним токеном должен быть запущен в одном месте. Не забудьте остановить копию на своём компьютере, когда бот заработает на сервере.
Бот молчит: чек-лист#
| Признак | Что проверить | Что сказать агенту |
|---|---|---|
| Бот не отвечает ни на что | запущена ли программа, нет ли ошибок в терминале | «Вот вывод терминала при запуске: [вставить]. Найди причину» |
| Ошибка Unauthorized при запуске | верный ли токен. Проверка: откройте в браузере https://api.telegram.org/bot<ТОКЕН>/getMe — при верном токене придёт описание бота | «Бот пишет Unauthorized. Проверь, как читается BOT_TOKEN из .env» |
| Polling запущен, но сообщения не приходят | не остался ли вебхук от прошлых экспериментов: пока он установлен, getUpdates не работает | «Проверь getWebhookInfo и, если вебхук есть, удали его через deleteWebhook» |
| В логе ошибка Conflict: terminated by other getUpdates request | бот запущен в двух местах с одним токеном: второй терминал, IDE, сервер | «Помоги найти и остановить лишний процесс бота» |
| На одни сообщения отвечает, на другие нет | ошибка в конкретном обработчике или не тот фильтр | «Бот не отвечает на [что]. Вот лог: [вставить]. Проверь фильтр и обработчик» |
| В группе бот не видит сообщения | включён режим приватности: в группе бот видит только команды к нему и ответы на свои сообщения | «Мне нужно, чтобы бот [что]. Как это сделать без отключения приватности?» |
Давайте агенту полный текст ошибки и лог, а не пересказ.
Как подключить нейросеть к боту#
Если бот должен отвечать с помощью языковой модели, принцип такой: обработчик получает сообщение, отправляет текст в API выбранной модели и возвращает ответ пользователю. Ключ API хранится в .env рядом с токеном бота. Добавляйте это отдельным шагом в ТЗ, когда обычный бот уже работает: так проще понять, где ошибка — в боте или в запросе к модели. Сразу решите, что делать с длинными ответами и ошибками API, и запишите это в раздел «Готово, когда».
Источники: Telegram — From BotFather to «Hello World», Telegram Bot API — получение обновлений и вебхуки, Telegram — возможности ботов и режим приватности, документация aiogram 3, пример echo-бота aiogram, aiogram — машина состояний, grammY — long polling или вебхуки, python-telegram-bot — ошибка Conflict, systemd.service.