Меня зовут Паша, и в сфере IT я уже 14 лет. Из которых 7,5 лет проработал в госсекторе, можно сказать, фулстек-специалистом — от ремонтов компьютеров до разработки сайтов и приложений. После ушел работать в банковский сектор, в котором уже 6,5 лет работаю в роли системного аналитика. В этой статье хочу рассказать, как в размеренную жизнь системного аналитика ворвался ИИ и как он помогает в повседневной жизни быстрее решать рутинные задачи. Например, описание API и состоваление UML диаграмм в рутинные Confluence.
Для начала расскажу из чего состоит работа системного аналитика на проекте одного крупного банка. Начну с того, что на части направлений в банке системный аналитик также выполняет роль тимлида команды. Что, в свою очередь, съедает какую-то часть рабочего времени, которого и так часто не хватает на выполнение системного анализа, описание документации на Confluence, постановки задач в Jira и написании технической документации для выкатки разработки в прод.
На одном из митапов системных аналитиков руководством было предложено перенести документацию мидловых API с Confluence в Git — так называемая документация рядом с кодом — и новые документации писать только в гите. Было принято решение провести пилотирование данного процесса на нескольких командах разных направлений. В моем направлении была выбрана моя команда.
Немного о документации рядом с кодом. Расскажу о плюсах и минусах такой документации.
Документация рядом с кодом
Для системного аналитика:
Плюсы:
· Контроль над содержанием — единый источник документации снижает риск противоречий в требованиях.
· Стандартизация формата — AsciiDoc и PlantUML позволяют структурировать информацию в едином стиле, что упрощает её восприятие командой.
· Упрощение коммуникации — визуальные схемы PlantUML помогают донести сложные процессы до разработчиков и тестировщиков без искажений.
· Интеграция с процессами разработки — документация хранится рядом с кодом, что облегчает её привязку к конкретным модулям или функциям.
· Совместимость с версионным контролем — текстовый формат позволяет отслеживать изменения в Git, что улучшает совместную работу и позволяет отслеживать изменения.
Минусы
· Требуется время на освоение синтаксиса AsciiDoc и PlantUML.
· Поддержка актуальности — при частых изменениях в коде диаграммы и описание могут устаревать, если их не обновлять вручную.
· Изменить атрибутный состав в Confluence занимает несколько минут, тогда как в Git — в несколько раз больше.
· Необходимость технических навыков — требуется понимание логики кода для точного описания методов и процессов в PlantUML и AsciiDoc.
Для разработчика:
Плюсы
· Быстрый доступ — документация находится в том же репозитории, что и код — не требуется искать информацию в сторонних источниках.
· Четкие требования — схемы PlantUML и описания в AsciiDoc снижают неоднозначность в понимании задач.
· Прозрачность изменений — версионный контроль документации и кода в одном месте упрощает отслеживание истории правок.
Минусы
· Сложность восприятия — большие вложенные схемы в текстовом виде могут быть неудобны для быстрого чтения. На Confluence все выглядит более наглядно и удобнее для чтения диаграмм.
Для тестировщика:
Плюсы
· Четкие сценарии — диаграммы процессов и состояний помогают проектировать тест-кейсы, соответствующие бизнес-логике.
· Единый источник истины — документация в репозитории снижает риск работы с устаревшими требованиями.
Минусы
· Зависимость от актуальности — если документация не синхронизирована с кодом, тесты будут некорректными.
· Требуется техническая экспертиза — для работы с PlantUML и AsciiDoc нужны базовые навыки, что может замедлить новых членов команды.
Как аналитику, который никогда не писал документацию в гите, а еще и на языке разметки AsciiDoc, идея перенести документацию в Git показалась не слишком хорошей.
Во-первых, потребовалось потратить какое-то время на изучение языка и работы в IDEA.
Во-вторых, уходило очень много времени на перенос документации, в которой были большие таблицы. На перенос одного метода могло уходить в среднем не менее 3 часов, а в неделю на данную активность выделялся только 1 день. При этом в API в среднем от 5 до 10 методов.
И в-третьих, нужно было получать 2 апрува от аналитиков, чтобы залить документацию на стенд, что не всегда происходит быстро и в тот же день в силу занятости.
Пилот продлился несколько месяцев, и мы пришли к заключению, что уходит слишком много драгоценного времени, и пока отказались от идеи использования документации рядом с кодом.
Появление ИИ в жизни системного аналитика
Через некоторое время начало набирать популярность ИИ. И в банке решили поднять свою версию ИИ для упрощения работы всех компетенций. Начался пилот, где также участвовала моя команда.
Цель пилота была в сокращении Lead Time команды.
Было испробовано много подходов использования ИИ в работе системного аналитика. Поделюсь несколькими из них.
Большая часть времени системного аналитика уходит на написание документации в Confluence.
Структура описания 1 метода состоит из:
1. Схема взаимодействия UML.
2. Описание логики работы метода.
3. Входящие и исходящие параметры метода с примерами запроса и ответа.
4. Маппинг исходящих и входящих запросов в смежные сервисы с примерами запроса и ответа.
Зная все параметры, для описания метода уходило времени:
1. Описание схемы взаимодействия без использования ИИ — в среднем 15 минут, с использованием ИИ — 6 минут.
2. Описание логики работы метода без использования ИИ — 8 минут, с использованием ИИ — 3 минуты.
3. Описание входящих и исходящих параметров с примерами без ИИ — час, с ИИ — 35 минут.
4. Описание маппинга исходящих и входящих запросов с примерами без ИИ — примерно 40 минут, с ИИ — 25 минут.
Но обязательный пререквизит к экономии времени и использованию ИИ, как я писал ранее, — знание всех параметров и всех внешних интеграций, так как ИИ не имел доступа к Confluence, и все равно уходило много времени на поиск информации.
Задача с переносом документации в Git снова встала на повестке дня. И тут ИИ пришелся как нельзя кстати. Достаточно было написать простенький промт, скопировать часть описания с Confluence, и через несколько минут уже была готовая документация на языке разметки AsciiDoc.
Но и тут не обошлось без нюансов: количество символов, которое поддерживает ИИ, всего 15 000, а на странице в Confluence их больше в несколько раз. Поэтому перенос документации в Git без использования ИИ (диаграмма + логика + контракты) занимал 1 час, с использованием ИИ — 25 минут в среднем.
Также ИИ пришел на помощь с совсем отсутствующим описанием старых модулей. На основе кода ИИ генерировал описание и отрисовывал модель взаимодействия в формате PlantUML. После системный аналитик проводил валидацию сгенерированного, приводил к стандарту описания, и после всех манипуляций на стенде появлялась документация сервиса. Точные замеры не производились, но, прикинув, сколько времени пришлось бы копаться в коде, возможно, задействовать другие компетенции в раскопках работы логики сервиса, можно с уверенностью сказать, что был сэкономлен не один день работы.
Немного расскажу про ИИ которую используем.
Первая версия ИИ была сделана на базе Llamma с ограничением в 5000 символов входящего запроса. Мы начали пробовать создавать промты с нуля, но нужного результата практически не получали. ИИ обучался долго и периодически мог додумывать ответы, например добавлять какой-нибудь атрибут, так как ранее в похожем запросе была похожая структура ответа. Через некоторое время были сделаны стандартные промт шаблоны для ускорения работы с ИИ. Приведу несколько примеров:
1. PlantUML в системные требования.
Промт – необходимо преобразовать диаграмму PlantUML в системные требования, следуя правилам: 1. Если PlantUML содержит текст типа “system1-> system2: Some actionnGET some/urln(//attributes//)”, преобразуйте это как: “Система выполняет запрос к <system2 имя участника> методом GET some/url с параметрами attributes” 2. Если какой-то текст отсутствует, пропустите его 3. Если PlantUML содержит текст типа “system2 –> system1: attributes”, преобразуйте это как: “Система получает значения attributes” 4. Если PlantUML содержит текст типа “system1 –> system1: something”, преобразуйте это как: “текст something” 5. Если PlantUML содержит оператор alt, например, “alt condition1…, else condition2 …” и т.д., преобразуйте это как: “Если condition1, то …, иначе если condition2, то …” 6. Если PlantUML содержит оператор opt, например, “opt condition1 …”, преобразуйте это как: “Если condition1 …” 7. Используйте имена участников из блока участников текста PlantUML. 8. Используйте нумерацию для интеграции систем. 9. Используйте маркированную нумерацию для обработки ответа или для отображения списка атрибутов. 10. Если PlantUML содержит текст типа ‘== something ==’, преобразуйте это как очень маленький заголовок.
2. Подготовка спецификации API
Промт – опишите спецификацию API, включающую следующее: 1. Название API на английском языке. Название раздела – “Название API”. 2. Название метода на английском языке, краткое описание метода и тип HTTP-метода. Название раздела – “Метод”. 3. Параметры запроса и ответа. Название раздела – “Параметры запроса и ответа”. Укажите тип данных для параметров запроса и ответа на английском языке, обязательный статус параметра, описание параметра и предоставьте пример параметра. Организуйте все параметры в табличном формате. Включите примеры запросов и ответов. 4. Описание возможных ошибок. Название раздела – “Ошибки”.
Следующая версия ИИ была сделана на базе DeepSeek R1 с ограничением в 15000 символов входящего запроса. Мне понравилось работать больше именно с этой версией, так как ответы она давала более близкие к ожидаемым.
Примеры промтов, которые активно используются на данной версии:
1. XHTML в AsciiDoc (для переноса документации в GIT)
Промт – преобразуй XHTML из Confluence в AsciiDoc (.adoc). Сохрани исходное форматирование из XHTML. Не добавляй никаких описаний и дополнительного текста – только переформатируй из одного типа в другой. Выведи мне только текст для вставки в AsciiDoc без объяснений.
2. Документация для ручки с использованием ASCIIDOC
Промт – сгенерируй документацию для эндпоинта микросервиса с использованием ASCIIDOC, используя plantuml. Ниже тебе будет приведен текст, описывающий функциональность данного эндпоинта.
Основные проблемы на данный момент, с которыми сталкиваемся при работе с ИИ.
1. При переносе документации в GIT необходимо проверять весь сгенерированный текст, так как ИИ мог додумать и добавить свой атрибут или описание. Решение проблемы каждый раз начинать новый чат, но при этом заново приходится объяснять какой результат я хочу получить
2. При генерации описания старых модулей ИИ делает описание ближе к разработчику, а не к аналитику, добавляя в документацию много лишних технических параметров и описаний. Решения проблемы пока не найдено, так как описание пишется на основе кода. Остается только вычитывать и преобразовывать все, что сгенерировал ИИ на более понятное описание.
Сейчас ИИ активно развивают дальше, и совсем недавно появилась возможность с помощью ИИ искать информацию на Confluence. Пока это бета-версия, но есть уверенность, что в скором будущем часть рутинных задач будет выполняться в разы быстрее.
Lead Time системного аналитика сократился. Часть задач стало выполнятся быстрее. Но так как это пилот и многое было попробовано впервые, точных замеров пока нет.
Со стороны команды на данный момент было отмечено, что документация стала быстрее отдаваться разработчикам.
В самом начале пилота я скептически отнесся к данному нововведению. Но спустя некоторое временя, работая вместе с ИИ, получил понимание, что это хороший помощник для работы, который помогает сэкономить много времени.
Автор: XBlade66
