main/.ai/conventions/dependencies.md

Dependencies

Перед добавлением

1. Найди аналог по назначению и реализации в affected repo.
2. Проверь его direct dependencies, текущий stack и native/stdlib API.
3. Определи масштаб: один простой случай или повторяющаяся техническая задача.
4. Используй существующее решение, если оно полностью покрывает поведение. Новый пакет оправдан меньшей общей сложностью, а не сокращением одной строки.

Повтор non-business задачи в примерно 3+ независимых местах — сигнал пересмотреть pattern, а не требование немедленно извлечь abstraction. Сравни общий helper, native API и зрелую небольшую dependency: parsing, serialization, dates, debounce, class composition. Три Array.map не требуют utility library. Не продолжай копировать boilerplate, если один принятый способ дешевле сопровождать.

При выборе пакета

• Укажи конкретную потребность, альтернативу из текущего stack и существенную цену: совместимость, browser bundle/server runtime, maintenance/security.
• Импортируемый пакет объявляй напрямую в repo владельца; наличие в соседнем repo или транзитивном дереве не является dependency contract.
• Сохраняй exact versions и lockfile. Перед Node-командами активируй .nvmrc через nvm use --silent; воспроизводимая установка — npm ci в нужном repo.
• Peer-конфликты решай совместимыми версиями, без --force/--legacy-peer-deps. Версии и compatibility принадлежат местному manifest/lockfile.
• После изменения запускай relevant install/type/build/behavior checks и npm audit при изменении зависимостей. Не добавляй второй analyzer, когда задача решается настройкой существующего; карта проверок.