diff --git a/README.md b/README.md
new file mode 100644
index 0000000..49e7f9a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,271 @@
+# 🚀 Python Project Template
+
+![Python](https://img.shields.io/badge/python-3.13-blue)
+![Docker](https://img.shields.io/badge/docker-ready-blue)
+![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)
+![License](https://img.shields.io/badge/license-MIT%20-green)
+
+Универсальный шаблон для создания Python-проектов с уже настроенной инфраструктурой разработки, тестирования и контейнеризации.
+
+Этот репозиторий позволяет начать новый проект **за несколько минут**, не тратя время на настройку инструментов и окружения.
+
+Шаблон задаёт единый стандарт для Python-проектов:
+
+- одинаковая структура проекта  
+- единые инструменты разработки  
+- воспроизводимое окружение  
+- готовая инфраструктура для запуска и деплоя  
+
+---
+
+# 📚 Содержание
+
+- [Быстрый старт](#-быстрый-старт)
+- [Что входит в шаблон](#-что-входит-в-шаблон)
+- [Структура проекта](#-структура-проекта)
+- [Docker](#-docker)
+- [Контроль качества кода](#-контроль-качества-кода)
+- [Тестирование](#-тестирование)
+- [Миграции базы данных](#-миграции-базы-данных)
+- [Локализация](#-локализация)
+- [Changelog](#-changelog)
+- [Workflow разработки](#-workflow-разработки)
+- [Release процесс](#-release-процесс)
+- [Для каких проектов подходит](#-для-каких-проектов-подходит)
+
+---
+
+# ⚡ Быстрый старт
+
+Клонируйте репозиторий:
+
+```bash
+git clone <repository>
+cd project
+````
+
+Установите зависимости:
+
+```bash
+uv sync
+```
+
+Запустите приложение:
+
+```bash
+python main.py
+```
+
+---
+
+# 🐳 Docker
+
+Собрать и запустить контейнер:
+
+```bash
+docker compose up --build
+```
+
+Docker-конфигурация включает:
+
+* production-ready `Dockerfile`
+* multi-stage сборку
+* оптимизацию размера образа
+* запуск контейнера без root
+* healthcheck контейнера
+
+---
+
+# ✨ Что входит в шаблон
+
+В репозитории уже настроены основные инструменты разработки.
+
+## Контейнеризация
+
+* Docker
+* Docker Compose
+* оптимизированная сборка контейнера
+
+## Проверка кода
+
+* Ruff — линтер и автоформатирование
+* mypy — статическая типизация
+* bandit — анализ безопасности
+* detect-secrets — обнаружение секретов
+
+## Автоматические проверки
+
+* pre-commit
+* проверки YAML и JSON
+* контроль merge конфликтов
+* обнаружение больших файлов
+
+---
+
+# 🧹 Контроль качества кода
+
+Перед каждым коммитом автоматически запускаются проверки:
+
+* линтинг
+* проверка типов
+* анализ безопасности
+* поиск секретов
+* базовые проверки репозитория
+
+Установка pre-commit:
+
+```bash
+pre-commit install
+```
+
+---
+
+# 🧪 Тестирование
+
+В проекте используется **pytest**.
+
+Особенности:
+
+* строгая конфигурация
+* поддержка asyncio
+* контроль предупреждений
+* удобный вывод ошибок
+
+Тесты располагаются в каталоге:
+
+```
+tests/
+```
+
+Запуск тестов:
+
+```bash
+pytest
+```
+
+---
+
+# 🗄 Миграции базы данных
+
+В проекте настроен **Alembic**.
+
+Он используется для:
+
+* управления миграциями базы данных
+* отслеживания изменений схемы
+* безопасного обновления структуры БД
+
+---
+
+# 🌍 Локализация
+
+Настроен **Babel** для поддержки переводов и интернационализации.
+
+Это позволяет легко реализовать многоязычные приложения.
+
+---
+
+# 📜 Changelog
+
+Используется **git-cliff** для автоматической генерации `CHANGELOG`.
+
+Changelog формируется на основе conventional commits.
+
+---
+
+# 📁 Структура проекта
+
+Рекомендуемая структура:
+
+```
+project/
+│
+├ src/
+│  └ app/
+│     └ main.py
+│
+├ tests/
+│
+├ migrations/
+│
+├ Dockerfile
+├ docker-compose.yml
+│
+├ pyproject.toml
+├ pytest.ini
+│
+└ README.md
+```
+
+---
+
+# 🔧 Workflow разработки
+
+Типичный рабочий процесс:
+
+1. создать новую ветку
+
+```bash
+git checkout -b feature/my-feature
+```
+
+2. внести изменения
+
+3. выполнить проверки
+
+```bash
+pre-commit run --all-files
+pytest
+```
+
+4. сделать коммит
+
+```bash
+git commit -m "feat: add new feature"
+```
+
+5. отправить изменения
+
+```bash
+git push
+```
+
+---
+
+# 🚀 Release процесс
+
+Релизы создаются с использованием **conventional commits**.
+
+История изменений генерируется автоматически:
+
+```bash
+git cliff
+```
+
+---
+
+# 🧩 Для каких проектов подходит
+
+Этот шаблон можно использовать для:
+
+* backend сервисов
+* API
+* Telegram-ботов
+* CLI инструментов
+* микросервисов
+* автоматизационных сервисов
+
+Он не привязан к конкретному фреймворку и может использоваться как универсальная база для Python-разработки.
+
+---
+
+# 🎯 Цель шаблона
+
+Этот репозиторий помогает:
+
+* ускорить запуск новых проектов
+* стандартизировать структуру кода
+* упростить разработку и деплой
+* внедрить единые инженерные практики
+
+Это **фундамент для Python-проектов**, который избавляет от повторяющейся настройки инфраструктуры.