🤔 Part I. Как принимать технические решения?
Часто в работе приходится принимать какие-то решения: как должна выглядеть архитектура проекта, какую метрику измерять, как сделать интерфейс forward(...) у кусочка модельки, чтобы его можно было легко поменять. И причём самое противное, - эти решения не принять экспериментальным путём, в отличие от, скажем, выбора лосса.
Обычно это происходит так: созвонились в Зуме или перетёрли в Слаке, решили «а давай сделаем вот так, вроде норм» и побежали писать код. Спустя полгода приходит новый человек (или вы сами возвращаетесь к проекту) и думаете: «А чё, почему мы так сделали?», и ничего не можете вспомнить, бегаете по слак-тредам в попытках найти правду, или запускаете весь мыслительный процесс заново. Или ещё хуже, если вдруг вам нужно доработать какую-то штуку, и вы не просто не можете что-то вспомнить, а упёрлись в ограничения своей реализации, и думаете «блин, а почему я норм не продумал это раньше». Или вы решаете какую-то задачку, а потом на код-ревью выясняется что вы всё сделали неправильно и приходится переделывать. Больно, страшно, печально. Но у всех перечисленных кейсов есть что-то общее: решения в них принимались непрозрачно и неявно.
Чтобы такого не было, люди придумали писать RFC и ADR. Основная идея этих штук - давайте думать прежде чем делать, а также формализовывать процесс нашего "думания" в виде текстовых документов.
📢 RFC (Request for Comments) — для стратегии и валидации идей
Это когда вы хотите внедрить что-то большое, что затронет много людей или изменит процесс работы глобально.
Цель: Собрать фидбек, найти "unknown unknowns", убедить людей.
Механика: Нам нужно, чтобы большинство согласилось, что идея норм. Иногда это может быть долгий процесс.
Примеры:
* «Давайте переедем с PyTorch на JAX» (затронет всех, нужно много обсуждений).
* «Внедряем Feature Store для шаринга фичей между командами поиска и реков» (большая идея, тоже нужно много обсуждений).
🏗 ADR (Architecture Decision Record) — для тактики и фиксации решений
Это инструмент команды. ADR создается, когда нужно принять конкретное техническое решение быстро. У ADR тоже есть стадия Draft/In Discussion.
Цель: Зафиксировать контекст и получить «добро» от тех, кого это касается напрямую.
Механика: Вопрос ставится в формате «Я предлагаю решение Х. Есть ли серьезные возражения (blockers)? Если нет — принимаем».
Примеры:
* «Используем Pydantic для валидации конфигов обучения».
* «Для сервиса X мы конвертируем веса в ONNX».
⚔️ RFC vs ADR: А в чём таки разница?
Это, наверное, спорный топик, и главное - это концепция «я сначала подумал, обсудил, а потом сделал», однако я привык к такому разделению:
* Масштаб: RFC — про идеи и влияние на многих. ADR — про реализацию и контекст внутри команды.
* Скорость: RFC может висеть неделями. ADR должен пролетать быстро.
* Результат: Принятый RFC часто рождает пачку конкретных ADR-ов о том, как именно мы это сделаем. Принятый ADR рождает уже конкретные задачи что-то сделать.
😭 Дак зачем это MLE?
Это понятный и прозрачный лог принятия решений в проекте, который упростит онбординг новичков и что-то подзабывших вас самих же.
ADR и RFC заставляют вас прийти к какому-то консенсусу с другими участниками команды заранее, существенно уменьшая количество недопонимания (как с вашей, так и с чужой стороны) во время реализации. Эти подходы провоцируют вас думать и заведомо принимать более хорошие и устойчивые решения, защищая от «да фиг с ним, го так, потом если чё поменяем». Это замечательный способ защититься от «синдрома вечного ресёрча». RFC/ADR ставит точку: «Мы исследовали 3 варианта, выбрали этот, тема закрыта. Двигаемся дальше». А ещё! Вы можете скормить свой ADR клод коду, и он с большей вероятностью сделает хорошо.
🚀 Как начать?
Не усложняйте. Если изменение большое и страшное — пишите RFC в Google доках/Notion, и кидайте ссылку на всех в каком-нибудь мессенджере, иногда созванивайтесь, чтобы какие-то совсем спорные и животрепещущие штуки закрыть. Если локальное — делайте Markdown файл прям в репозитории, отправляйте его в Pull Request, там же обсуждайте.