Вайбкодинг <> Документация?

Что произойдет, если AI-программист будет получать контекст не из собственного чата, а из функциональной и архитектурной модели проекта?

Последние пару месяцев я работал над несколькими прикладными задачами.

• агент-аналитик, который помогает выявлять бизнес-процессный функциональный каркас ERP-систем. Наша специализация — замена одной ERP-системы на другую, а такая работа начинается с выявления As Is в уходящей системе и моделирования To Be в новой. Чем полнее мы выявили существующие функции и промоделировали их в новой системе, тем надежнее можно провести переход.

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

• процессный ассистент — эксперимент, в котором сотрудник компании взаимодействует с «зоопарком» корпоративных систем через Telegram-бота. Например, руководитель проекта запускает новый проект, бот предлагает подходящий процесс, затем сам создает контрагента в 1С и проект в Redmine. И все это мы проверяли без классической интеграции через HTTP-сервисы или API. Чистый nocode

Каждая лабораторная работа заканчивается видео на YouTube и появлением очередной папки. В какой-то момент объем трех проектов составил около 1,7 ГБ. Что если через несколько месяцев я захочу что-то изменить в каждом из этих агентов?

Я открою папку проекта в Cursor. Увижу код. Увижу Markdown-файлы. И, скорее всего, увижу довольно большой чат, где я самозабвенно давал агенту ценные указания до тех пор, пока он не стал выдавать нужный функционал.

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

Но после нескольких таких экспериментов стало понятно, что следующий вопрос должен быть другим:

А что произойдет, если вайбкодингом начать делать не только программу, но и ее документацию?

И не в смысле написать еще несколько Markdown-файлов.

Я решил попробовать сделать так, чтобы документация и функциональная модель проекта создавались одновременно с кодом.

Задача на текущую лабораторную работу

Совместить скорость программирования AI-агентом с полноценным документированием доработок с помощью ERP-tools.

Промежуточная задача - У нас есть 1С-версия ERP-tools, в которой работает проектная команда. Теперь нужно выпустить упрощенную веб-версию программы с ключевыми артефактами, чтобы заказчик мог следить за своим проектом в браузере.

Есть и задача со звездочкой.

Фактически текущий проект — это проект «2 в 1»: мы делаем проект, который делает другой проект.

Как всегда, есть и видео-версия для YouTube и RuTube, где можно увидеть реальную работу агента.

Markdown уже научил нас одной важной вещи

Для разработки с агентами сегодня совершенно нормально использовать Markdown-файлы.

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

Но у нас есть еще одно преимущество

ERP-tools это база данных, в которой артефакты функциональной модели хранятся не в текстовых файлах, а в отдельных сущностях и реляционных связях. И ERP-tools умеет описывать ERP-системы - наиболее заковыристые и гигантские виды программного обеспечения и там точно md файлы бессильны.

Поэтому проект начался с создания MCP-сервера — расширения для 1С, с которым будет общаться Cursor, — и системного промпта, объясняющего Cursor методологию пяти артефактов ERP-tools и правила работы с ними.

То есть мы решили проверить гипотезу:

А что если внешний контекст AI-программиста будет не набором Markdown-файлов, а структурированной моделью проекта в специализированной базе данных

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

Подготовка к проекту

Для начала мы создали новый проект в ERP-tools — ERPToolsWeb.

Затем создали пользователя Cursor и назначили его руководителем проекта - чтобы у него появились права чтения и создания данных внутри проекта.

После этого создали пустое расширение и сохранили его в XML. Здесь пришлось немного помогать Cursor - с созданием расширения с нуля он всегда ошибается.

Мы не ставим агента перед фактом:

«Вот репозиторий. Делай что хочешь».

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

Что не так с обычным вайбкодингом

Перед началом эксперимента я попросил Cursor самому перечислить проблемы вайбкодинга.

Получился довольно знакомый список.

Модель данных расползается

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

Ошибки модели всплывают поздно

Агент реализует ровно то, что описано. Если в описании есть дыра, он вполне способен аккуратно закодировать эту дыру.

Агент делает больше, чем просили

Это один из главных источников регрессий в вайбкодинге. Модель «заодно улучшает» соседний код, переименовывает, рефакторит и иногда меняет то, чего ее вообще не просили менять.

Права доступа размазываются по коду

Через 30–40 функций уже трудно сказать, кто и что может делать. Если каждая сессия придумывает собственный способ проверки роли, постепенно появляются и архитектурный хаос, и потенциальные проблемы безопасности.

При доработке непонятно, что она задевает

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

Знания живут в чате, а результат нечем проверить

Это результат выдачи Cursor, но конечно все зависит от умения ставить вопросы...

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

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

Архитектурные решения

Поэтому работу мы начали не с кода. Мы начали с архитектурных решений — правил, предназначенных одновременно для Cursor и для команды.

В ERP-tools используется требование с типом «Архитектурное решение». Внешне оно действительно похоже на Markdown-файл: оба содержат текст - есть название и подробное описание. Но у одного нужно прочитать весь файл, а в случае базы данных - текст лежит в специальном месте и читать всю таблицу не нужно.

У требования есть статусная модель — от «Не согласовано заказчиком» до «выполнено», а внутри еще отдельное согласование архитектором и руководителем проекта

Мы зафиксировали правило: архитектурные решения записываются в базе и требуют согласования в ERP-tools.

И главное правило системного промпта:

Cursor не может выполнять требование, которое не согласовали люди.

Cursor покритиковал это правило и назвал его бюрократией, которая тормозит выполнение.

Но позднее сам заметил:

«С ростом команды выгода растет: служебные шаги, которые одиночке кажутся бюрократией, в команде становятся смыслом процесса».

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

Ну разумеется, я не стал выдумать архитектурные требования - я попросил создать их Cursor, он подшаманил MCP и создал 2 десятка требований, который можно почитать и согласиться. А раньше я начинал проекта с команды - Создай сайт который...

Мы потратили несколько минут на согласование файловой структуры проекта — и в этот момент кому-то очень хотелось бы сказать: «Зачем вы это делаем? Начинайте жечь токены на код!»

Но именно в этом и состоит смысл эксперимента.

Мы не хотим ни на секунду отдавать проект на произвол агента. Мы хотим, чтобы агент программировал внутри согласованной модели.

После согласования первичных решений Cursor развернул проект, создал файловый каталог и начал загрузку Django - то есть выполнять директивы согласованных требований

Объекты метаданных

Первым небольшим сражением стала синхронизация терминологии: в ERP-tools сущность называется «Пользователи», а в Django используется User. Такие вещи кажутся мелочами, пока не начинаешь строить систему, в которой несколько моделей должны говорить на одном языке.

В ERP-tools объекты метаданных являются основой навигации. Внутри объекта есть перечень реквизитов с указанием типов данных, в т.ч. с указанием других элементов метаданных. Еще раз - мы не внутри конфигуратора ERP-tools. Мы в режиме Предприятия работаем над Проектом. Рядом работаю другие команды для другими проектами. Никто никому не мешает.

Традиционные «Код» и «Наименование» вопросов не вызвали. А вот остальные реквизиты потребовали отдельного размышления.

Мы решили, что осмысленный реквизит должен быть обоснован требованием — функциональным, а иногда нефункциональным. Именно так мы поступаем на проектах внедрения ERP - все "разрывы" должны быть зафиксированным созданным Требованием, а не просто в телефонном звонке.

Причина очень простая. Cursor с легкостью добавляет в Django-модель то, что считает полезным. Поэтому получилось довольно интересное правило:

AI может свободно генерировать реализацию, но не должен свободно придумывать бизнес-модель - максимум предлагать и советовать

Создание десяти требований только с наименованием занимает считанные минуты.

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

В вайбкодинге с нуля - этап рисования модели объектов метаданных, реквизитов, возможных функций - это наверное многодневная работа именно внутри ERP-tools - подальше от бешенного программатора.

Миграции

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

Поэтому в системном промпте появилось правило: любая задача в Cursor должна проходить контроль.

Для этого агент создает элемент дорожной карты, формулирует предложение в виде заметки и ждет разрешения. В ERP-tools для этого уже есть отдельный механизм — справочник «Дорожные карты» и связанные с ним «заметки».

С точки зрения руководителя проекта, да и самого «механизатора» — программиста, который управляет агентом с практически безграничными возможностями, это уже не бюрократия, а разумные предосторожности.

Агент предлагает. Ему разрешают. Только после этого он делает.

Функция

Первая таблица «Пользователи» готова. Теперь самое важное — функции. В нашей методологии функция — это законченное действие пользователя над объектом метаданных. Я специально повторяю это определение, потому что в слово «функция» легко впихнуть вообще что угодно. Здесь речь именно о пользовательском поведении.

Бизнес-процесс является контейнером для функций, а функция отвечает на более простой вопрос:

Что конкретно пользователь должен иметь возможность сделать в приложении?

Например, у нас есть таблица «Пользователи». Одна из функций — «Создание пользователя».

Это довольно простой справочник, и самое ценное в нем — правильно сформулированное название. Для человека оно сразу задает смысл.

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

Поэтому пропускаем тут создание второго объекта метаданных Аккаунты и общей функции "Регистрация управляющего аккаунтом и нового аккаунта".

Для LLM хорошее название тоже экономит контекст: модели не приходится читать длинное объяснение того, что означает функция, если ее название уже достаточно точно сформулировано.

Инструкция

Следующий вопрос был интереснее и на самом деле ключевым.

Сможет ли LLM сама придумать инструкцию к функции и разобраться, что нужно делать на первом шаге, а что на последнем?

Cursor справился.

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

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

После проектирования инструкции Cursor попросил разрешения выполнить задачу через механизм «Заметок».

Я разрешил - и он ушел программировать.

Примерно через 10 минут и около 8 млн токенов он закончил реализацию отдельной несложной функции (для справки - в 1С ERP в среднем 700 несложных функций для пользователей. Основная сложность, что их 700).

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

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

А требования, которые нашли отражение в инструкции, получили финальный статус «Выполнено включением в инструкцию» - это так умеет ERP-tools.

Получается цепочка:

Функция
   ↓
Объект метаданных
   ↓
Реквизиты
   ↓
Требования
   ↓
Инструкция
   ↓
Согласование
   ↓
Код
   ↓
Тестирование
   ↓
Визуальная инструкция

И вот это, пожалуй, главный результат лабораторной работы.

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

А как же права доступа?

Спокойно.

Права тоже не должны появляться в голове агента. В ERP-tools для них есть отдельное место — профили доступа, а сами права назначаются непосредственно к функции: кто может ее выполнять.

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

Это решение находится в модели проекта и в нашем проекте ролевая модель довольно богатая и работает РЛС по проекту и аккаунту. И уже позже Cursor порекомендовал добавить в рабочие таблицы новый реквизит Account, хотя там был Project, у которого Account - владелец, но Cursor убедил, что самостоятельный реквизит сделает работу быстрее. Мы это зафиксировали в Нефункциональном требовании (так как вопрос безопасности), Добавили новый реквизит в Объект метаданных в ERP-tools и сделали миграцию. то есть мы это обсудили в чате, он создал нужные изменения в ERP-tools, я согласовал новое требование и он поменял миграцию.

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

Контекст

Теперь можно перейти к самому интересному техническому вопросу. Как Cursor вообще получает все это знание? MCP дает ему возможность обращаться к ERP-tools запросами.

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

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

Cursor даже предложил выполнять каждую новую задачу в новом чате - тоже переживал за ход эксперимента, как и его коллега - ChatGPT.

И замеры на сопоставимой задаче показали интересный результат: вместо примерно 8 млн токенов ушло около 4 млн. Это не benchmark и не универсальная цифра — результат конкретного эксперимента. Много или мало - я не знаю.

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

Поэтому ERP-tools здесь выполняет еще одну роль:

Это не только хранилище документации. Это механизм управления контекстом AI-программиста.

Цикл разработки

Таким образом, сформировался довольно простой цикл. Мы не просим LLM сразу написать приложение целиком - как модные блогеры неизвестные супер-приложения.

• Сначала формируем модель.

• Создаем объект.

• Определяем его реквизиты.

• Фиксируем требования.

• Создаем функцию.

• Описываем, что должен уметь пользователь.

• Затем просим LLM предложить реализацию с учетом этой модели.

• После проверки разрешаем программирование.

• После реализации получаем тест и визуальную инструкцию.

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

Нефункциональные требования

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

Просим агента сформулировать предложение как требование. После этого требование согласуется в ERP-tools и остается навсегда.

Таким образом, решение перестает быть частью временного разговора с моделью. Оно становится частью проекта. Это очень важная граница. И несколько раз при выполнении задачи Cursor сказал, что данное решение нарушает архитектурный контракт - то есть он действительно держит в контексте эти данные.

Чат — место, где агент думает. ERP-tools — место, где принятое решение становится частью проекта, также куда смотрят люди и визуализируют приложение, которое с каждым часом набирает все большую функциональность

Функциональные требования

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

• Функция описывает законченное действие.

• Требования объясняют, что именно в этом действии должно происходить.

• Инструкция показывает действие человеку.

• А код реализует его для системы.

Документация

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

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

Используются системные промпты, skills, Markdown-файлы, MCP-коннекторы к трекерам и базам знаний. Поэтому сама идея внешней памяти для AI не нова.

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

• Markdown хранит описание.

• ERP-tools хранит модель.

В Markdown можно написать:

«У объекта есть реквизит Ответственный».

В ERP-tools этот реквизит является частью объекта модели, имеет тип, связан с требованиями, функциями и другими объектами.

Cursor может создать после разработки еще один огромный Markdown-файл и написать в нем, как устроено приложение. Формально документация будет.

Но кто будет ее читать? Маркдаун документы лично я читаю с трудом. "А чего их читать - llm мягко стелит, да жестко спать"

В ERP-tools человек может смотреть на модель проекта с разных сторон: через функции, объекты, требования, права, инструкции, бизнес-процессы - возможно еще пару лабораторных работ - и будем работать как Том Круз в фильме Особое мнение.

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

Я честно попросил Cursor сравнить варианты работы с контекстом

Технический уровень: зачем нам DevInfo

Есть еще один, более технический уровень.

В ERP-tools существует регистр сведений DevInfo, который позволяет сгенерировать «код инъекции» — специальную метку, которую Cursor может вставлять в код рядом с местом реализации требования.

Cursor фиксирует, в каком файле было внесено изменение. Зачем это нужно?

Представим, что через полгода архитектор видит подозрительный кусок кода. Обычный вопрос:

«Зачем это здесь?»

В нашей схеме можно задать обратный вопрос:

«Какое требование привело к появлению этого кода?»

Именно здесь появляется трассируемость:

Требование
    ↕
Функция
    ↕
Инструкция
    ↕
Код

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

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

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

Графические схемы

Есть еще один интересный результат. Cursor быстро разобрался, как создавать графические схемы внутри ERP-tools в нашем «1С»-ном формате и BPMN.

То есть агент способен работать не только с текстом и кодом. Он может создавать и редактируемые визуальные артефакты проекта. Это еще один аргумент в пользу того, что структурированная модель проекта может быть полезнее коллекции Markdown-файлов.

Фактически Cursor стал аналитиком, с которым можно обсудить любой вопрос - промпт его научил методологии, а коннекторы позволяют запросить и записать любую информацию. Я пока не заставлял бедного Cursor писать ТЗ внутри Требований (как заставляю аналитиков), но даже сомнения не возникнет - он это сделает.

Несколько вайб-программистов

Теперь вернемся к исходной проблеме. Что произойдет, если над одним проектом работают несколько AI-программистов? В обычном сценарии каждый агент имеет свой чат. У каждого накапливается собственный контекст. Один агент знает, почему вчера было принято определенное решение. Второй об этом не знает.

Третий может вообще предложить сделать все иначе. и скорее всего каждый разработчик будет делать свой Монолит, полученная программа будет 3 монолитами, то есть с 3 микросервисами - ведь это способ обосновать нарушение принципа DRY.

В нашей схеме общий контекст находится снаружи и жутко упорядочен. Архитектурные решения согласованы. Функции определены. Требования связаны с объектами. Права находятся в модели. Инструкции являются частью проекта и завязаны с требованиями.

И честно говоря становится понятным - а что вообще делает данная система?

Поэтому агенты могут быть разными, а модель проекта — общей. Получается конструкция:

                  ERP-tools
              общий контекст
          ┌──────────┼──────────┐
          ↓          ↓          ↓
       Cursor     Cursor     Cursor
       агент 1    агент 2    агент 3
          ↓          ↓          ↓
        код        код        код
          └──────────┼──────────┘
                     ↓
                    Git

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

Темы следующих лабораторных работ

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