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

Кирилл Гончаров, директор по продукту и цифровой трансформации BusinessPad

Сергей Адамов, системный аналитик BusinessPad

Представим ситуацию. Вы настроили ИИ-агента и за две недели собрали с его помощью новый продукт — например, систему согласования заказов. В ней менеджер создает заказ, финансист его проверяет, руководитель согласовывает, после чего запускается доставка. Система работает, и пользователи могут пройти весь процесс от начала до конца. Но вдруг выясняются детали, которые сложно было предусмотреть заранее: например заказы дороже 100 000 рублей должен подтверждать директор.

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

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

Как составить описание

В описании нужно зафиксировать две сущности. 

Первая — предметная модель, то есть из чего состоит продукт. Команде нужно перечислить основные объекты системы, их характеристики, связи между ними, роли пользователей, возможные состояния и ограничения. Например, для системы согласования заказов нужно указать, что в ней есть заказ, клиент и договор; у заказа есть номер, сумма и дата; каждый заказ связан с клиентом; работать с ним могут менеджер, финансист и директор. Также нужно зафиксировать возможные состояния заказа — например, «черновик», «на проверке» и «согласован»; и ограничения: например, сумма заказа не может быть отрицательной.

Вторая — то, что я называю семантическим контрактом. По сути это набор правил, которые определяют, как должен работать продукт независимо от того, на каком языке написан код и через какой интерфейс с ним взаимодействует пользователь. Если предметная модель отвечает на вопрос «из чего состоит продукт?», то семантический контракт — «как он должен работать?».

В этой части от компании требуется описать действия, которые можно выполнять в системе: кто имеет право их выполнять, при каких условиях, что должно произойти в результате и как проверить, что действие выполнено правильно. Для наглядности возьмем действие «согласовать заказ». Тут можно прописать, что согласовать его могут финансист или директор. А для этого в заказе нужно предварительно указать имя клиента, сумму оплаты и дату. После согласования статус заказа меняется на «согласован», участники получают уведомление, а действие фиксируется в журнале. Если статус изменился, но уведомление не отправилось, система должна повторить отправку, не согласовывая заказ повторно. Если сумма заказа превышает установленный лимит, его должен подтвердить директор.

Базовая единица семантического контракта — возможность продукта, то есть действие, полезное для пользователя, с понятными условиями и проверяемым результатом. Например, «согласовать заказ» — возможность продукта, а кнопка «Согласовать» — лишь один из способов ее использовать. Сегодня пользователь нажимает кнопку, завтра дает команду ИИ-агенту, а позже запускает то же действие из другой программы. Способ взаимодействия меняется, но правила согласования остаются прежними.

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

Почему недостаточно описать кнопки и запросы

Самый простой способ зафиксировать работу системы — записать: «кнопка №143 запускает запрос №27». Для автоматизации существующего интерфейса этого может быть достаточно. Для развития продукта — нет. Все потому, что такая запись не объясняет, зачем пользователь выполняет действие, в каких случаях оно разрешено и какой результат считается правильным. Стоит перенести кнопку или изменить техническую реализацию запроса, и описание устареет.

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

Где хранить описание

Храните его там же, где и код, то есть в репозитории продукта, в отдельной папке. Пишите его обычными текстовыми файлами, например в форматах Markdown и YAML: их одинаково легко читают человек и ИИ-агент. Тогда описание попадает в историю версий, и видно, кто, когда и почему поменял правило. Каждую правку описания проверяет владелец продукта, так же как и правки кода. Так описание не отстает от системы, в отличие от документа в чате, который через месяц никто не открывает. Агенту достаточно указать путь к папке: перед работой он прочитает правила и будет действовать в их границах. Проверочные сценарии положите рядом и свяжите с возможностями продукта. Так после каждой правки система будет сопоставлять результат с описанием.

Зачем бизнесу описание 

Есть пять главных ценностей семантического описания.

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

2. Архитектуру можно перестраивать сколько угодно раз.
Даже если код трансформируется, смысл продукта и критерии работы остаются неизменными. Поэтому первый интерфейс при необходимости можно смело заменить, а единый сервер можно разрезать на самостоятельные службы. Способ, которым части системы передают друг другу данные, также можно перепридумать, а ИИ-модель или ее поставщика сменить. 

3. Можно легко упаковать продукт в новый интерфейс. 

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

4. Любую новую версию можно проверить по бизнес-результату.
Новую версию сверяют не со старым видом экрана, а с бизнес-смыслом: остались ли на месте правила, допустимые состояния, права и ожидаемый результат. Из семантики выводят приемочные тесты и повторные тесты для сценариев, которые уже работают. Так видно, где система ведет себя не так, как записано. Агент получает границы, внутри которых он работает сам. Сильные модели делают эту схему мощнее, но источником истины остается каркас.

5. Продукт копит подтвержденный опыт.
Система записывает трассировку действий пользователя (последовательность его шагов) с пометками смысла. В ней видно, кто это и какую роль он играет, с какой сущностью работает и в каком она состоянии, какими элементами интерфейса пользуется, какие шаги делает, чем все заканчивается, где ошибается и как исправляет ошибку. Элементы интерфейса и доступные шаги связаны с каркасом, поэтому трассировка показывает не ряд кликов, а настоящий путь пользователя и его цель. Агент изучает его, сравнивает шаги пользователя с ожидаемыми состояниями и результатами. Он также находит цели, которые люди повторяют, обходные пути и места, где факт расходится с правилом. Затем человек проверяет выводы агента. А подтвержденные выводы становятся тестами, примерами для агента, уточненными правилами и контекстом компании или отдельного человека. Так продукт постоянно развивается и становится лучше.