crypto-breakout-screener

Imported from xsa-dev/crypto-breakout-screener (AGENTS.md). Install upstream with npx skills add xsa-dev/crypto-breakout-screener. Copyright stays with the author.

AGENTS.md

Инструкции для AI-агентов (Claude Code, Codex и др.), работающих в проектах на основе этого шаблона. Шаблон используется в курсе Ayaz Sh по разработке крипто-скринеров и торговых ботов.

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

1. Типовая структура проекта

Шаблон фиксирует только инфраструктурную часть — каталог app/core/. И даже там физически лежит лишь необходимый минимум (config.py, env.py, logger.py); остальные файлы core/ создаются по мере надобности (см. ниже). Всё остальное (как организован доменный код: exchanges/, screeners/, strategies/ и т. д.) каждый проект решает сам, исходя из задачи. Архитектуры приложений всегда отличаются — фиксировать их в шаблоне нельзя.

<project_root>/
├── .claude/
│   └── skills/              # project-level skills (см. раздел 4)
├── app/
│   ├── __init__.py
│   ├── __main__.py          # entrypoint: запускается через `python -m app`
│   ├── core/                # инфраструктура: общие, переиспользуемые, неспецифичные модули
│   │   ├── __init__.py
│   │   ├── config.py        # конфигурация приложения (загруженные настройки, константы)
│   │   ├── env.py           # загрузка и валидация переменных окружения (.env)
│   │   └── logger.py        # настройка loguru (см. skill loguru-logging)
│   │
│   └── ...                  # доменный код — структура на усмотрение проекта
├── .env.example
├── .gitignore
├── pyproject.toml
├── README.md
├── AGENTS.md
└── CLAUDE.md                # ссылается на AGENTS.md

Правило раскладки

• app/core/ — всё, что инфраструктурное и переиспользуемое: конфиг, окружение, логирование, общие DTO/enums/исключения, базовые утилиты. Этот слой одинаков во всех проектах шаблона.
• Остальное в app/ — на усмотрение проекта. Единственное жёсткое правило: доменный код импортирует из core/, но не наоборот. core/ ничего не знает о конкретной предметной области.
• Корневой пакет — app/, entrypoint — app/__main__.py. Приложение запускается командой python -m app. Это дефолт для всех учебных проектов — он проще, понятнее и подходит большинству задач курса.

Составной проект (src/ с несколькими процессами)

Когда репозиторий перерастает рамки одного процесса — есть торговая логика и отдельная веб-админка, которые запускаются как два сервиса, но делят общий код (core/, БД), — используется раскладка с src/. Это канон для проектов вида «торговый бот + веб-панель» (пример — examples/pd-tradebot).

Доменные пакеты в src/ имеют фиксированные имена — не плоди синонимы (panel/, bot/, db/, trading/):

src/
├── core/         # инфраструктура: config, env, logger, schemas, enums... — как app/core/ выше
├── database/     # слой БД: database.py, models.py, repositories.py (skill sqlite-settings-storage)
├── app/          # логика приложения: скринер (producer/consumer), signal_manager, tradebot
│   └── __main__.py   # основной процесс:  python -m src.app
└── web/          # веб-приложение: FastAPI-админка — роуты, шаблоны
    └── __main__.py   # точка входа: ASGI-объект app; запуск: uvicorn src.web.__main__:app --host ... --port ...

Всё импортируется и запускается по полному пути от корня проекта (from src.core..., python -m src.app). src/ — обычная директория без __init__.py: Python видит её как namespace-пакет (PEP 420), поэтому из корня репозитория всё работает без editable-install. Проект не устанавливается как пакет ([tool.uv] package = false).

• src/core/ и src/database/ — общие, их импортируют оба процесса. core/ ничего не знает ни о app/, ни о web/.
• src/app/ — вся логика приложения: скринер, менеджер сигналов, изолированные tradebot'ы (см. skills screener-architecture, tradebot-architecture). Запуск — python -m src.app.
• src/web/ — только веб: FastAPI-роуты, шаблоны, статика. Бизнес-логику не дублирует — читает/пишет настройки через src/database/. Точка входа — src/web/__main__.py (там лежит ASGI-объект app), запуск — через uvicorn (uvicorn src.web.__main__:app --host 0.0.0.0 --port 8000), а не python -m web: так host и port задаются прямо в команде запуска.
• Два процесса = два systemd-юнита (см. skill systemd-vps-deploy): python -m src.app и uvicorn src.web.__main__:app. Запускаются и перезапускаются независимо.

Внутренние пакеты app/ и web/ (например, app/screener/, app/tradebot/, web/routes/) — на усмотрение проекта; фиксированы только эти четыре верхнеуровневых имени.

Используй src/ только когда реально есть два независимых процесса. Для одного процесса (чистый скринер, один Telegram-бот, REST-сервис) всегда выбирай первый вариант (app/) — он проще.

Что должно лежать именно в core/

core/ всегда содержит минимум — три файла, которые есть в шаблоне с самого начала:

Остальные файлы core/ в шаблоне отсутствуют и заводятся по мере надобности — когда в проекте реально появляется соответствующая потребность. Не создавай их «на будущее» пустыми. Когда заводишь — придерживайся этих имён и назначений (не плоди синонимы вроде dto.py, types.py, errors.py):

Принципы для контрактов (models.py, enums.py, exceptions.py)

1. Единый формат данных внутри приложения. Биржевые ответы нормализуются на границе (в коде биржевого клиента), наружу уходят только типы из core/schemas.py (рыночные данные) или core/models.py (DTO приложения). См. skill market-data-normalization.
2. Pydantic — для DTO приложения (models.py): даёт валидацию и сериализацию из коробки.
3. TypedDict — для рыночных данных (schemas.py): они приходят уже нормализованными от биржевого клиента, валидация не нужна, а TypedDict даёт типизацию без оверхеда.
4. Никаких сырых dict'ов с биржи между модулями. Если данные ходят между слоями — это либо TypedDict из schemas.py, либо Pydantic-DTO из models.py.
5. Enum'ы вместо магических строк. Side.BUY, а не "BUY".
6. Исключения — по необходимости. На первых, простых проектах хватает встроенных исключений Python и библиотек. Свои классы в core/exceptions.py заводим только когда появляется реальная потребность отличать ошибки друг от друга в коде (например, ретраить транзиентные, но прокидывать наверх логические — см. skill exchange-error-handling).

2. Импорты

• Используем абсолютные импорты от корня пакета: from app.core.config import config. В src/-раскладке src — пакет, и импорт идёт по полному пути от него: from src.core.config import config, from src.database import Database, from src.app.tradebot import Tradebot.
• Внутри одного пакета можно относительные: from .models import SignalDTO.
• core/ не импортирует ничего из доменного кода. Только наоборот. В составном проекте app/ и web/ не импортируют друг друга — общаются только через core/ и database/.

3. Стиль кода

• Python 3.13+.
• Типизация обязательна для публичных функций и методов.
• Pydantic v2 для DTO.
• Логирование — только через loguru, настроенный в core/logger.py. Не использовать print и стандартный logging напрямую.
• Конфигурация — только через core/config.py и core/env.py. Не читать os.environ россыпью по коду.
• Настройки Ruff и Pyright лежат в pyproject.toml. Не заводи отдельные .ruff.toml, ruff.toml или pyrightconfig.json без явной просьбы пользователя.
• Правила линтинга и type checking не ослаблять ради прохождения проверки. Если правило мешает задаче — сначала объясни причину и предложи точечное изменение.

4. Менеджер пакетов и запуск

В проектах курса используется uv — это дефолт, если пользователь явно не попросил pip, poetry или что-то ещё. Все команды установки зависимостей, запуска и работы с виртуальным окружением идут через uv.

Инициализация проекта

# создать .venv и установить зависимости из pyproject.toml + uv.lock
uv sync

После uv sync появляется .venv/ в корне и uv.lock (его коммитим, как и pyproject.toml).

Добавление и удаление зависимостей

uv add aiohttp              # рантайм-зависимость
uv add --dev pytest ruff    # dev-зависимость
uv remove aiohttp

Никогда не редактируй pyproject.toml руками для добавления пакетов — uv add обновит и pyproject.toml, и uv.lock согласованно.

Запуск

uv run python -m app        # запуск приложения
uv run pytest               # запуск тестов
uv run ruff check .         # линтер
uv run pyright              # проверка типов

uv run сам активирует .venv и подтягивает зависимости — отдельный source .venv/bin/activate не нужен.

Правила

• Если пользователь не оговорил иное — все команды от агента идут через uv (uv sync, uv add, uv run ...).
• pip install в инструкциях агента — только если пользователь явно отказался от uv.
• uv.lock коммитим. .venv/ — нет (уже в .gitignore).
• На VPS uv ставится тем же способом (curl -LsSf https://astral.sh/uv/install.sh | sh), и systemd-юнит запускает uv run python -m app либо абсолютный путь к интерпретатору из .venv (см. skill systemd-vps-deploy).

5. Биржевые клиенты

Никогда не пиши биржевой клиент с авторизацией самостоятельно. Подпись запросов, реконнекты, обработка лимитов, разбор ошибок биржи — это решённые задачи, и самописный клиент в учебном проекте почти всегда содержит ошибки. Порядок выбора:

1. Официальная библиотека биржи (если у биржи есть свой асинхронный коннектор). Для Binance — python-binance (from binance import AsyncClient): покрывает spot и futures, REST и WebSocket. Это дефолт для всех проектов курса по Binance.
2. unicex — если у биржи нет своей асинхронной библиотеки, либо проект работает сразу с несколькими биржами и нужен единый интерфейс. unicex даёт унифицированные клиенты, websocket-менеджеры и ExchangeInfo с округлением под фильтры.
3. Свой клиент с авторизацией — только в крайнем случае, когда ни официальной библиотеки, ни поддержки в unicex нет. Тогда подпись и сессию выноси в отдельный модуль и применяй skill exchange-error-handling.

Биржевой клиент создаётся один раз (await AsyncClient.create(api_key=..., api_secret=...)) и переиспользуется; в конце — await client.close_connection(). Ключи берутся из core/env.py (см. skill secrets-storage), округление цен/объёмов перед ордером — обязательно (см. skill exchange-rounding).

6. Skills (.claude/skills/ и .codex/skills/)

В шаблоне предустановлен пакет project-level skills, покрывающих узкие места крипто-разработки. Агент обязан обращаться к соответствующей skill, когда задача попадает в её область:

Источник skills в шаблоне — .claude/skills/. Для совместимости с Codex тот же набор skills вручную продублирован в .codex/skills/.

• api-rate-limits — REST/WS лимиты, backoff.
• websocket-lifecycle — реконнекты, ping/pong, gap detection.
• market-data-normalization — единый формат данных между биржами.
• loguru-logging — стандартная конфигурация логов.
• exchange-error-handling — классификация и обработка ошибок биржи.
• order-position-lifecycle — управление ордерами и позициями.
• systemd-vps-deploy — деплой как systemd-сервис.
• telegram-alerts — отправка уведомлений в Telegram.
• screener-architecture — архитектура скринера.
• exchange-rounding — округление цен и объёмов под фильтры биржи.
• order-placement-rules — правила выставления ордеров.
• position-sizing — расчёт quantity из USDT, минимальный размер позиции, разбиение на N ордеров.
• secrets-storage — хранение секретов в .env/БД, права API-ключей биржи, действия при утечке.
• env-and-config — core/env.py (pydantic-settings) + core/config.py (константы).
• sqlite-settings-storage — SQLite через SQLAlchemy async + aiosqlite (без Alembic): runtime-настройки, профили, история сигналов/сделок. Минимальная раскладка app/database/ из трёх плоских файлов: database.py, models.py, repositories.py. Не основной storage live-состояния (это биржа).
• async-patterns — asyncio-паттерны: фоновые задачи, gather, периодические циклы, graceful shutdown, отмена.
• tradebot-architecture — торговый бот поверх скринера: менеджер сигналов, фильтры, изолированный tradebot на символ.
• time-and-timezones — биржевые ms-таймстемпы, UTC vs локальное время, выравнивание по границам свечей, monotonic vs wall clock.
• graceful-config-reload — горячая перезагрузка настроек без рестарта процесса: фоновый цикл перечитывания из БД, атомарная подмена состояния.
• timeout-tracker — кулдауны и временные блокировки сигналов: не слать повторный алерт по символу N минут после первого срабатывания.
• signal-links — генерация ссылок на биржу, CoinGlass, TradingView для Telegram-алертов: inline-кнопки и HTML-ссылки в тексте сигнала.

7. Чек-лист при добавлении нового модуля

• Понятно, это инфраструктура (→ app/core/) или домен (→ остальной app/).
• Логирование — через loguru, конфигурация и секреты — через core/config.py / core/env.py (не print, не os.environ россыпью).
• Если модуль ходит в биржу — используется готовый клиент (официальная библиотека или unicex, не самописный — см. раздел 5), применены правила соответствующей skill (rate-limits, rounding, error-handling и т. д.).