Когда вы последний раз читали документацию размером более страницы А4 без привлечения LLM? Вопрос риторический.
Кажется пришло время вычеркнуть написание документации из списка тех. долга.
В статье я попытался переосмыслить саму идею документации для enterprise разработки, а также рассказать о практическом решении поднятого вопроса для любой системы на платформе 1С 8.3 и выше.
Суть классической документации
Меня зовут Артем, я с командой уже год заставляю себя и LLM разбираться с нюансами устройства 1С. Тут история о том как я попал в 1С, но сегодня про документацию.
Начнем с начала. Любой ит-продукт рождается из требований. Когда продукт сложный и в цепочке его создания более одного человека, люди придумали использовать артефакты – документы разной степени детализации описывающие на естественном языке, что же надо сделать разработчику. Эти документы несут несколько бенефитов:
Единый источник правды для всей команды
Снятие когнитивной нагрузки для писателя (сразу все не придумаешь, пишем шаг за шагом, корректируем)
Снятие когнитивной нагрузки для читателя (сразу все в голову не вгрузить, а по частям заходит хорошо)
Этот тип документации, назовем его ЧТЗ, нужен разработчику, чтобы выполнить перевод с языка естественного на язык который понимает компилятор (в нашем случае платформа 1С). Этот процесс перевода – называется разработка или написание кода.
Технический долг обычно возникает, когда разработка завершена. Несколько ЧТЗ работают как надо, и часто не совсем так как написано в ЧТЗ. Более того, иногда ЧТЗ заменяется устной беседой аналитика и разработчика. То что получилось, по всем бест практикам должно быть обратно переведено на естественный язык для следующих этапов развития системы.
Но зачем делать лишнюю работу которая не факт что пригодится кому-то, если основная ценность в виде работающего кода уже получена. В погоне за сроками/маржинальностью, написание итоговой тех документации по системе оставляют до лучших времен. На моей практике 9 из 10 корпоративных систем не имеют достаточной и актуальной документации. В лучшем случае есть только пользовательские инструкции, чтобы пользователи мозг не выносили разработчикам.
Вывод: тех документация нужна для перевода с естественного языка на машинный и обратно. И так по кругу. Но ее не пишут, потому что некогда, а перевести можно потом и на лету.
Недостатки технической документации
Кроме того что ее создание отнимает время и не приносит ценности в моменте, есть ключевой недостаток о котором мало кто задумывается:
Это проекция реальности на бумагу. Внимание, проекция, которая передает только часть реального функционала системы. И чем больше она передает, тем зануднее и зубодробительнее этот артефакт с неприличными расходами на его поддержку.
Представьте, система протестирована тестировщиками и даже реальными пользователями в миллионе кейсов, устранена тьма багов и все это запечатлено в коде, а не в документации.
Отсюда вывод: лучшая документация — это код. Правда, чтобы читать код нужен переводчик, он же разработчик. До недавнего времени нужен был...
LLM — решение?
Почему бы просто не взять и не забить на классическую документацию, отдав LLM функцию перевода кода на естественный язык. Можно, если соблюдены 2 условия:
весь код приложения умещается в эффективное контекстное окно (примерно 120 тыс токенов)
LLM предобучена на этом языке программирования
Второе ограничение почти снято. Современные LLM неплохо разбираются и в COBOL и в 1С. Да не идеально, но достаточно чтобы уметь переводить большую часть кода на понятный русский язык.
Но что делать, с контекстным окном? Тоже есть решение – «проиндексировать» содержимое всего репозитория: правильно разбить его на кусочки, создать несколько уровней навигации, научить агентную систему ориентироваться по указателям и нырять в нужное место «документации». В нужное, значит, в то о котором спросил читатель.
В результате мы получаем новый паттерн работы с тех документацией. Мы более не создаем ограниченные проекции реальности в текст. Мы достаем знания из первоисточника в тот момент и в том разрезе, в котором нужно прямо здесь и сейчас.
Где подвох?
Сделать эмбединги и завайбкодить идею можно мигом. В принципе как и любого новомодного агента с RAG’ом, MCP и промптами. Боль начинается, когда это не работает на реальных пользовательских вопросах.
Да, код не всегда идеален и устройство вашего приложения может быть нетривиальным. 1С в отличие от Python работает не только так как написано в коде, но и так как задумано платформой. Платформа диктует неочевидное поведение системы, которое LLM не поймет, глядя исключительно в код. СКД, громоздкие XML метаданных, RLS, это только часть особенностей, которым нужно обучить вашего агента. Отдельная боль это объемы: флагманские конфигурации могут весить гигабайты, а контекстное окно сами знаете какое.
Даже если все сделать идеально, ответа на вопрос может просто не быть в коде. В этом случае напрашивается поиск в интернете по тщательно отобранным источникам.
Что еще может пойти не так. Пользователь может спросить что-то неконкретное или то что можно понять неоднозначно. Здесь прежде чем искать ответ, нужно добиться от пользователя уточнений и при этом не задушить его дотошными расспросами, ведь он привык что разработчик его с полуслова понимает.
Самое сложное. По крайней мере в нашей команде, самое сложное всегда это выбрать метрики качества и собрать датасет на котором будем их замерять. Ближе к релизу конструкция такого агента становится настолько нетривиальной, что без метрик уже не понятно как внесенные изменения влияют на итоговое качество. В идеале метрики должны быть на каждом компоненте системы, каждый шаг «размышлений» агента должен быть измерим. Интересно дебажить случаи, которые улучшают метрику шага, но при этом ухудшают итоговую метрику, обычно причина в том что датасет кривой или сама метрика не подходящая.
Вот базовые метрики, которые мы измеряем:
Полнота (Recall) – доля найденных релевантных кусочков данных из всех возможных. Показывает, не упустила ли система важный контекст.
Точность (Precision) – доля полезных данных в вашем контекстном окне. Показывает, сколько «мусора» притащил поиск вместе с полезными данными.
Достаточность (Context Sufficiency) – хватает ли извлеченных данных, чтобы LLM сгенерировала верный ответ без галлюцинаций.
Качество ответа (Answer Correctness) – финальная оценка. Решил ли сгенерированный текст задачу пользователя. Тут можно оценивать правильность по нескольким критериям.
Почему это трудно. Потому что собирать датасеты для замера нужно почти вручную, валидировать с экспертами. Это скучно и нудно. Вайбкодить MCP-сервера куда веселее. И это не разовая задача, датасет нужно дополнять новыми кейсами, которые вы находите в процессе тестирования, а потом и на проде, когда пользователь с ухмылкой заявляет: этот ваш ИИ неправильно ответил на мой вопрос.
Рассказываю на реальном примере
Вот настоящий вопрос пользователя к конфигурации УХ 3.3:
Какой реально оборот выдаст источник данных, настроенный на получение оборота счета с определенным корсчетом по данным регистра бухгалтерии МСФО за период? Дебетовый оборот счета с кредита корсчета, кредитовый оборот счета в дебет корсчета, разницу дебетового и кредитового оборота счета в корреспонденции с корсчетом, или что-то иное?
Наш ответ:
Источник данных выдает строго односторонний оборот по корреспонденции: либо дебетовый оборот счета с кредита корсчета, либо кредитовый оборот счета в дебет корсчета, что определяется реквизитом ДтКт. Разницу дебетового и кредитового оборотов источник напрямую не формирует.
Механика получения оборотов с корсчетом
При настройке элемента справочника ИсточникиДанныхДляРасчетов для регистра бухгалтерии МСФО система возвращает суммарный оборот строго по указанной стороне корреспонденции . Итоговый результат зависит от комбинации реквизитов ВидИтога и ДтКт :
Дебетовый оборот счета с кредита корсчета: формируется, если реквизит ДтКт установлен в значение «Дт» (или ВидИтога = ДО). Система суммирует проводки, где анализируемый счет находится в дебете, а корсчет — в кредите .
Кредитовый оборот счета в дебет корсчета: формируется, если реквизит ДтКт установлен в значение «Кт» (или ВидИтога = КО). Суммируются проводки, где счет находится в кредите, а корсчет — в дебете .
Разница дебетового и кредитового оборотов в корреспонденции с корсчетом напрямую источником не выдается . Для получения разницы необходимо создать два отдельных источника (для ДО и КО) и настроить их вычитание через формулу в справочнике ПоказателиОтчетов.
Пошаговая настройка источника
Для корректного извлечения оборота выполните следующие действия в форме элемента ИсточникиДанныхДляРасчетов :
Установите СпособПолучения в значение «Данные регистра бухгалтерии» .
Укажите РегистрБухгалтерииБД = МСФО .
Заполните реквизиты Счет и КоррСчет .
Выберите ВидИтога = «Оборот» (или «КорДО»). При других итогах (например, сальдо) корсчет будет очищен .
В поле ДтКт укажите требуемую сторону оборота («Дт» или «Кт») .
Укажите РесурсРегистра (например, СуммаВВалютеУчета) и проверьте выборку командой «Проверить операнд» .
Дополнительные нюансы
Согласно информации из интернета, при использовании макроязыка бухгалтерских итогов в формулах можно применять нотацию вида <Вид итога><Счет>(<КоррСчет>), что позволяет системе однозначно определить требуемый оборот . Также, по данным из открытых источников, если в настройках источника выбрать вид итога, соответствующий «чистому» обороту без уточнения Дт/Кт, система может обратиться к ресурсу СуммаОборот виртуальной таблицы ОборотыДтКт, который представляет собой разницу ОборотДт - ОборотКт . Однако для прозрачности расшифровки показателей (drill-down) в отчетах рекомендуется использовать два независимых источника.
Оценка ответа клиентом (дословно):
В форме настройки источника нет доступного переключателя Дт/Кт, когда выбираешь Вид итога "Оборот в корреспонденции" (он есть в случае, когда вид итога "Оборот по счету"). Ответ системы частично правильный, но частично нет. Вообще говоря, доверять ему нельзя. Увы.
Перевожу:
Основной тезис в ответе – верный. Основные шаги инструкции по настройке – верные.
Ошибка в том что система описала элемент формы, которого в пользовательском режиме просто не видно. В итоге получается что пользователь не доволен, хотя ответ на 95% верный. А что если убрать инструкцию по настройке? Ошибка исчезнет, но удовлетворенность пользователя будет не 100%, хотя и выше чем в нашем примере. Все не так однозначно и в каждом кейсе приходится балансировать между удовлетворенностью (качеством), себестоимостью, усилиями на R&D и сроками выхода на рынок.
Важно прогонять расчет метрик после каждого значимого изменения, чтобы понять в какую сторону мы сдвинулись по качеству. Когда датасет большой, это съедает немало токенов и может влетать в копеечку.
Если вам нужна документация по вашей 1С и вы хотите сэкономить время и деньги, приглашаю попробовать наш заменитель документации: чат с 1С конфигурацией - chat.1yes.pro там есть бесплатный пакет вопросов, чтобы вы помогли нам без лишних бальеров замерить еще более важную метрику – ценность для пользователя.
