«У меня работает» — до сих пор самый дорогой мем в разработке. Обычно за ним спрятаны глобальная нода неизвестной версии, ручная правка `/etc/hosts`, секрет в `.zshrc`, о котором забыли написать в README, и кэш, который «просто есть» на одном ноутбуке из пяти.
Я предпочитаю скучное: одна команда поднятия, зафиксированные версии, явные env-файлы-примеры без настоящих секретов, понятный смоук. Docker тут не религия — иногда хватает `asdf`/`mise` и нормального `Makefile`. Важно, чтобы новый человек за час увидел зелёный результат, а не квест с тремя чатами и шаманом команды.
На практике первым делом убиваю скрытые зависимости от машины. Локальная БД с продовыми кусками данных, VPN, без которого тесты «почему-то» красные, ручная установка системной библиотеки. Всё, что нельзя описать в репозитории, однажды предаст — обычно в день релиза или на онбординге.
Убираем скрытые зависимости
Seed-данные лучше держать маленькими и понятными. Гигантский дамп с прода экономит день сейчас и дарит месяц сюрпризов с персональными данными и странными состояниями позже. Для большинства багов хватает пары пользователей, заказа, платежа и одного кривого статуса. Отдельный пункт — совместимость с CI. Локально зелёное и красное в пайплайне из-за другой версии Postgres — всё ещё магия. Стараюсь, чтобы локальный смоук повторял ключевые шаги CI, пусть медленнее.
Если окружение сложное, документирую не только happy path, но и типичные поломки: порт занят, миграции отстали, сертификат протух, не хватает прав на volume. Это выглядит непрезентабельно в README и спасает пятницу лучше красивой схемы «архитектура локали».
Документируйте поломки
Споры «docker vs native» решаю прагматично. Что команда реально поднимает каждый день — то и поддерживаем. Второе окружение «для чистоты» быстро гниёт и начинает врать. Лучше один рабочий путь, чем два полуживых. Когда контур тяжёлый, честно режьте повседневный scope: не каждый поднимает весь зоопарк. Но полный путь должен быть описан и иногда прогоняться, иначе сгниёт незаметно.
Секреты локали — отдельная дыра. Не копируйте прод в `.env` «на минутку». Используйте фейки, локальные ключи, явные заглушки. Иначе секрет уезжает в скриншот, в бэкап ноутбука или в историю шелла.
Цель не красота инфраструктуры, а одинаковый результат у двух ноутбуков и CI. Пока этого нет, любая отладка наполовину про код и наполовину про шаманство. Сначала воспроизводимость — потом уже тонкая настройка под вкус.
Если онбординг всё равно буксует, снимите десятиминутное видео «поднимаю с нуля» и положите рядом с README. Текст врёт молча, а в видео видно, где человек на самом деле спотыкается. На практике после такого ролика число вопросов в чате падает заметнее, чем после очередной красивой схемы. И обновите его, когда путь сломается — протухшее видео хуже отсутствия, потому что уверенно ведёт не туда.