Правила разработки и архитектуры для AI ассистентов.

Этот репозиторий содержит правила и руководства для разработки на NestJS с использованием TypeScript, MongoDB и других современных технологий. Эти правила предназначены для AI Code ассистентов, в частности для Roo Code, для обеспечения единообразного и качественного кода.

Содержание

• Правила кодирования
• Правила архитектуры
• Используемые технологии

Правила кодирования

Основные инструкции

• Используйте NestJS CLI для генерации модулей, контроллеров и других компонентов
• Yarn - менеджер пакетов по умолчанию
• GitLab - для хранения кода
• Обязательные команды после завершения задачи:
  • yarn lint - проверка стиля кода
  • yarn type-check - проверка типов
  • yarn build - сборка проекта
  • yarn format - форматирование кода

Качество кода

• ❌ Запрещены дублирования - всегда рефакторьте код
• ✅ Обязательна проверка производительности и безопасности
• ✅ Обязательна проверка читаемости и поддерживаемости
• ✅ Исправляйте все ошибки и предупреждения линтера
• ❌ Не используйте тестовые данные в продакшене
• ✅ Используйте env.example для конфигурации (не трогайте .env)
• ✅ Логируйте все важные действия через Logger из @nestjs/common
• ❌ Не пишите тесты - они не требуются
• ✅ Всегда мапьте _id в id
• ✅ Снижайте когнитивную сложность для легкого чтения
• ❌ Не оставляйте TODO в коде

TypeScript - Общие руководства

Основные принципы

• Английский язык для всего кода и документации
• Строгая типизация - всегда объявляйте типы для переменных и функций
• ❌ Избегайте any - создавайте реальные типы
• ✅ Используйте JSDoc для документации публичных классов и методов
• ❌ Не оставляйте пустые строки внутри функций
• ✅ Один экспорт на файл
• ✅ Предпочитайте ?? вместо || (более безопасно)

Номенклатура

• PascalCase для классов
• camelCase для переменных, функций и методов
• kebab-case для файлов и директорий
• UPPERCASE для переменных окружения
• ✅ Избегайте магических чисел - определяйте константы
• ✅ Начинайте функции с глагола
• ✅ Используйте глаголы для булевых переменных: isLoading, hasError, canDelete
• ✅ Полные слова вместо аббревиатур (кроме стандартных: API, URL, i/j для циклов, err для ошибок)

Функции

• Короткие функции с одной целью (менее 20 инструкций)
• Именование: глагол + описание
• Булевые функции: isX, hasX, canX
• Функции без возврата: executeX, saveX
• ✅ Избегайте вложенности через ранние проверки и возвраты
• ✅ Используйте высшего порядка функции (map, filter, reduce)
• ✅ Стрелочные функции для простых (менее 3 инструкций)
• ✅ RO-RO паттерн для множественных параметров

Данные

• ✅ Инкапсулируйте данные в составные типы
• ✅ Валидация в классах, а не в функциях
• ✅ Предпочитайте иммутабельность
• ✅ Используйте readonly для неизменяемых данных
• ✅ Используйте as const для литералов

Классы

• ✅ Следуйте SOLID принципам
• ✅ Предпочитайте композицию над наследованием
• ✅ Объявляйте интерфейсы для определения контрактов
• ✅ Маленькие классы с одной целью:
  • Менее 200 инструкций
  • Менее 10 публичных методов
  • Менее 10 свойств

Исключения

• ✅ Используйте исключения для неожиданных ошибок
• ✅ Обрабатывайте исключения для:
  • Исправления ожидаемых проблем
  • Добавления контекста
  • Глобального обработчика

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

• Jest + @nestjs/testing - основной фреймворк
• Пирамида тестов:
  • 75% unit тестов (полностью замоканные)
  • ≤20% интеграционные с MongoMemoryServer
  • ≤5% HTTP E2E через supertest
• Arrange-Act-Assert стиль
• ≥80% покрытие кода
• ❌ Никогда не используйте реальную БД в unit тестах

Правила архитектуры

SOLID принципы

1. Single Responsibility (SRP): Класс должен иметь только одну причину для изменения
2. Open-Closed (OCP): Код открыт для расширения, закрыт для модификации
3. Liskov Substitution (LSP): Подтипы должны быть полностью заменяемы для базовых типов
4. Interface Segregation (ISP): Много маленьких интерфейсов лучше одного большого
5. Dependency Inversion (DIP): Зависимость от абстракций, а не от конкретных классов

Классы

• ✅ Следуйте SOLID принципам
• ✅ Предпочитайте композицию над наследованием
• ✅ Объявляйте интерфейсы для определения контрактов

NestJS - Специфические принципы

Модульная архитектура

• Один модуль на основной домен/маршрут
• Один контроллер для основного маршрута
• Дополнительные контроллеры для вторичных маршрутов
• Структура модуля:
  • models/ - типы данных
  • DTOs/ - валидация входных данных с class-validator
  • services/ - бизнес-логика и персистентность
  • Один сервис на сущность

Архитектурные модули

Core Module

• Глобальные фильтры для обработки исключений
• Глобальные middleware для управления запросами
• Guards для управления разрешениями
• Interceptors для управления запросами

Shared Module

• Утилиты
• Общая бизнес-логика
• Сервисы, используемые между модулями

Используемые технологии

• NestJS - основной фреймворк
• Mongoose - ODM для MongoDB
• Swagger - документация API
• REST API - архитектура API
• MongoDB - база данных
• GitVerse - система контроля версий
• Yarn - менеджер пакетов

Дополнительная информация

Для получения более подробной информации обратитесь к файлам:

• .roo/rules-code/code_rules.md - полные правила кодирования
• .roo/rules-architect/architect_rules.md - полные правила архитектуры