Чеклист архитектурного ревью для вывода ассистента ИИ

Почему аккуратный код всё ещё может создавать структурные проблемы

Чистый код может толкать систему в неправильном направлении. Тесты проходят, типы сходятся, и дифф выглядит аккуратно, но изменение может положить логику не в тот слой, обойти общие контракты или дать одному сервису знание, которого ему не следовало бы иметь.

Это часто случается с кодом, написанным ассистентом, потому что он решает локальную задачу перед собой. Попросите фичу — и он обычно найдёт кратчайший путь к рабочему поведению. Ревьюер видит зелёные тесты и читаемый код, поэтому изменение кажется безопасным.

Проблема проявляется позже. Хендлер начинает обращаться к хранилищу напрямую вместо прохождения через доменный слой. Фоновая задача тихо переосмысливает проверки прав. Новое поле переезжает из API в базу данных без ясного владельца, и три части приложения начинают делать собственные предположения о нём. В день слияния ничего не сломано, но система становится сложнее изменять с каждым пулл-реквестом.

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

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

Цель не в том, чтобы добавить бюрократию. Цель — меньше сюрпризов при слиянии и меньше "почему этот модуль это знает?" через неделю. Хорошее ревью должно останавливать код, который работает сегодня, но делает работу завтра грязной.

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

Границы, которые нужно определить до ревью

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

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

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

Ваш чеклист также должен назвать каждую точку взаимодействия, которую ассистент может использовать. Это включает API, внутренние сервисы, очереди, кэши и хранилища данных. Если вывод добавляет Redis в новое место, даёт прямые чтения из базы в маршруте UI или пропускает обычный вызов сервиса, ревьюер должен заметить это сразу.

Держите правила близко к реальному коду. Простой пример может сказать:

• Ассистент может менять валидацию запросов, логику сервисов и тесты.
• Ассистент может вызывать billing API и user service, но не неутверждённые сторонние инструменты.
• Ассистент может читать из PostgreSQL через сервисный слой, а не делать сырые запросы в контроллерах.
• Ассистент не может менять форматы событий, правила авторизации или файлы инфраструктуры без отдельного ревью.
• Ассистент должен следовать шаблонам команды по ошибкам, логированию и ретраям.

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

Это может звучать строго, но экономит время. Ревьюер может сравнить вывод с линиями владения и системными границами вместо спора о вкусе. Так структурные проблемы ловятся до слияния.

Как данные должны двигаться по системе

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

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

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

Короткая заметка ревью должна отвечать на четыре вопроса. Где данные входят? Какой сервис их проверяет? Какой сервис меняет формат? Какой сервис хранит их и на какой срок?

Некоторые границы требуют твёрдого «никогда». Сырые подсказки с персональными данными никогда не должны попадать в логи. Секреты не должны передаваться модели. Внутренние админ-заметки не должны возвращаться клиенту. Выведенные сводки могут переходить между сервисами, тогда как исходные документы остаются в одном защищённом хранилище. Ревью ловят больше структурных ошибок, когда эти запрещённые пути записаны, а не подразумеваются.

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

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

Кто принимает решения

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

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

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

Небольшой разрыв часто работает:

• Владелец модуля утверждает дизайн и форму кода внутри области.
• Владелец продукта утверждает влияние на пользователя, объём и сроки.
• Владелец данных утверждает изменения схемы, значение полей и правила хранения.
• Техлид или CTO решает спорные вопросы, когда изменение пересекает несколько областей.

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

Серые зоны требуют именованного рефери. Запишите, кто решает пограничные споры за один день или меньше. В стартапе это может быть CTO или fractional CTO. Быстрое владение важно, потому что одно изменение, написанное ассистентом, может одновременно затронуть код, инфраструктуру и процесс.

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

Превратите правила архитектуры в одностраничный лист ревью

Лист ревью работает только если кто-то может прочитать его примерно за две минуты и использовать во время пулл-реквеста. Если он превращается в мини-политику, никто не будет проверять его, когда код движется быстро.

Разделите правила на три группы: границы, поток данных и владение. Это держит страницу маленькой и делает структурные ошибки проще замечаемыми до слияния.

Что должно быть на листе

Для границ используйте язык «пройти» или «не пройти». Пройти, если изменение остаётся внутри модуля или использует утверждённый интерфейс. Не пройти, если оно залезает в внутренности другого сервиса, общие таблицы базы данных или приватный вспомогательный код. Чат-ассистент, например, может вызывать billing API, но не должен записывать напрямую в billing tables, потому что это ломает границу сервиса.

Для потока данных — пройти, если путь запроса легко прослеживается от ввода до хранения и вывода. Не проходить, если данные пропускают валидацию, копируются в побочные каналы или проходят через скрытые фоновые задачи без причины. Текст пользователя может попасть в сервис ассистента, быть отфильтрован, затем уйти в модель, а логи сохраняют только безопасную мета-информацию. Сырые подсказки по умолчанию не должны попадать в аналитику.

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

Каждая строка должна читаться как ворота, а не совет. Формулировки «Пройти если» и «Не пройти если» убирают споры и ускоряют ревью.

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

Если вы хотите, чтобы чеклист использовали, уберите всё, что требует встречи для объяснения. Лист должен помогать ревьюеру сказать «да», «нет» или задать один точный вопрос.

Проверяйте вывод ассистента перед слиянием

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

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

Именно здесь чеклист помогает. Он держит ревью в фокусе на структуре, а не только на стиле.

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

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

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

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

Отклонение слияния из-за структуры часто правильное решение. Аккуратный код в неправильном месте всё равно делает систему сложнее в эксплуатации. Небольшая задержка перед слиянием дешевле недели исправлений после релиза.

Простой пример от стартап-команды

Стартап просит ассистента добавить форму поддержки. Сгенерированный код сначала выглядит хорошо: чистый UI, кнопка отправки и сообщение об успешной отправке. Риск скрыт под поверхностью.

Чистая версия проста. Форма отправляет один запрос на бэкенд, например POST /api/support-requests. Этот API проверяет ввод на сервере, убирает мусор, прикрепляет ID залогиненого пользователя из сессии и записывает одну новую запись в базу. После этого запускается одно follow-up действие, например джоб уведомления.

Этот путь сохраняет границы чистыми. Браузер собирает ввод. API отвечает за валидацию и проверки прав. База хранит результат. Каждая часть делает одну работу.

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

Ревьюер может не заметить этого, если фокусируется только на том, работает ли форма. Она работает. Просто она ломает правила системы.

Чеклист помогает тем, что принуждает пару прямых вопросов:

• Посылает ли браузер данные в один утверждённый API?
• Валидирует ли сервер и назначает ли поля владения?
• Создаёт ли одно действие одну запись в базе?
• Происходит ли побочный эффект после основного сохранения, а не рядом с ним?

Эти четыре проверки ловят большинство проблем. Если вывод отправляет данные прямо из формы в несколько мест, ревьюер останавливает это. Если валидация есть только в JavaScript, ревьюер останавливает это. Если владение приходит с клиента, а не из сессии сервера, ревьюер останавливает это.

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

Ошибки, которые проходят проверку

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

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

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

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

Такие изменения часто проходят ревью, потому что выглядят маленькими. Утилита теперь сохраняет состояние. Путь чтения теперь триггерит побочный эффект. Сервис импортирует ещё одного клиента "только для этого случая". Фоновая задача начинает владеть бизнес-правилами.

Проверки владения тоже пропускаются при мелких правках. Ревьюер думает: "Всего 20 строк." Но даже маленький патч может переместить решение из одной команды в другую. Если логика ценообразования появляется в checkout, support и analytics, у неё больше нет реального владельца.

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

Хорошие правила звучат просто. "Profile service может читать только профильные данные." "Billing пишет только billing records." "Хелперы не пишут, если их имя этого не говорит." Эти правила кажутся слишком простыми, но они ловят больше структурных повреждений, чем любые витиеватые формулировки.

Когда в игру вступает вывод ассистента, простые правила важны ещё больше. Ассистент умеет сделать обход разумным на вид. Ревью ловят больше, когда команда проверяет границы, записи данных и владение до того, как восхищаться аккуратностью кода.

Быстрые проверки и дальнейшие шаги

Ревью идёт быстрее, когда команда использует одни и те же три вопроса каждый раз:

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

Если ревьюер не может ответить на все три за минуту–две, изменение, вероятно, не готово. Хороший вывод всё ещё может скрывать плохое разделение ответственности, новый путь данных или логику в неправильном слое.

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

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

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

Небольшая стартап-команда может сделать это без тяжёлого процесса. Если одно изменение, сгенерированное ассистентом, позволяет UI слою писать пользовательские данные прямо в отчётные таблицы, это — ошибка правила, а не просто баг. Следующее правило может сказать, что только бэкенд-сервисы могут записывать отчётные данные, и ревьюеры должны проверять этот путь.

Если команде нужна помощь превратить это в лёгкий процесс, Oleg Sotnikov на oleg.is работает со стартапами и малыми компаниями как Fractional CTO. Его фокус практичен: жёстче правила архитектуры, яснее владение и AI-augmented разработка, которая не превращается в хаос ревью.

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