В какой-то момент у нас, как и у многих команд, появился соблазн проверить: а можно ли уже не просто просить AI «написать user story», а действительно встроить его в рабочий процесс аналитика? Например, дать агенту вводные по задаче, макеты в Figma, примеры документации и требования к оформлению, и получить на выходе нормальный Use Case, API-спецификацию, PlantUML-диаграмму и аккуратную страницу в Confluence.
Звучит красиво.
Особенно если вы когда-нибудь вручную переносили сценарии из заметок в Confluence, сверяли шаги с макетами, оформляли вкладки с HTTP-запросами, проверяли коды ошибок и пытались не забыть все вопросы, которые «надо потом уточнить».
В статье расскажу, насколько мы близки к этой утопии — как протестировали работу ИИ в реальном аналитическом процессе в нескольких кейсах: для подготовки Use Case, аналитических артефактов, публикации в Confluence и в работе с Figma.
Пролог
Всем привет! Я Золотарёва Виктория, ведущий системный аналитик в команде Financial Transaction Service или просто FinService. В марте 2026 года активно обсуждалось внедрение ИИ в рабочие процессы. Аналитиков это тоже коснулось.
Моя первая реакция была скептической: зачем мне агент, если свою работу я могу сделать быстрее сама?
Первые эксперименты этот скепсис только подтвердили. К примеру, я могла за рабочий день самостоятельно подготовить User Story и полноценный Use Case с контрактами, эндпоинтами, диаграммой и макетами. С агентом та же задача растягивалась на 3-4 дня: нужно было передать контекст, объяснить формат результата, постоянно направлять агента, а затем ещё и внимательно проверять, что он успел придумать по дороге.
Однажды в начале исследования агент предложил неверный контракт. Я явно указала на ошибку и передала актуальное решение. Но в финальной документации снова увидела неправильный контракт с неймингом, похожим на первоначальный. Агент вернулся к собственному старому решению и представил его как подтверждённое мной (а вот это уже опасно).
Проблема AI в аналитике не всегда в том, что он пишет очевидную чушь. Иногда он очень убедительно пишет неправильные вещи.
Также основную аналитическую документацию мы описывали в Confluence, а разработчики работали с кодом и агентами в GitLab. Чтобы агент разработчика мог начать работу, документацию из Confluence приходилось передавать ему как контекст. Затем он заново анализировал требования, формировал Markdown-спецификацию в GitLab и только после этого переходил к реализации.
Получалось, что один и тот же контекст фактически описывается дважды.
В какой-то момент мы с разработчиком задались вопросом: а зачем дважды описывать один и тот же сценарий сначала в Confluence, а потом GitLab? Что, если аналитик сразу подготовит спецификацию, которую агент разработчика сможет использовать почти без дополнительной переработки?
С этого и началось данное исследование — я решила проверить, насколько мы близки к этой утопии, и протестировала, как ИИ работает в реальном аналитическом процессе в нескольких кейсах:
research-фазы для подготовки Use Case;
подготовка аналитических артефактов: user story, use case, API-спецификаций, PlantUML-диаграмм и Confluence-структуры;
публикация в Confluence (здесь мы использовали агентов и, что примечательно, выявили важные технические ограничения, связанные с авторизацией, storage-разметкой, вложениями, кодировкой и передачей больших данных (но об этом в статье);
работа с Figma: настройка токена, обращение к API, чтение нод и экспорт экранов в PNG.
В статье расскажу, где AI действительно помог, где уверенно начал придумывать лишнее, почему Confluence оказался сложнее, чем ожидалось, и какие правила я бы теперь закладывала в любой агентный сценарий для аналитика.
Спойлер: до магической кнопки далеко. Но мы получили отличный (и довольно болезненный) опыт того, как ИИ может помочь в аналитике, а где он пока просто спотыкается и обламывается.
Для самых внимательных в конце оставлю ссылку на диск со всеми style guide и результатом генерации, чтобы вы могли самостоятельно проверить подход в своей работе —>
Четыре гипотезы
Исследование было направлено на проверку нескольких практических гипотез.
Первая гипотеза заключалась в том, что AI может ускорить подготовку аналитических артефактов: user story, use case, acceptance criteria, API-спецификаций и описаний бизнес-процессов.
Вторая была связана с качеством требований: проверялось, может ли AI не только писать текст, но и выявлять пропуски, противоречия, неоднозначные формулировки и открытые вопросы.
Третья гипотеза касалась агентных сценариев — можно ли использовать AI-агента как участника рабочего процесса: чтобы он читал макеты, работал с файлами, формировал спецификации, готовил Confluence-разметку и помогал публиковать результат.
Четвертая гипотеза касалась ограничений. Было важно не только зафиксировать успешные кейсы, но и понять, где агентный подход становится нестабильным: в авторизации, публикации, работе с вложениями, передаче изображений, кодировке или сетевых ограничениях.
В результате исследование охватило не только «полезные сценарии», но и реальные технические сбои, которые важно учитывать при внедрении AI в аналитическую работу.
Использовать ИИ, чтобы написать требования, — сразу нет
В списке выше нет гипотез «Может ли ИИ написать требования с нуля», потому что первый же эксперимент показал, что для аналитической работы недостаточно просто попросить AI «написать требования». Такая формулировка может дать быстрый черновик, но не гарантирует корректность.
К примеру:
если во входных данных отсутствует endpoint, AI может предложить его по аналогии;
если не описаны ошибки, он может добавить типовые коды;
если в макете не виден текст кнопки, AI может восстановить его по смыслу.
Внешне результат выглядит аккуратно, но для разработки и тестирования такие допущения опасны, потому что ИИ подменяет неизвестность своими выдумками.
Поэтому в исследовании был использован более строгий принцип: AI не должен закрывать пробелы самостоятельно. Если данных недостаточно, он должен фиксировать неопределенность и задавать уточняющие вопросы.
Для этого был применен целевой уровень неопределенности — 0,1. Это означает, что перед подготовкой финального артефакта все ключевые вопросы должны быть закрыты или явно вынесены в список открытых вопросов. Если неопределенность выше, агент не должен формировать финальный use case, domain-spec или диаграмму.
Такой подход позволил изменить роль AI. Он перестал быть просто генератором текста и стал инструментом предварительного анализа: помогает собрать вводные, найти недостающие данные и подготовить основу для дальнейшей спецификации.
Spec Driven Development
Следующая идея появилась после разговора с разработчиком, — чтобы ИИ не ушел в свободный полет, мы приручили его методологией Spec Driven Development. В контексте системного анализа он был применен не как подход к автоматической генерации кода, а как способ выстроить управляемую цепочку аналитических артефактов.
Суть подхода в том, что спецификация становится центральным рабочим артефактом. Работа начинается не с написания итогового документа, а с последовательного уточнения того, что должно быть реализовано, какие сценарии должны поддерживаться, какие данные нужны, какие ограничения существуют и какие вопросы остаются открытыми.
В исследовании этот подход был адаптирован следующим образом:
Исследование → Открытые вопросы → Зафиксированные факты → Domain-spec → OpenAPI → Confluence UC
На первом этапе собираются вводные и фиксируются неопределенности. На втором этапе подтвержденные факты переносятся в findings. После этого формируется domain-spec, который становится основой для API-спецификации, диаграммы взаимодействия и страницы use case в Confluence.
Такой процесс снижает риск того, что AI перенесет ошибку из раннего этапа в финальный документ.
Если вопрос не закрыт, он остается в research-фазе.
Если поле API не подтверждено, оно не должно появляться в спецификации.
Если сценарий не согласован, он не должен попадать в Confluence как финальное требование.
Spec Driven Development в этом контексте оказался полезен не как модная методология, а как практический способ дисциплинировать работу с AI
Итак, исследование
Дальше вас ждут несколько кейсов. Пересказывать всё исследование нет смысла, потому постараюсь кратко. Также важный нюанс — один кейс может проверять несколько гипотез.
Кейс №1. Подготовить Use Case? Да, но с нюансами
Задача research-фазы — собрать все данные, необходимые для будущего UC: цель сценария, точки входа, пользовательские действия, данные для отображения, API-вызовы, успешные и ошибочные ответы, предусловия, постусловия, бизнес-правила, ограничения и исключения из scope. Решили проверить, как с этим справится агент и «скинули» ему задачи анализировать вводные, фиксировать подтвержденные факты и выявлять недостающую информацию, при этом агент не должен писать финальный UC.
Для этого были определены рабочие файлы:
README.md — общий контекст и статус (в т.ч. та самая неопределенность).
open-questions.md — журнал вопросов, зависимостей и допущений.
findings.md — только подтвержденные факты.
Такой формат оказался удобен для работы с неполными вводными. Он помогает не терять вопросы, отделять факты от предположений и не переносить спорные решения в финальную документацию.
Основной вывод из этого кейса: до применения такого подхода AI мог сразу предлагать готовый use case, даже если часть информации отсутствовала. После введения research-фазы процесс стал более контролируемым: сначала фиксируются пробелы, затем уточняются данные и только после этого формируется спецификация.
Кейс №2: Подготовка аналитических артефактов
Следующим направлением стала подготовка style guide и промптов для разных типов аналитических документов. Style guide был сделан с помощью модели LLM на основе ранее составленных user story.
Сначала я пыталась описать все правила работы агента одной большой инструкцией, но затем агент начал смешивать требования разных артефактов: правила User Story переносились в Use Case, подход к UC влиял на API-спецификацию. Поэтому каждый тип артефакта получил собственный style guide.
Первые правила я описывала с нуля на основе своего опыта и уже выстроенного формата документации.
Были отдельно оформлены правила для user story, research-фазы, REST API-спецификации и Confluence use case. Это оказалось важным, потому что AI существенно лучше работает, когда ему задан не только контекст задачи, но и точный формат результата.
Для user story были определены правила формулировки пользовательской цели, результата и критериев приемки. Отдельно было зафиксировано, что одна story должна описывать одну пользовательскую цель, а критерии приемки должны быть проверяемыми.
Для API-спецификации были определены правила описания сценария, endpoint, параметров, тела запроса, успешных ответов, типовых ошибок и PlantUML-диаграммы. Отдельно было зафиксировано, что агент не должен придумывать поля или коды ошибок, если они отсутствуют в источнике.
Для Confluence UC были заданы более строгие правила, так как это уже не просто текстовый документ, а страница с конкретной структурой и макросами. В неё должны входить разделы основной информации, истории изменений, предусловия, сценарии использования и схемы работы. HTTP-детали должны оформляться во вкладках, запросы и ответы — в code-блоках, бизнес-правила — в info-блоках, а диаграмма — в PlantUML.
Основной вывод из этого кейса: AI может ускорить подготовку артефактов, если для него заранее определены правила качества. Без style guide результат будет зависеть от интерпретации модели. Со style guide результат становится более повторяемым и пригодным для командной работы
Кейс №3: Публикация UC в Confluence (или почему здесь начался ад)
Наиболее сложным и показательным стал кейс подготовки и публикации use case в Confluence.
На первый взгляд задача простая: сформировать страницу в формате команды и опубликовать её. Страница должна была содержать оглавление, историю изменений, вкладки, code- и info-блоки, PlantUML. Обычного Markdown здесь недостаточно.
Но нельзя просто взять HTML-выгрузку существующей страницы и отправить её обратно как body.storage. Когда так делали, мы получали некорректную страницу, битые изображения и ссылки на attachments исходного документа (а ещё море слёз).
Как оказалось, генерация текста и публикация в корпоративную вики — это два совершенно разных уровня сложности. И вот почему:
1. Проблема авторизации. В Figma был PAT, и агент работал сам по себе. В нашем корпоративном Confluence отдельного технического токена не было. В итоге агент работал от лица пользователя, используя куки активной вкладки браузера (credentials: 'same-origin'). То есть, если вы не залогинены в Confluence, агент видит страницу входа.
2. Проблема формата (Storage XML). Нельзя просто взять HTML-выгрузку страницы и отправить её как body storage. Confluence это съест, но картинка сломается, а ссылки превратятся в мусор. Нам пришлось писать Python-скрипт, который генерировал чистую Confluence storage-разметку.
3. Проблема версий. Confluence требует актуальный номер версии (version.number + 1 при PUT-запросе). Если кто-то зашёл и поправил страницу пока ИИ думал — конфликт обеспечен. Приходилось перед публикацией запрашивать status=current с отключением кэша.
4. Боль с кодировкой. Классическая засада. Передавали storage через base64, использовали стандартный atob(b64) для декодирования — и вся кириллица превратилась в кракозябры. Пришлось переписывать на new TextDecoder('utf-8').decode(raw).
5. Ограничения CDP. Confluence storage весит десятки килобайт, а если добавить картинки — мегабайты. Прогонять такие объёмы данных через последовательные вызовы Runtime.evaluate (Chrome DevTools Protocol) оказалось нестабильным — связь рвалась.
В итоге мы пришли к такому пайплайну: Python-генератор → Storage XML → Локальная валидация → Локальный CORS-сервер → Browser REST (с куки) → TextDecoder → Выполнение сниппета в DevTools.
Как раз тогда и появилась идея фиксировать все проблемы и итоговые рабочие решения в отдельный документ в confluence-generation-retrospective.md. Это позволило агенту не зацикливаться на одних и тех же предложенных вариантах решения, а полноценно и автономно решать вопросы по уже зафиксированным рабочим решениям.
Кейс №4: Работа с Figma
Отдельным направлением исследования стала работа с Figma, так как макеты пользовательских сценариев хранятся именно там.
Для доступа к Figma был настроен Personal Access Token. Токен был сохранен в переменную окружения FIGMA_TOKEN, после чего агент мог обращаться к Figma API через заголовок X-Figma-Token.
Проверка подключения выполнялась через endpoint /v1/me. После подтверждения токена агент мог получать данные о файле, читать структуру нод и экспортировать отдельные экраны в PNG.
Пример проверки:
curl -s -H “X-Figma-Token: $FIGMA_TOKEN” https://api.figma.com/v1/me | python3 -m json.tool
Для работы с конкретными экранами использовались file key и node id. При этом была зафиксирована важная техническая особенность: node id из ссылки Figma может отображаться через дефис, но в API передаётся через двоеточие. Например, 4888-28266 в URL передается как 4888:28266 в API-запросе.
В результате агент смог получать макеты, экспортировать экраны в PNG, читать изображения с диска и использовать их для описания сценариев.
Отдельно было выявлено, что работа токена в обычном терминале не гарантирует работу агента в Cursor. Для доступа агента к api.figma.com может потребоваться разрешение сетевого доступа в sandbox-настройках.
Промежуточный вывод
После первых кейсов стало понятно: я постепенно перешла от разовых экспериментов с AI к оформленному рабочему подходу.
Агент уже не был отдельным чатиком, которому я каждый раз заново объясняю задачу. У него появились правила, область ответственности, рабочие файлы, критерии остановки research-фазы и понятный формат результата. Но вместе с этим появился новый риск.
Все эти эксперименты я проводила в своей предметной области и на артефактах, которых хорошо знала. Я понимала, каким должен быть результат, где агент ошибается, какие поля нельзя придумывать, какие формулировки не подходят и какие технические детали нужно перепроверить.
То есть на этом этапе мы доказали не то, что подход универсален, а только то, что он помогает мне быстрее выполнять знакомую работу при моём же постоянном контроле.
А этого было недостаточно.
Чтобы эксперимент не превратился в историю «я хорошо написала промты под свои задачи», нужно было проверить подход на другом артефакте, в другой предметной области и в формате документации, который изначально не был заточен под мой привычный рабочий процесс.
Бонусная глава, где я экспериментирую на чужой документации
Все эксперименты я проводила на собственной работе, в знакомой предметной области и на документации, формат которой хорошо знала. Задачи, которые раньше оценивались примерно в пять story points, теперь укладывались в один-два с учётом проверки. И к этому моменту оставался один вопрос: «Действительно ли у меня получилось построить воспроизводимый процесс или я просто научила агента работать «как я»?»
Чтобы подтвердить или опровергнуть свою догадку, я предложила коллеге из другого отдела провести эксперимент на другой документации. Мы взяли реальную задачу по актуализации middle-документации сервиса. Она звучала так: «Разработчик уже добавил новую функциональность, OpenAPI и тесты. Базовый каркас документации существовал, но полноценного раздела по новой функциональности ещё не было»
При ручной работе сначала потребовалось бы изучить существующую документацию, затем собрать детали реализации у разработчика, написать и полдня отшлифовать описание и отдельно дождаться сниппетов.
Мы начали не с команды «Внеси в документацию все изменения разработчика», а согласно уже проложенному сценарию (который описала выше). На первой фазе агент должен был исследовать изменения feature-ветки относительно основной и определить:
Что изменилось?
Что действительно реализовано?
Что из этого нужно переносить в документацию?
В качестве источника истины он использовал код, OpenAPI и уже существующую документацию из Confluence для получения полного контекста. Согласно правилам все подтверждённые факты фиксировались в findings.md, а неясности в open-questions.md.
Research-фаза выявила методы, которые уже появились в коде, но отсутствовали в документации, а также расхождения между контрактом и фактической реализацией. Эти расхождения не скрывались, а фиксировались через NOTE.
После исследования началась документационная фаза. Для AsciiDoc подготовили отдельный style guide на основе существующих раздело в репозитория. Агент сформировал вводный раздел, общую sequence-диаграмму, сценарии работы методов, таблицы параметров и сниппеты (которые уже были описаны разработчиком, перенесли).
Параллельно мы сравнивали результат с другой документационной веткой, но не использовали её как безусловный источник истины.
Также мы четко разграничили правилами:
Если в документации был метод, которого нет в нашем API, мы его не переносили.
Если описание обещало больше, чем делал код, фиксировали расхождение.
Получился двухфазный процесс: исследование изменений с минимальной неопределенностью → перенос подтвержденных фактов в техническую документацию.
Полное описание со сниппетами заняло примерно полдня. Часть времени при этом ушла на первую настройку среды и плагина (не все плагины так легко настраиваются или просто мне с IDEA не везет).
Но главное — эксперимент шёл параллельно с ручной работой другого аналитика над той же задачей.
После завершения мы сравнили результаты. Существенных расхождений в сценариях и технических фактах не оказалось, различались в основном формулировки.
Например, ручное описание начиналось примерно так:
> В сервисе реализованы эндпоинты для управления пакетами поставок. Пакеты используются для группировки изменений сущностей с целью последующего выполнения действий: отправки на ревью, развертывания и других операций.
Агент сформулировал вводный текст немного иначе:
> В сервисе реализованы эндпоинты для админки по работе с поставками. Поставки используются для группировки изменений сущностей перед согласованием и последующей выкаткой. Доступ к данным эндпоинтам извне ограничивается шлюзом доступа.
Смысл в обоих вариантах совпадал: речь шла о новой функциональности для группировки изменений и управления их жизненным циклом. Но агент, следуя style guide, сделал вводный текст более структурным: сначала указал, для кого предназначено API, затем объяснил назначение поставок, а отдельно вынес ограничение доступа.
При этом детали реализации не попадали в intro. Они оставались в описании конкретных методов, чтобы вводный раздел не превращался в техническую свалку.
Для меня это стало одним из главных результатов исследования: агент справился с другой предметной областью и другим форматом документации не потому, что «умеет писать middle-документацию», а потому что сработал процесс.
Но есть неприятный нюанс, который нужно учитывать при работе с агентом: результат нужно уметь проверить
Здесь легко сделать неправильный вывод. Раз агент смог работать с технической документацией, значит аналитик может заходить на территорию разработки и самому покрывать код тестами вместо разработчика.
Нет.
Результат получился качественным потому, что его можно было проверить.
В аналитической части я понимала структуру сценариев, правила описания контрактов и могла заметить, когда агент начинает додумывать.
В эксперименте с middle-документацией источником истины были код, OpenAPI и тесты. Результат дополнительно сравнивался с работой другого аналитика.
Но без достаточной экспертизы в разработке я не могу утверждать, что сгенерированный AI сниппет жизнеспособен. Я могу проверить, соответствует ли он описываемому сценарию и выполняет ли функцию примера в документации.
И вот здесь и появляется риск локальной оптимизации.
Аналитик может сэкономить два часа на генерации сниппетов, а разработчик затем потратить четыре на review, конфликты и исправление неработающего кода.
Это не оптимизация, а перенос работы на следующего участника процесса.
Поэтому нужно добавить ещё одно правило: не оценивайте качество AI-результата там, где у вас нет экспертизы его проверить.
Хороший промт не превращает аналитика в разработчика. AI ускоряет существующую экспертизу, но не создаёт её автоматически.
Зоны ответственности остаются прежними: аналитик отвечает за требования и спецификацию, разработчик — за реализацию, тестировщик — за качество проверок. AI лишь помогает каждой роли работать быстрее со своим контекстом.
Что изменилось в процессе команды
В конце квартала мы вынесли результаты на общую встречу и сравнили артефакты, подготовленные вручную и с участием агента.
Стало понятно, что основной эффект — не только в экономии времени аналитика.
Раньше один и тот же контекст фактически описывался на двух платформах: аналитик готовил основной документ в Confluence, а затем требования повторно переносились и интерпретировались в GitLab для разработки и агентов.
После эксперимента мы решили сосредоточиться на одном полноценном артефакте и процессе:
Аналитик формирует подтверждённый контекст.
Агент разработчика использует спецификацию как вход для реализации.
Тестировщик на основе спецификации подготавливает тест-кейсы.
Мы не убрали документацию из Confluence полностью, а убрали повторный перенос и интерпретацию одного и того же контекста.
Заключение
В марте я начинала с простого вопроса: «Зачем мне агент, если сама я сделаю быстрее?»
Первые эксперименты давали однозначный ответ: не нужен.
Задача «на день» растягивалась на три-четыре. Агент требовал постоянного контроля, придумывал данные и возвращал собственные решения в финальный документ как мои, а после запрета на додумывание начинал бесконечно задавать вопросы.
Постепенно стало понятно: мы давали агенту задачу, но не давали процесс. В итоге полезным оказался не «идеальный промт», а система ограничений: research → open questions → findings → domain-spec → API → документация.
А также:
Отдельные style guide.
Явные источники истины.
Контроль неопределённости.
Чёткие границы ответственности.
И к концу исследования вопрос изменился на «Можно ли один раз подготовить качественную спецификацию и перестать пересобирать один и тот же контекст отдельно для аналитика, разработчика и тестировщика?»
В нашем случае — да.
При этом мой главный вывод за квартал остаётся довольно жёстким — ИИ эффективен в аналитике только тогда, когда заперт в управляемый процесс. Без процесса он ускоряет не только создание документации, но и распространение ошибок. А с процессом, style guide, контролем неопределённости и ручной проверкой он становится полезным ассистентом.
AI ускоряет, он не заменяет вашу экспертизу. Если вы не способны проверить результат, вы не контролируете агента. Вы просто надеетесь, что он угадал. А на требованиях, API, коде и архитектурных решениях я бы на удачу пока не рассчитывала
Чтобы статья не осталась только рассказом о моем опыте, я собрала отдельную папку с материалами эксперимента.
[Ссылка на материалы здесь]
Важно: материалы обезличены и очищены от чувствительных данных. Их не стоит воспринимать как универсальный шаблон «на все случаи жизни», но можно использовать как отправную точку для собственного процесса