В командном чате спорят, каким быть единому формату ошибок во всех API продукта. К вечеру выбор сделан, участники разошлись, а через месяц никто уже не может ответить, почему отвергли второй вариант. Аргументы тонут в скролле, контекст уходит вместе с уволившимися, и спор начинается заново с каждым новым голосом. Решение, принятое в переписке, держится ровно до закрытия окна. Эту привычную потерю лечат RFC-документы: короткие тексты предложения, которые проходят открытое ревью и остаются в проекте навсегда.
Спор в чате, из которого не выживает ни одна цитата
У чата как среды принятия решений три системных дефекта. Первый эфемерность: полезное сообщение закапывается под смайликами, повторами и обсуждением обеда. Второй отсутствие владения: в переписке нет автора решения и ответственного за вывод, выигрывают не аргументы, а настойчивость и порядок выхода в эфир. Третий отсутствие итога: даже когда выбор случился, он нигде не зафиксирован, и каждый новоприбывший честно переспрашивает, почему именно так.
Есть и человеческая сторона. Поздно включившиеся видят хвост переписки и вступают с вопросом, на который уже отвечали трижды. Тихие специалисты молчат, потому что перебивать поток неудобно, а выделяться не хочется. Итог принимает тот, кто громче всех повторил свою позицию, и глубина здесь проигрывает скорости без всякой возможности вернуться. Через полгода команда снова соберёт тех же людей и повторит тот же спор, потому что у него не осталось тела.
Протоколы встреч, которые команды ведут из отчаяния, тут не спасают. Запись о том, кто и что сказал, не содержит вариантов, минусов и альтернатив, а без них через год непонятно даже то, было ли решение выбором или просто усталостью. Документ предложения устроен иначе: он спорит сам с собой, поэтому его можно перечитать как рассуждение, а не как стенограмму.
Распределённой команде чат-решения обходятся дороже всего. Половина участников спала, когда выбор случился, и просыпается уже свершившимся проигравшим. Согласие, которое в одной комнате достигается кивками, здесь не собирается вовсе, и недовольство копится молча до ближайшего конфликта. Текст с открытым ревью снимает эту беду: у спящих есть сутки на замечания, и решение остаётся открытым ровно столько, сколько нужно.
Откуда пришёл формат и кто им пользуется
Аббревиатура RFC расшифровывается как request for comments, запрос комментариев. Формат придумали инженеры, строившие компьютерные сети: первый документ этой серии датирован апрелем 1969 года, автором значится Стив Крокер. Идея состояла в том, чтобы предлагать изменения открытым текстом и собирать замечания до, а не после. Порядок прижился повсюду: в экосистеме Python похожие документы называются PEP и существуют с 2000 года, в языке Rust процесс описан документом от марта 2014 года, где закреплены шаблон, статусы и нумерация.
Общее у всех версий одно: предложение живёт отдельно и от кода, и от переписки. Его можно прочитать целиком, процитировать, отклонить с причиной или принять с оговорками. Спор из потока сообщений превращается в текст с адресом, а адрес не исчезает. Отдельная сила в равенстве: документ может написать разработчик со стажем в один месяц, и открытое ревью уравнивает голоса лучше любого совещания.
Сфера применения шире архитектуры. Так же описывают порядок релизов, дежурства, правила ревью, поддержку старых версий: всё, что затрагивает многих и живёт долго. В больших проектах форматы различаются названиями, механика одна: черновик, ревью, номер, статус. Отсюда практичный вывод: команде не нужен собственный словарь, достаточно привычки оформлять выбор текстом до, а не после.
Стоит проговорить и то, чем формат не является. Он не замена тикетам: задача на реализацию после принятия живёт в обычном порядке. Он не замена разговору: резкое несогласие стоит проговорить голосом, а в документ занести итог. И он не приговор: принятый текст можно заменить новым документом, когда мир изменится, процедура для этого и придумана.
Анатомия документа, по которой спор превращается в работу
Шаблон делает спор управляемым, у каждого раздела есть своя работа:
# RFC 7, единый формат ошибок в API
Автор, статус: черновик
Сводка: один абзац о том, что предлагается
Мотивация: какую проблему решаем и кому от неё больно
Объяснение для пользователей: как изменения выглядят снаружи
Технический проект: как реализуем, граничные случаи, совместимость
Минусы: за что придётся платить прямо и косвенно
Альтернативы: что рассматривали и отчего отказались
Чужой опыт: кто уже ходил этой дорогой и что из этого вышло
Открытые вопросы: что не решено и кто будет решатьСводка заставляет сжать идею до абзаца, и половина разногласий умирает уже здесь: выясняется, что предлагали вовсе не то, что услышали остальные. Мотивация отделяет проблему от решения, и читатель вправе не согласиться с обоими по отдельности. Раздел с минусами лечит главную болезнь энтузиастов, недооценку стоимости, а альтернативы показывают, что автор думал шире первого пришедшего в голову варианта. Открытые вопросы честно говорят, где кончается проработка и начинается вера.
Отдельного слова заслуживает чужой опыт. Почти любое техническое решение уже принимали сотни команд, и этот раздел заставляет сначала поискать, потом писать. Ссылка на чужой путь экономит месяцы: видно, чем кончилась та или иная дорога, без повторения чужих граблей. А для спорящих раздел работает как общий фундамент: цитировать опыт проще, чем голосовать по вкусу.
Хорошая последовательность начинается не с документа, а с тикета о проблеме. Проблема описана, обсуждение показало разнобой мнений, и вот тогда предложение превращается в текст. Документ, написанный до разговора с теми, кого он затронет, будет переписываться целиком.
Дисциплина объёма здесь важнее красоты слога. Один документ описывает одно предложение: попытка свернуть в него всю стратегию команды даёт текст, из которого нельзя процитировать ни одной отдельной мысли. Лучше серия маленьких документов, чем один монумент, потому что маленький можно принять, отклонить или заменить отдельно от остальных.
Жизненный цикл от черновика до принятого решения
Документ проходит несколько состояний:
Жизненный цикл документа
черновик: текст пишется, номер ещё не присвоен
на ревью: ссылка уходит в общий канал, замечания в строках документа
принят: получает номер, уходит в реализацию с тикетом
отклонён: остаётся в архиве с причиной, номер не переиспользуется
заменён: ссылается на документ-наследникаВнутри команды путь выглядит обычно так. Автор копирует шаблон в репозиторий проекта, в каталог с номерами, и посылает черновик на ревью как обычный код: замечания пишутся в строки, спор идёт по тексту, а не по памяти. Когда разногласия исчерпаны, назначенный ответственный принимает или отклоняет документ, и тот получает финальный номер. Встреча при таком порядке становится факультативом: она нужна только там, где текст не снял спор, и её итог всё равно возвращается в документ.
Круг ревьюеров подбирается по последствиям, а не по чинам. Затрагивает документ две команды, значит обе читают черновик до принятия, а не узнают о новшестве из конфликта. Внешние замечания ценнее своих: со стороны видны места, где текст понятен только автору. Согласия всех добиваться не нужно, нужен выслушанный каждый, у кого изменится работа.
Принятые тексты стоит показывать в общей ленте: короткое сообщение о том, что документ с номером принят и что он меняет. Лента читается за минуту, зато смежные команды узнают о решениях из первых рук, а не из споров у чужого кода.
Правило номеров простое и важное: они никогда не переиспользуются. Читатель по номеру всегда находит именно то, что обсуждали год назад, даже если решение давно заменено. Замена проходит ту же процедуру, а старый документ ссылается на наследника. Отклонённые тексты не удаляются: они остаются в архиве с причиной, чтобы спор не начинался с чистого листа. Отсюда у формата редкий талант: история решений читается как история проекта, без устных преданий.
Что решать документом, а что оставлять в чате
Порог, выше которого спор переезжает в документ, стоит проговорить заранее:
- Выбор, который дорого откатывать: хранилище, брокер, схема API, язык внутреннего инструмента;
- Правила для всех сразу: стиль ошибок, структура модулей, границы сервисов, порядок миграций;
- Решение, переживающее авторов: поддержка версий, политика совместимости, гарантии безопасности;
- Спор, который уже возвращался и каждый раз заканчивался ничем;
- Всё прочее остаётся в комментариях к тикету, и это не поражение формата, а его экономия.
Существенность легко проверить по следствию: если выбор меняет смысл для пользователей или соседних команд, документ нужен, если меняет форму без смены смысла, достаточно комментария. Ускорение функции без изменения поведения, переименование, правка описания: всё это живёт в обычном ревью. И правило срабатывает в обратную сторону: спор, который третий раз возвращается в чате, говорит о том, что у него до сих пор нет документа.
Полезный тест перед стартом нового текста: закроет ли он вопрос новичка через год. Если закроет, стоит писать, даже если тема кажется мелкой. Если нет, лучше потратить вечер на разговор, потому что страница без контекста не поможет никому.
Грабли бюрократии и лечение лёгкой версией формата
Формат умеет съезжать в бюрократию, и первый симптом сорок страниц на смену кэша. Лечение простое: лимит объёма в одну-три страницы, излишки уходят в приложения. Второй промах вечное ревью, когда документ зависает на месяц, потому что всем некогда. Спасает таймбокс: неделя-две на замечания, потом ответственный решает, а молчание означает согласие. Третья беда мёртвый архив: если документы пишутся, но на них никто не ссылается, формат работает на галочку, и спасает только привычка ссылаться в тикетах и ревью.
Немного автоматизации поддерживает порядок без надзора. Шаблон хранится в репозитории рядом с кодом, а не в личных заметках автора. Линтер каталога проверяет, что у каждого документа заполнены статус и номер, и ругается на файлы без них. Мелочь, а история перестаёт зарастать черновиками без финала.
Четвёртый промах психологический: писать текст страшно, и формат кажется жертвой ради порядка. Здесь выручает лёгкая версия для мелких решений: пять строк, три поля, статус. Миф о том, что писать умеют только избранные, лечится тем же шаблоном: заполнить девять заголовков проще, чем сочинить эссе. Первые два документа у автора выйдут корявыми, третий уже читается свободно, а цена корявости низкая: ревью правит текст так же, как код.
Решение, которое можно процитировать через год
Чат хорош для скорости, документ для памяти, и попытка назначить одному обе роли проваливается в обе стороны. Спор, оформленный текстом до решения, экономит время после: новичок читает и не переспрашивает, спорящий цитирует раздел, а не пересказывает слухи, уволившийся уносит контекст, но не аргументы. Мерило простое: если на вопрос "почему так" в команде есть ответ со ссылкой, а не пожатие плеч, формат работает.
Зрелость видна по мелочи. В спокойной команде спор начинается с фразы "оформи документом", и это не бюрократическое оскорбление, а комплимент теме: её считают стоящей текста. В незрелой та же фраза звучит как отсылка подальше, и это верный признак, что формат ввели без разговора о его смысле.
Тренировочное упражнение, которое хорошо работает: взять недавний чат-спор и переписать его задним числом в короткий документ. На чужом материале страшно писать меньше всего, а польза двойная: команда сразу видит, сколько бы пропало, и получает первый настоящий текст в архиве.
Начать стоит с одного документа по реальному спору, который уже возвращался. Пять страниц не нужны, хватит одной, зато следующая пойдёт легче, а третья станет обычной работой. Чат не исчезнет и не должен: он останется местом, где споры начинаются. Разница в том, что теперь у них появится финиш с адресом, датой и номером, и команда перестанет платить за одни и те же решения дважды.