# Название проекта

> Одно предложение — что делает этот проект и зачем он существует.

## Технический стек

| Слой | Технология |
|---|---|
| Язык | — |
| Фреймворк | — |
| База данных | — |
| Инфраструктура | — |

## Структура репозитория

```
/
├── src/                  # исходный код
│   ├── modules/          # модули фич
│   ├── services/         # общие сервисы
│   └── utils/            # общие утилиты
├── docs/                 # дополнительная документация
├── tests/                # тесты
├── .env.example          # шаблон переменных окружения
└── README.md             # этот файл
```

> Каждая директория, содержащая самостоятельную логику, должна иметь свой `README.md`
> с описанием назначения юнита, его публичного интерфейса и зависимостей.

## Запуск

```bash
# 1. Клонировать репозиторий
git clone <repo-url> && cd <repo-name>

# 2. Скопировать и заполнить переменные окружения
cp .env.example .env

# 3. Установить зависимости
<команда установки>

# 4. Запустить в режиме разработки
<команда запуска>
```

## Переменные окружения

| Переменная | Описание | Обязательна |
|---|---|---|
| `EXAMPLE_VAR` | Описание того, что переменная контролирует | да |

## Конвенции

### Именование

| Артефакт | Конвенция | Пример |
|---|---|---|
| Файлы | `kebab-case` | `user-service.ts` |
| Директории | `kebab-case` | `auth-module/` |
| Переменные / функции | `camelCase` | `getUserById` |
| Классы / типы | `PascalCase` | `UserService` |
| Константы / переменные окружения | `UPPER_SNAKE_CASE` | `MAX_RETRIES` |
| Git-ветки | `type/short-description` | `feat/user-auth` |

### Коммиты

Следуем [Conventional Commits](https://www.conventionalcommits.org/):

```
feat: add user authentication
fix: handle empty input in parser
docs: update API reference
refactor: extract validation logic
```

### Стиль кода

- Никаких хардкодных секретов — только переменные окружения
- Все внешние вызовы (сеть, файловая система, БД) обёрнуты в обработчики ошибок
- Функция делает одно дело; стараться укладываться в 40–50 строк
- Магические числа и строки выносить в именованные константы
- Мёртвый код удалять, а не комментировать

## Стандарты и требования

- [ ] Обработка ошибок с понятными сообщениями на всех внешних вызовах
- [ ] Никаких секретов и учётных данных в исходном коде
- [ ] Каждый модуль/сервис/утилита имеет `README.md`
- [ ] Публичные интерфейсы задокументированы
- [ ] Конфигурация управляется через переменные окружения

## Тестирование

```bash
# Запустить все тесты
<команда тестов>

# Запустить с покрытием
<команда покрытия>
```

## Дополнительная документация

- [Обзор архитектуры](docs/architecture.md) _(если есть)_
- [Справочник API](docs/api.md) _(если есть)_
- [Руководство по деплою](docs/deployment.md) _(если есть)_