Привет, меня зовут Андрей Калинин, я отвечаю за цифровые финансовые активы и сопровождение инновационных продуктов. Управляю командами разработки и развития. Мы любим и умеем запускать пилоты в бигтехе: платформа ЦФА А-Токен, API для работы с самозанятыми, безопасные сделки, блокчейн‑платформа ФНС.

Начну свою историю с пролога.

Часть первая: пролог

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

Есть такая вещь, как цифровые финансовые активы (ЦФА). Вы могли их видеть на витрине в своём мобильном банке, в приложениях для инвестиций и в агрегаторах финансовых услуг. Это новые инвестиционные инструменты, похожие на облигации, но более разнообразные.

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

Если облигация вам даст только деньги, с ЦФА вы можете получить деньги или актив, например, слиток или квартиру.

Главная особенность — прямое распоряжение активами с применением электронных подписей УКЭП, УНЭП и ПЭП, обязательное исполнение сделок смарт‑контрактами, неизменность блоков и содержимого транзакций. В блокчейне скорректировать введённые данные не так‑то просто из‑за расширенной криптографии, а ещё есть законодательная защита инвесторов со стороны Центробанка.

Чтобы учитывать ЦФА клиентов, вы должны зарегистрироваться как оператор. Все операторы содержатся в реестре, мы зашли туда четвёртыми (в мае 2025-го зарегистрировано 15 операторов). По данным Банка России, на конец 2024 года мы занимали 40% рынка, а по оценке Cbonds — 50%.

Чтобы мы могли предлагать ЦФА, а клиенты ими оперировать: изучать, покупать, продавать, мы запустили свою платформу А-Токен. Как она работает — не так важно для истории, нас интересует документация.

При разработке мы описывали сервисы по следующей технологии:

1. Документация создаётся в AsciiDoc, в редакторе, например, AsciiDocFX.

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

3. Готовая папка с документацией сервиса загружается в Git в подготовленный репозиторий сервиса.

4. Сборка документации в виде статической страницы и архива выполняется из Git при релизе с помощью Jenkins.

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

При раскатке в прод и передаче на функциональное сопровождение возникли вопросы: «А как сопровождать чёрный ящик?». Первоначально вендор оценил трудоёмкость задачи как незначительную, но после детального анализа увеличил затраты в 10 раз, а затем, помучившись, ещё в 2 раза. Мы со множеством итераций три квартала закрывали техдолг по документации вендора. Пометим эту историю, как историю №1.

История №2 начинается, когда вторая команда того же вендора по проторенной дорожке пришла с новой разработкой и тоже без документации.

Пролог закончен, приступаем к повествованию.

Часть вторая, в которой «криптаны» не пишут документацию для сопровождения, а их и не просили

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

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

Но случился сюжетный поворот, в котором по завершении разработки вендор ожидаемо распустил команду (звук тарелок ударной установки).

«И что? Натравите юристов, пусть заставят подготовить документацию, её подготовка прописана в техзадании. Ведь прописана?».

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

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

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

В итоге получился прямо «треугольник отчаяния»:

• Есть крутая штука, которая нам очень нужна — работающая система, она устраивает бизнес, и он готов её внедрять.

• Вот только брать её никто не собирается, потому что чёрный ящик, сэр, без документов.

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

Чья это проблема? Вопрос для дискуссии. Но независимо от ответа работу надо работать, а мы в тупике.

Часть третья, в которой мы ищем решение и нам неожиданно везёт

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

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

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

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

Есть несколько выходов, которые мы расписали, когда прикинули ТРИЗ к носу.

Простой способ

Если бы команду вендора не распустили.

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

Сложный способ

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

Второй вариант сложного способа

Если бы проект разрабатывался в контуре банка, мы наняли бы условных техписов с рынка, они так же привлекали бы архитектора, разработчиков, смотрели, как всё работает, какие и зачем у нас условия. Всё это нетривиальная задача.

Пара новых неизвестных для сложного способа

Есть разные подходы к коду. Если код написан по шаблонам, с применением паттернов, наименованием переменных — это один вопрос описания.

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

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

Часть четвертая, в которой мы подбираемся к ИИ

Мы пошли по второму варианту, когда у нас не было команды разработки. Но нам повезло в том, что мы наняли технического писателя из расформированной команды вендора. Нет, не переманили, она сама пришла (работы‑то нет), а мы наняли. Мы достаточно плотно работали, и найти общий язык не составило труда.

Как пишем? Запускаем из исходного кода собранные сервисы на изолированном стенде и пишем документацию силами техписа и solution‑архитектора.

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

Единственное, что мы смогли стребовать у вендоров путем переговоров, — схемы процессов в вижене в виде «диаграмм». Для примера покажу малую часть.

Соответственно, наша задача — подготовить вижн на основе того, что нам передал вендор. Здесь можно обойтись без ИИ — ведь для этого есть шаблоны.

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

Ко всем системам есть стандартные требования (например, дока должна поставляться в виде приложения). Примерно так, на скрине маааленькой части документации ниже.

OТАР передаётся в несколько подразделений, но главное — документы должны принять DevOps'ы. Систему сопровождают администраторы (не разработчики) первой линии сопровождения, после обращений пользователей изучают проблему по документации, регистрируют дефект и отправляют разработчикам. А если документации нет, они не понимают, как система работает, не могут её ни сопровождать, ни консультировать по ней.

Вот для этого в том числе и необходима документация.

При подготовке OTAP мы двигались как по рельсам — по двум параллельным путям:

• Первый путь — через UI в GenAI‑ассистенте для разработчиков AlfaGen (наш внутренний продукт), загружая разные данные и схемы в UI и получая части описания.

• Второй путь — через это же подключение к Git, который готовит описание API по исходному коду.

Часть, которая работает с API, готовит только треть документации и по качеству почему‑то пока работает хуже.

Через UI можно написать всю документацию, но её надо в любом случае проверять. Условно, в документации описывается метод и примеры запросов и ответов. Этот участок проверяет функциональное сопровождение — сверяет, корректно ли система работает, загружает в Swagger.

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

Что же в итоге?

Когда мы думали над идеальным конечным результатом с документацией, нам пришла идея — пусть документация готовит себя сама, и мы сразу подумали о генеративном ИИ. Обычные инструменты не подходили. Внутрянка продукта — это NDA. Решением стал наш GenAI-продукт для сотрудников банка AlfaGen, его нейронки работают в контуре и не отдают промпты и ответы наружу.

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

AlfaGen сэкономил нам где‑то 20–25% времени на запуске. Да, магии не будет, заклинание «Акцио документум» не сработает (а вот «Авада криптабра» можно было применить гораздо раньше), и ИИ всю работу не сделает. Не бывает такого.

Мораль? Не экономьте на техписах и прописывайте техзадание на продукт подробнее (а если с этим проблемы, попросите совета у IT).

Пишите, с какими проблемами сталкивались вы при написании документации?