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, если один принятый способ дешевле сопровождать.

clsx сейчас не принят как direct dependency. Разные способы соединить классы сначала требуют подтверждённого повторения; устанавливать его заранее не нужно.

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

• Укажи конкретную потребность, альтернативу из текущего 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. Известная frontend граница TypeScript/openapi-typescript — в README; версии принадлежат manifest/lockfile.
• После изменения запускай relevant install/type/build/behavior checks и existing security workflow. Не добавляй второй analyzer, когда задача решается настройкой существующего; карта проверок.