Зафиксирую новый опыт и поделюсь с вами. Причём, изложу как запомнил т. к. что-то, кажется, часто идёт не так, когда я стремлюсь к точности.

Что случилось?

Неделю назад я сгонял на Code Fest 2025 (видео-история в канале), познакомился со Светлана Болсуновская. Она провела нам мастер-класс по мотивам книги «Хороший выбор. 45 упражнений для принятия решений от чемпиона мира по игре в покер» от Энни Дьюк.

Короче, есть механизмы принятия решений, а есть ускорители. Ускорители это типа лайфхаков, чтобы не топтаться на месте. Механизмы это каким образом решение должно быть принято.

Чуть подробнее

Механизмы

Например:

Почему руководитель не может принимать все решения единолично? Ответ: без поддержки команды некоторые решения не будут реализованы, либо будут реализованы плохо (а надо хорошо). Однако, есть решения, для которых поддержка не важна.

Примеры. В архитектурных вопросах или при внедрении каких-то практик поддержка команд важна, а при выборе кофе-машины нет. Во всяком случае, решение по выбору кофе-машины может быть реализовано быстро и хорошо вне зависимости от возражений. А решение по архитектуре… не факт.

Таким образом, механизмы принятия решений обладают двумя свойствами:

  1. Скорость
  2. Формируемый уровень поддержки

Возьмём консенсус. Например, я спрашиваю: что если я вот это перепишу вот так? Если никто не возражает, я перепишу… Консенсус – быстрый механизм, и обеспечивает мне достаточную поддержку, чтобы я взял и переписал.

Или я спрашиваю: давайте развернём Temporal и будем писать все джобы на нём? Не думаю, что консенсуса достаточно. Если все просто воздержатся, никто не поменяет технологию. Обнадёжит супербольшинство или хотя бы большинство. Однако, не всегда нужно спрашивать всех. В случае Temporal достаточно ключевых экспертов и лидов команд – это уже комитет, внутри которого ищем поддержку.

Короче, механизм это как будет принято решение.

Лайфхак № 1 – собирая созвон, имеет смысл объявить коллегам механизм.

Ускорители

Вот ещё ускорители от Энни Дьюк (ну и странные названия):

  1. Фрироллинг
  2. Две двери
  3. Овца в волчьей шкуре
  4. Тест по ключевому вопросу

Эти названия, понятные (видимо) игрокам в покер, вызывают у меня странные ассоциации. Например, путается волк в овечьей шкуре с овцой в волчьей. Кажется, можно войти не в ту дверь, когда их две…

Поэтому, я приведу эти ускорители в форме вопросов (номера совпадают):

  1. Можно ли заскочить и “бесплатно” выйти?
  2. Можно ли заскочить и “бесплатно” переобуться?
  3. Есть ли разница куда заскочить?
  4. Зачем это надо?

Задавайте себе эти вопросы, чтобы ускоряться – это будет лайфхак № 2. Может быть, ответ влияет на выбор механизма.

Кейсы

Погреемся на простом, а затем нырнём по настоящему…

Купить железо А или Б?

Вы покупаете что-то дешёвое, например, неуправляемые коммутаторы – это “овцы”.

Можно решить консенсусом, простым большинством в рамках узкого круга (сетевиков), либо единолично. Иногда, нужен консенсус лишь для того, чтобы не демотивировать ключевого сотрудника, считающего, что его мнение должно быть учтено.

Вы покупаете что-то дорогое, например, СХД – это серьёзный вопрос, уже настоящий “волк”.

Когда всё серьёзно, заходите в сравнение альтернатив, весовые системы и так далее…

Тут я подразумевал, что бесплатно переобуться или передумать не получится. Но иногда это фрироллинг, например, вам дают что-то на тест. Раньше СХД могли дать…

Как документировать API-методы?

Это настоящая большая история, которую мы покрутили на мастер-классе в нашей группе. Не буду говорить, что за компания.

Начало истории

В одной крупной компании в 2021-м году сменился вице-президент по технологиям, что породило волну инициатив. В частности, принцип API-First объявлялся частью стратегии. Надеюсь, Вы понимаете суть – сначала проектируется API, а потом разрабатывается реализация.

Принцип хорошо, но команды (на одном из больших продуктов, где несколько команд) состояли из аналитиков, которые в жизни своей не писали API-спецификации в YAML. Писали доку в конфлюэнс, параметры оформляли таблицами и это ехало в разработку. Неточности аналитики фиксились разработкой, которая тоже кое-что понимает. Было вполне окей.

Эксперимент c API-First в 2022-м году показал, что можно научить аналитика писать OpenAPI-спеку, но нельзя ограничиваться в найме (требовать опыта с OpenAPI на входе). Рынок был не тот (или продукт не тот). В любой момент аналитик, хорошо освоивший это дело, может уйти, а на его месте окажется новичок (так и было несколько раз).

Этот же опыт показал, что команда не в состоянии обеспечить соответствие между OpenAPI-спекой, вышедшей из аналитики, и итоговой OpenAPI-спекой (полученной при реализации).

Чего нет:

  1. Нет инструментария, чтобы гарантировать соответствие реализации аналитической спеке, нет скиллов в построении такого инструментария (их вообще на рынке мало).
  2. Нет инструментария, чтобы гарантировать соответствие аналитической спеки единому гайдлайну. Значит, API будут плясать в разных стилях. Скиллов в пайплайнах на гайдлайнах на рынке микроскопически мало, откуда они в команде?
  3. Быстрее разрабатывать так, как заставляет фреймворк, чем как пишут аналитики. Ради чего вообще создаются фреймворки – облегчать правильное и затруднять неправильное. Аналитик, при этом, фреймворком не ограничен.

Что есть:

  1. Горящие бизнес-задачи, которым необходим приоритет 3 года подряд.

Зачем я рассказал это? – это базис для вопросов-ускорителей, которые будут заданы ниже.

Что наблюдали?

По некоторой части API есть OpenAPI-спецификации от аналитиков, живущие в проектах GitLab (отдельно от реализации).

По некоторой части API нет OpenAPI-спецификаций от аналитиков, но есть описания входных и выходных параметров в Confluence – иногда приличное описание для каждого метода.

У большей части логики есть какое-то описание в Confluence, которое ссылается на спецификации (иногда не ссылается) или на описание других методов в том же Confluence. Причем, вместо аналитических спецификаций, полезнее бывает прочитать реализацию. Степень актуальности аналитических артефактов под вопросом. И, напомню, это было несколько разных команд, привязанных к разной функциональности большого продукта. Там были разные практики.

Однако, всё работало т. к. локально (на уровне команд) какие-то практики сложились.

Что произошло?

В 2025-м году после оптимизации продукта команды перемешали, перераспределили аналитиков. Каждый столкнулся с новыми для себя практиками. Начался большой диалог о лучших практиках и единообразии. Рой загудел.

Провели анализ, что создаёт трудности. На первое место вышла неуверенность в актуальности артефактов, дублирование описаний в разных артефактах и тому подобное.

Мир аналитиков, как оказалось, разделился – одни предпочитали OpenAPI и GitLab + Confluence, другие просто Confluence. И в той, и в другой группе есть хорошие аналитики, которые пишут достойную документацию.

Со стороны лидера разработки было высказано убеждение, что писать ещё один сваггер просто нет смысла. Разработка делает пагинацию как велит Spring Framework, а не как написано в анал-спеке. Архитекторы считали так же.

Коллеги обсудили, что кроме варианта просто взять и отказаться от аналитических спецификаций обратно, есть варианты по разному прокачать Confluence шаблонами для более структурированных описаний, варианты публиковать спеки в Confluence-плагине, причём множество – мини-спека на странице каждого метода или большая спека на странице API, а если второе, то можно включать её из GitLab, либо вставлять в сам Confluence…

Как это решать?

Вот что наштормила наша группа на мастер-классе:

  1. Нужен комитет, т. к. в режиме каждый-с-каждым обсуждать невозможно (есс-но).
  2. Здесь нет фрироллинга, дверей и овец – изменение практик это дорогое решение.
  3. Тест по ключевому вопросу – зачем менять практики?

Вдумались, API First был нужен вице-президенту. Разгребается, конечно, команда. Пользы ноль.

Вдумались глубже и увидели, что какое бы решение не приняли, без поддержки команды его реализовать невозможно. Комитет будет не просто голосовать, а сравнивать альтернативы и анализировать компромиссы. Большое и дорогое решение. Потом документация сама себя не перепишет.

Вдумались ещё глубже и задали вопрос чуваку, который притащил кейс: а тебе зачем это надо? – это и был тест по ключевому вопросу. Собственно, зачем этим управлять, других дел что ли нет?

Иногда решение иногда принимается так – найдётся инициативный чувак, который затащит изменение, значит надо делать, нет – нет. Если ты не можешь затащить изменение, то и не тащи. Тащи то, что можешь, в этом смысла больше. Кажется, если очевидного решения нет, нужно просто успокоить команду.

Порой всё кажется банальным…

Все эти механизмы и ускорители – обыденная банальность, а не наука.

Все мы покупали бытовые предметы, ёршики, коврики, лампочки, понимая, что думать тут не над чем. Иногда мы выбирали консенсусом, либо единогласно межкомнатные двери. Возможно, кто-нибудь выбирал стиральную машину попарным сравнением и взвешиванием её характеристик в составе комитета.

Давайте помнить это на работе и не превращать выбор корпоративного ёршика в выбор стиральной машины. И наоборот, API-First это тебе не ёршик, а сначала разберись где и как это работает!

Зачем нам мастер-классы?

Иногда, надо тренировать лучшую версию себя. Или вспоминать как ты принимаешь решения, когда думаешь логично. Однако, работа бросает нас в гонку, где после 2-3 кругов мы перестаём осмыслять наши приёмы и тонем в потоке бессмысленных, но необходимых обсуждений.

Возможно поэтому, когда я тусил на Code Fest 2025, я как-то сам собой оказывался на мастер-классах по софт-скиллам. Если профессия связана с софт-скиллами, может организм сам идёт прочищаться? Подумаю над этим..

Светлана Болсуновская, спасибо!