Запись frontend‑решений, которую команда действительно будет обновлять

Почему команды теряют фронтенд‑решения

Решения во фронтенде редко исчезают в один драматичный момент. Они уходят понемногу.

Выбор начинается в чате: "оставить этот фильтр в URL". Другой попадает в тикет: "кешировать результаты на несколько минут". Третий остаётся в комментарии в коде, который никто больше не читает. Через несколько недель код всё ещё есть, но причина — исчезла.

Вот тогда и начинаются проблемы. Небольшие фронтенд‑выборы кажутся безобидными в момент принятия. Позже они определяют, как перемещаются данные, когда обновляются экраны и какая часть приложения владеет правдой.

Одна команда хранит настройки пользователя в локальном состоянии компонента. Другая часть приложения копирует те же настройки в глобальный стор. Затем приходит ответ с устаревшими данными, кэш не обновляется так, как ожидают люди, и никто не знает, какое значение UI должен считать достоверным.

Шаблон знаком: устаревшие данные, которые выглядят нормально, пока клиент не сделает обновление; дублирование состояния по компонентам и формам; неясность владения между фронтендом и бэкендом; и фиксы багов, которые добавляют ещё больше правил.

Эти баги обычно не от одной большой архитектурной ошибки. Они появляются из десятков мелких решений, которые никто не записал. Должно ли это значение жить в URL, локальном состоянии или общем сторе? Когда срок годности кэша истекает? Какой запрос обновляет список после мутации? Каждый ответ сам по себе кажется неважным. Вместе они решают, будет ли фича стабильной или хрупкой.

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

Именно это делает frontend decision record полезным. Он остаётся близко к фиче, объясняет решения, которые код сам по себе не покажет, и даёт следующему человеку что‑то лучшее, чем догадки.

Что положить в файл

Большинство команд делают файл слишком большим, а потом перестают его читать. Держите его коротким — чтобы можно было просканировать примерно за две минуты. Один экран — хорошее ограничение. Если нужны протоколы встреч, обсуждения дизайна или длинная история, положите их в другое место.

Файл работает лучше, когда у каждой фичи одинаковый шаблон. Так его проще сравнивать, проще ревьюить и гораздо проще обновлять в срочной релизной ситуации.

Простейшая структура достаточна. Начните с области: страницы, потока или компонента, который покрывает файл. Затем запишите выборы состояния: что живёт в локальном состоянии, что в общем, что в параметрах URL или на сервере. Добавьте правила по данным и кэшу, которые объясняют, откуда берутся данные, как долго они свежи и что вызывает обновление. Отметьте граничные случаи, особенно loading, empty, error, права доступа, устаревшие данные и конфликтные обновления. Закончите открытыми вопросами, включая владельца и дату следующего ревью.

Отделяйте факты от открытых вопросов. Факты должны читаться как принятые решения. Открытые вопросы — как работа в процессе. Когда это смешивается, люди начинают считать гипотезы правилами, и UI дрейфует.

На странице биллинга разница становится очевидной. Файл может сказать, что фильтры по счетам живут в URL, выбранная строка — в локальном состоянии, а данные по счетам обновляются после успешной оплаты или раз в 60 секунд. Если команда ещё не решила, как обрабатывать неудачные оптимистичные обновления, это должно быть в разделе открытых вопросов, а не рядом с устоявшимся поведением.

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

Как написать запись в пять шагов

Запись работает, только если остаётся короткой. Один файл на фичу обычно достаточен. Если она начинает превращаться в спецификацию, люди перестают её открывать и обновлять.

Заполните её до того, как код разойдётся по компонентам, хукам и вызовам API.

1. Начните с одного простого предложения о цели фичи. Пишите, что пользователь пытается сделать, а не что команда планирует построить. Например: "Пользователи могут сохранить черновик счета и продолжить позже." Эта строка привязывает дальнейшие решения к реальному результату.
2. Перечислите экраны и действия, которые важны. Назовите места, где фича появляется, и что пользователь там может сделать. Держите список кратким: создать, редактировать, повторить попытку, отменить, обновить. Это даёт команде общее представление о потоке без полной диаграммы.
3. Решите, где живёт каждая часть состояния. Отделяйте локальное UI‑состояние от общего состояния приложения и серверного. Флаг открытия модалки вполне может жить внутри компонента. Выбранный аккаунт, возможно, должен жить выше. Данные сервера обычно принадлежат слою получения данных, а не копироваться в дополнительные сторы.
4. Добавьте правила кэша и граничные передачи до того, как напишете много кода. Отметьте, какие данные вы получаете, что может оставаться свежим некоторое время, что нужно повторно запросить после действий пользователя и какие события обновляют связанные экраны. Если сохранение черновика меняет и редактор, и страницу со списком, запишите это сейчас. Небольшие заметки здесь предотвращают большинство «почему эта страница устарела» багов.
5. Пересмотрите файл после первой рабочей версии. Этот шаг важен. Первый проход часто неверен в двух‑трёх местах, потому что реальное поведение проявляется только при запуске фичи.

Этого достаточно для полезной записи. Если кто‑то подключится к фиче через неделю, он должен за несколько минут понять решения по состоянию, правила кэша и поток данных.

Чётко фиксируйте выбор состояния

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

Состояние компонента — самый маленький бакет. Используйте его для UI‑деталей, которые важны для одной части экрана: открыт ли модал, какая вкладка активна или видим ли тултип. Если пользователь может уйти со страницы и потерять это значение без вреда, локальное состояние обычно верный выбор.

Состояние в URL — для того, что пользователь ожидает сохранить при обновлении, шаринге или при работе кнопки «назад». Фильтры, порядок сортировки, номер страницы и выбранные представления часто туда и идут. Короткая причина помогает: "Порядок сортировки в URL, потому что поддержка может открыть тот же вид по ссылке" — достаточно.

Серверное состояние приходит из API, так что считайте сервер источником правды. В файле должно быть, какие данные вы запрашиваете, где их читаете и можно ли показывать UI устаревшие данные короткое время. Избегайте копирования API‑данных в общий стор, если у фичи нет явной потребности, например, слияния данных сервера с несохранёнными локальными правками.

Состояние форм заслуживает отдельной заметки, потому что команды часто смешивают его с общим состоянием слишком рано. Черновые значения полей, ошибки и флаги dirty обычно остаются внутри формы до отправки. Общее состояние должно быть маленьким и скучным — это хороший знак.

Простая форматная заметка работает: имя состояния, где оно живёт, кто его читает и почему такой объём подходит.

Возьмите страницу поиска. Текст запроса в поле может жить в состоянии формы, в то время как применённый запрос попадает в URL. Список результатов — в серверном состоянии. Открытость панели фильтров — в компоненте. Четыре выбора, четыре короткие причины, и следующий разработчик не должен гадать.

Добавьте правила кэширования, которым можно следовать

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

Начните с первого загрузки. Скажите точно, когда приложение запрашивает данные. Загружается ли при открытии страницы, при раскрытии панели, после выбора фильтра или только после клика "Поиск"? Эта деталь экономит много лишних запросов и догадок.

Потом задайте окно свежести простыми словами. "Считается свежим 30 секунд" — понятно. "Короткосрочный кэш" — нет. Если экран делает повторный запрос в фоне, укажите это. Люди должны знать, будет ли UI тихо обновляться или ждать следующего действия пользователя.

Хорошая заметка по кэшу отвечает на базовые вопросы: когда стартует первый запрос, как долго данные остаются свежими, какие события вызывают рефетч, как UI меняется после create/edit/delete и когда кэш должен сломаться (invalidate), а не оставаться.

Правило для мутаций особенно важно, потому что команды часто реализуют это тремя разными способами в одном приложении. После create вы можете добавить новый элемент в список сразу, а затем сделать рефетч. После edit — патчить изменённую запись на месте. После delete — удалять элемент сразу, если только сервер не может откатить удаление и вернуть его обратно.

Отмечайте места, где кэш должен намеренно умирать. Конфиденциальные данные обычно очищают при выходе. Результаты поиска, привязанные к одноразовому фильтру, часто не должны пережить полный перезагруз. Быстро меняющиеся числа, временные права и поэтапные черновики форм требуют дополнительной осторожности.

Небольшой пример достаточен: таблица заказов загружается при открытии страницы, свежа 60 секунд, рефетчится по ручному обновлению и при возвращении окна, если устарела; после сохранения редактируемая строка обновляется локально, удалённые строки удаляются сразу, а весь кэш очищается при выходе. Если двое из команды ещё реализовали бы это по‑разному, правило не закончено.

Пропишите граничные передачи данных до того, как они сломаются

Большинство фронтенд‑багов начинается на краях. Значение приходит из API, преобразуется на клиенте, попадает в локальное состояние, а потом другой сервис читает его позже. Если никто не записал этот путь, команда начинает гадать.

Запись должна назвать каждый источник, с которым фича взаимодействует. Обычно это основной API, любой клиентский стор, браузерное хранилище и внешние сервисы вроде auth, payments, maps или analytics. Держите это просто: одна короткая заметка для каждого источника — что он отправляет и где фича его читает.

Отслеживайте владение, а не только движение

Команды часто пишут, где данные появляются, но пропускают, кто ими владеет. Здесь и начинается путаница. Если профиль пользователя владеет сервер, скажите об этом. Если форма владеет несохранёнными правками до отправки — тоже скажите.

Владение закрывает много бессмысленных споров. Когда значение выглядит неправильно, команда может проверить правильный слой сначала, а не трассировать всё приложение. Значок корзины может читаться из клиентского стора, в то время как итоговая сумма на кассе всё ещё принадлежит серверу. Это разные ответственности — и файл должен это отражать.

Короткая заметка для каждого значения работает: источник правды, где UI читает это значение, кто может изменить и когда оно синхронизируется обратно.

Отмечайте изменения формы и состояния ошибок

Записывайте каждое место, где данные меняют форму. Это включает переименование полей API для UI, преобразование строк дат в Date объекты, маппинг серверных enum в метки или объединение нескольких ответов в одну view‑модель. Эти места ломаются тихо.

Небольшое несоответствие может создать сюрприз. Скажем, фича показывает статус подписки. Billing API возвращает trialing, стор приложения хранит isTrial, а баннер ждёт trial. Это не кажется серьёзным, пока один устаревший экран не скроет неверное состояние.

Также опишите состояния, о которых люди вспоминают только в релизную неделю: loading, empty, error и offline. Не просто перечислите их. Скажите, что делает фича в каждом из них. Показывает ли она кэшированные данные при рефетче? Пустой результат означает «пока нет элементов» или «фильтры убрали всё»? При офлайне пользователь может читать старые данные или экран блокируется?

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

Простой пример для одной фичи

Список продуктов быстро превращается в хаос. Фильтры живут в одном месте, счётчики в другом, а одно массовое редактирование может оставить пол‑экрана устаревшим. Короткая запись фичи держит эти решения в одном файле, чтобы никто не гадал позже.

Один файл фичи может быть таким же маленьким:

# Feature: Product list with filters and saved views

Goal
Users can filter products, save a view, bulk edit selected items, and share the current list by URL.

State
- Local state: filter panel open or closed, draft filter input, selected rows.
- URL query params: search, status, category, sort, page, savedViewId.
- Rule: only applied filters go into the URL. Draft input stays local until the user clicks Apply.

Data
- Server data: product list, total item count, filtered item count, saved views.
- The API owns the list and both counts.
- The client does not recalculate counts after filtering or bulk edits.

Caching
- Cache the product list by full query string.
- Cache counts by the same query string.
- After a bulk edit, refetch the current list and current counts.
- If the edit can change a saved view result, mark saved view queries stale too.
- Do not refetch while the confirmation modal is open.

Edge case
- If a product gets deleted while its details tab is still open, show "This product no longer exists".
- Disable edit actions in that tab.
- When the user goes back to the list, refetch once and clear any selected rows that no longer exist.

Это работает, потому что отвечает на вопросы, которые обычно вызывают баги. Где живёт каждое состояние? Какие данные приходят с сервера? Когда кэш обновляется?

Неловкий граничный случай важен. Если кто‑то открыл продукт в другой вкладке, а кто‑то его удалил, UI должен иметь чёткое правило. Без него люди нажимают "Сохранить" для уже удалённого объекта, и приложение кажется сломанным.

Файл намеренно короткий. Если он разрастается в спецификацию, люди перестают его обновлять. Если он умещается на одном экране, обычно никто не против его править.

Ошибки, которые делают файл бесполезным

Файл перестаёт помогать в момент, когда пытается делать слишком многое. Он должен быстро отвечать на повседневные вопросы: где живёт состояние, что кэшируется, когда данные обновляются и какие границы между экранами или сервисами могут провалиться.

Команды обычно ломают это предсказуемо.

Первая ошибка — превращение файла в мини‑документ по дизайну. Если на чтение уходит десять минут, никто не откроет его при фиксе бага. Держите область узкой: одна фича и один набор решений.

Вторая ошибка — вставлять тут документацию по фреймворку. Вашей команде не нужен тут туториал по React Query или Redux. Им нужно локальное правило: что эта фича хранит, где и почему.

Ещё одна распространённая проблема — оставлять инвалидацию кэша как «решить позже». Отсюда растут реальные баги: устаревший профиль, запаздывающий счётчик корзины или панель, которая никогда не обновляется.

Команды также смешивают текущие правила с будущими идеями. "Возможно, позже перенесём на сервер" — в бэклоге, а не рядом с сегодняшним поведением. Когда выпущенная логика и черновые планы лежат вместе, люди читают не то.

А затем самая обычная проблема: никто не обновляет файл после релиза. Первая версия часто годится. Через три небольших изменения код и запись расходятся, и файл превращается в вымысел.

Короткий файл остаётся полезным, когда чётко отделяет то, что есть сейчас, и то, что может быть позже. Если будущее важно, добавьте маленький открытый вопрос в конце или следите за ним в другом месте. Не давайте спекуляциям размывать правила, которыми разработчики пользуются сегодня.

Правила кэша требуют дисциплины. Если команда знает, что список рефетчится после create, делает оптимистические обновления при edit и очищается при sign‑out, запишите это в точности. Пять простых строк бьют расплывчатые обещания.

Владение тоже важно. Один человек должен обновить запись в том же PR, где меняется поведение. Если фича вышла в пятницу, а файл ждёт правки до следующей недели, он, скорее всего, останется неактуальным.

Короткий чек‑лист для ревью

Пользуйтесь этим перед релизом и снова после первой недели реального использования. Файл работает, только если его можно быстро просмотреть, доверять ему и изменить без рыться в старых ветках.

Короткий файл обычно лучше полного файла, который никто не читает. Если страница перегружена, вырежьте старые дебаты, оставьте решение и одну‑две простые причины.

Задайте несколько прямых вопросов:

• Сможет ли новый коллега объяснить, откуда приходят данные, где они живут и что их обновляет?
• Есть ли у каждого общего значения только один дом?
• Покрывают ли правила кэша create, edit и delete с понятным поведением, а не расплывчатыми обещаниями?
• Показывает ли каждая граничная передача источник, владельца и любые изменения формы?
• Обновлял ли кто‑то файл после того, как реальное использование выявило пробелы?

На экране профиля пробелы особенно заметны. Если он показывает карточку пользователя, панель прав и ленту активности, и запись не говорит, кто владеет состоянием прав или что происходит после удаления роли админом, люди будут гадать — и, как правило, по‑разному.

Цель ревью не в оценке текста. Она в проверке, соответствует ли файл фиче, которая используется сегодня. Если нет — исправьте фичу или запись в тот же день.

Что делать дальше

Выберите одну фичу, над которой уже ведётся работа. Не самую большую и не самую грязную. Что‑то достаточно активное, чтобы команда коснулась её на этой неделе, затем напишите первую запись для этой фичи.

Держите её короткой. Один файл покрывает три вещи: где живёт состояние, как работает кэш и от каких граничных передач зависит фича. Если написание занимает час — файл, вероятно, слишком большой.

Используйте файл при планировании, разработке и ревью. Эта повторная употребляемость важнее идеальной формулировки. Файл, который люди открывают в процессе работы, остаётся живым. Тот, что существует только ради документации — нет.

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

Простая привычка помогает: относитесь к записи как к части pull request. Если поведение изменилось, изменился и файл. Обычно этого достаточно, чтобы держать решения по состоянию видимыми, не превращая процесс в бумажную волокиту.

Если ваша команда постоянно возвращается к одним и тем же архитектурным спорам или вы хотите более аккуратный процесс для доставки с поддержкой ИИ, внешняя проверка может помочь. Oleg Sotnikov at oleg.is работает со стартапами и малыми командами по архитектуре продукта, процессам доставки, инфраструктуре и практическим настройкам разработки с приоритетом на ИИ, которые команды действительно используют.

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