# Aiogram Bot Auditor

> Telegram-бот на aiogram 3.x падает, молчит или дублирует ответы — найти причину и укрепить: необработанный flood-control (429/TelegramRetryAfter), второй polling-инстанс (409 Conflict), блокировка event loop, MemoryStorage в проде, отсутствие graceful shutdown и идемпотентности, структура Router/middlewares/FSM, небезопасный webhook. Используй когда пользователь говорит «бот запущен, на /help не реагирует», «бот падает/тормозит/дублирует», пишет или чинит aiogram-бота, настраивает FSM, middlewares, webhook или рассылку. Только aiogram 3.x. Сервис на сервере не поднимается вовсе — vps-ops.

- Skill: `goldenprofile/aiogram-bot-auditor` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add goldenprofile/aiogram-bot-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldenprofile/aiogram-bot-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: goldenprofile (https://skillmd.com/u/goldenprofile)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goldenprofile/aiogram-bot-auditor

---


# Aiogram Bot Auditor

Аудитор и помощник по Telegram-ботам на **aiogram 3.x**. Цель — поймать то, из-за чего бот в
проде падает, тормозит, дублирует ответы, теряет состояние или попадает под флуд-бан, а также
выправить структуру и тесты. По итогу — отчёт с уровнями риска и (по согласованию) правки.

## Когда применять

Перед деплоем бота, при ревью PR, при жалобах «бот не отвечает / тормозит / дублирует / теряет
шаг диалога», при настройке рассылки, FSM, middlewares, webhook. Только aiogram 3.x — если код
на 2.x (`executor`, `Dispatcher(bot)`, `@dp.message_handler`), сначала предупреди о
несовместимости и предложи миграцию на 3.x, не применяй 3.x-советы вслепую.

## Контекст — установить ПЕРВЫМ делом

1. **Версия aiogram** — подтверди 3.x (импорты `from aiogram import Router, F`, `dp.run_polling`).
2. **Запуск** — polling (по умолчанию у владельца) или webhook. См. [references/deploy.md](references/deploy.md).
3. **Storage FSM** — MemoryStorage (только dev) или RedisStorage (прод). У владельца есть redis.
4. **Масштаб** — есть ли рассылки/большая аудитория (тогда критичен flood-control и троттлинг).
5. **Инстансы** — гарантирован ли один polling-процесс (две копии → 409 Conflict).

## Процесс

1. Собрать точки входа (`__main__`, создание `Bot`/`Dispatcher`, `run_polling`/webhook-setup),
   роутеры, middlewares, FSM, обработку ошибок, места `bot.send_*`/рассылок, деплой-юнит.
2. Прогнать по чеклисту рисков (ниже) и справочникам.
3. Классифицировать риск, объяснить *почему* ломается в проде именно у него.
4. Предложить безопасную альтернативу.
5. Отчёт по [references/output-format.md](references/output-format.md); по согласованию — правки.

## Уровни риска

- **CRITICAL** — бот не работает/недоступен в проде: две polling-копии (409), блокировка
  event loop (sync/CPU в хендлере), краш без graceful shutdown с потерей состояния.
- **HIGH** — рассылка без обработки `TelegramRetryAfter` (429) и `TelegramForbiddenError`
  (бот заблокирован) → бан токена/потеря сообщений; MemoryStorage в проде (теряет FSM при
  рестарте); глобально не обработанные `TelegramAPIError`.
- **MEDIUM** — нет идемпотентности к повторной доставке апдейтов, нет таймаутов, токен/секреты
  в репозитории, `allowed_updates` не включает нужные типы, монолит без роутеров/middlewares.
- **LOW** — стиль, именование, мелкие улучшения.

## Быстрый чеклист

- Гарантирован **один** polling-инстанс? (две копии → 409, апдейты теряются)
- Рассылка ловит `TelegramRetryAfter` и `TelegramForbiddenError`, троттлит (≤~30 msg/s, ~1/s в чат)?
- В хендлерах нет блокирующих/CPU-операций в event loop (sync-БД, requests, тяжёлые вычисления)?
- FSM на **RedisStorage** в проде, а не MemoryStorage?
- Есть graceful shutdown: `dp.shutdown`, закрытие `bot.session`, redis, пулов БД?
- `allowed_updates` включает нужные типы (`callback_query`, `my_chat_member` и т.п.)?
- Токен и секреты — из env/`EnvironmentFile`, не в репозитории?
- Хендлеры идемпотентны к повторной доставке (особенно платежи/побочные эффекты)?
- Webhook (если есть): проверяется `secret_token`, за nginx+TLS, `drop_pending_updates` осознанно?

## Связь с библиотекой навыков

- Бот ходит в БД с миграциями → перед деплоем навык **`migration-safety-auditor`**.
- Аудит/написание тестов хендлеров и FSM → **`test-coverage-auditor`** (см. также
  [references/testing.md](references/testing.md)).
- Ревью диффа правок → **`change-review`**; перед релизом → **`python-project-audit`**.

## Справочники

- [references/reliability.md](references/reliability.md) — Telegram API: 429/flood-control,
  ошибки, троттлинг рассылок, таймауты, graceful shutdown, идемпотентность, single instance.
- [references/architecture.md](references/architecture.md) — Router, middlewares (outer/inner),
  DI, FSM и storage, фильтры (`F`), структура проекта, вынос бизнес-логики из хендлеров.
- [references/deploy.md](references/deploy.md) — polling под systemd (основное), webhook+nginx
  (best practice), RedisStorage, секреты, логирование, healthcheck, один экземпляр.
- [references/testing.md](references/testing.md) — pytest, мок `Bot`, `feed_update`, тесты
  хендлеров и переходов FSM.
- [references/output-format.md](references/output-format.md) — формат отчёта.