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

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

Запуск

# 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:

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

Стиль кода

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

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

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

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

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

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

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

Обзор архитектуры (если есть)
Справочник API (если есть)
Руководство по деплою (если есть)