AI-агент як технічний письменник: як я автоматизував генерацію бізнес-документації з Agile-артефактів за $20

💡 Усі статті, обговорення, новини про AI — в одному місці. Приєднуйтесь до AI спільноти!

Привіт. Мене звати Євген Харчук. Я Salesforce-архітект з дев’ятирічним досвідом, більшість із яких — робота на ентерпрайз-проєктах. Зараз працюю в EPAM як Software Architect. Поза роботою граю у великий теніс, проводжу час із дітьми і копаю все, що пов’язано з AI — особливо цікавить, як цю нову реальність вбудовувати в існуючі ентерпрайз-системи.

Вступ

Ми почали впроваджувати на проєкті систему AI-агентів для повного циклу розробки — від аналізу вимог до імплементації. Агент-продакт-овнер, агент-архітектор, агент-розробник — кожен зі своєю роллю, кожен працює на своєму етапі. Щось на кшталт BMAD Method — open-source фреймворк для agile-розробки з AI-агентами.

І дуже швидко зіштовхнулися з однією проблемою: агентам потрібен контекст проєкту. Коли агент-продакт-овнер готує нову фічу чи зміну бізнес-сценарію, він мусить розуміти, як система працює зараз — які бізнес-процеси є, які залежності між ними, які автоматизації задіяні. Без цього він упускає деталі, які потім довго і нудно рефайниш, допрацьовуєш, проганяєш через архітектора. Архітектору, у свою чергу, треба бачити залежності між модулями і командами, щоб підсвітити ризики до того, як код написаний.

А ці знання — бізнес-процеси, ролі, зв’язки між модулями — в гіті не живуть. Код є, тікети є, сотні закритих stories є. Але цілісної картини, яку можна швидко скормити агенту, — нуль.

Тому я написав фреймворк і зібрав агентний pipeline, який тягне Agile-артефакти (Rally у моєму випадку, але підходить і Jira, і Azure DevOps — що завгодно з ієрархією Feature → Story) і перетворює їх на структуровану базу знань. Понад десять бізнес-процесів, десятки автоматизацій, інтеграції, персони — усе зібрано в одному місці, з метаданими і графом залежностей. Триста фіч за три роки проєкту я обробив приблизно за 600 premium-запитів у GitHub Copilot на GPT-5.4. За публічним прайсом це десь $20.

Первинна ціль — дати контекст AI-агентам. Але побічний ефект виявився не менш цінним: ми отримали нормальну бізнес-документацію, яку можуть читати і люди. Онбординг, impact analysis, розуміння системи цілком — усе це прийшло «в комплекті».

У цій статті поділюсь тим, яку проблему розв’язував, що з цього вийшло, і чому мені здається, що в цьому підході є потенціал для ентерпрайз-проєктів загалом.

Чому git-репозиторію недостатньо

Перше, що хочу розмежувати відразу. Є купа тулів, які генерують доку з коду: JavaDoc, JSDoc, різні API-референс генератори. Це все працює на технічному рівні — класи, методи, ендпоінти. Якщо вашому проєкту вистачає такого, далі можна не читати, ця стаття про інше.

У мене задача виглядала зовсім по-іншому. Бо коли маєш справу з великою CRM чи ERP — Salesforce, SAP, ServiceNow, та навіть кастомна платформа — там система живе не класами, а бізнес-сценаріями. От є процес обробки замовлення. Є процес онбордингу клієнта. Є ескалація інциденту. І ці штуки ніде в гіті в явному вигляді не існують. Вони розмазані по десятках класів, конфігурацій, автоматизацій, UI-сторінок. Жоден генератор доки з коду не скаже тобі: «ось твій бізнес-процес від А до Я, ось де він розгалужується, ось які інтеграції зачіпає».

Хочеш зрозуміти, як щось працює — збирай пазл з десятків файлів. Хочеш зробити impact analysis — тримай в голові граф залежностей на пів-системи. Саме для цього потрібна бізнес-документація. Але от біда — хто її писатиме? І головне, хто підтримуватиме?

Agile-артефакти: вони не хаотичні, але читати їх неможливо

У більшості проєктів, де окрему доку ніхто не тримав, Agile-інструмент стає єдиною базою знань де-факто. Rally, Jira, Azure DevOps — неважливо. Feature → User Story → Test Case: у цій ієрархії є і бізнес-контекст, і вимоги, і сценарії, і ролі.

Але тут є підступ, який я довго не міг сформулювати. Agile-артефакти — вони не хаотичні. Вони цілком собі структуровані, кожен окремо. Проблема в іншому: вони відображають таймлайн розробки, а не актуальний стан системи. Працюють як ланцюжок git-комітів — кожна нова фіча, кожна story це ніби «патч» поверх попереднього стану. Нові stories перетирають старі, уточнюють, змінюють поведінку, додають винятки. І щоб зрозуміти, як конкретна річ працює зараз, тобі треба прошерстити всі пов’язані артефакти — а їх буває десятки. Для системи з трьома сотнями фіч це робити вручну доволі складно.

Ще один момент, який мене здивував: я пробував підключити AI-агента напряму до Rally через MCP-інтеграцію. Думав — ну он, нехай сам шукає потрібні тікети. Пробував і пошук по ключових словах, і навіть контекстний пошук через векторну базу. Не працює. Нормально не працює — агент не може зібрати повну картину з розрізнених фрагментів через пошук. Йому потрібна або вся історія по сутності цілком, або вже готовий структурований документ.

Тому рішення вийшло інше: експортувати кожну фічу цілком (сама фіча + всі дочірні stories + тест-кейси — одним JSON-файлом) і дати агенту обробити їх по одній. Він бере фічу, розкладає інформацію по модульній бібліотеці знань, іде до наступної.

Мій контекст: чому Salesforce, і чому це не тільки про Salesforce

Я все це реалізував на нашому Salesforce-проєкті — CRM з порталами, інтеграціями, купою кастомізації. Система немаленька: понад десять різних бізнес-процесів, кілька типів користувачів, кожен зі своїми сценаріями. Але хочу одразу сказати: Salesforce тут — просто приклад. Конкретна платформа, на якій я обкатав фреймворк. Модульна структура документів, шарова модель, композиція бізнес-потоків, агентний pipeline — все це не має жодної прив’язки до Salesforce. Працюватиме з будь-якою ентерпрайз-системою.

Документація в нас була в типовому стані: щось на Confluence (написане два роки тому і з тих пір ніхто не відкривав), щось у головах людей (які частково вже пішли з проєкту), а щось — просто ніде. Зате в Rally лежало кілька сотень фіч і тисячі user stories. Найповніший опис системи, який існував — тільки от не у вигляді документації, а у вигляді хронологічного потоку тікетів.

З чим я мав справу: п’ять болів

Перший — AI-агентам нема звідки взяти контекст. Хочеш, щоб агент-продакт-овнер підготував нормальну фічу — йому треба знати, як працюють існуючі бізнес-процеси, які персони задіяні, які залежності між модулями. А цього ніде немає у зручному для агента вигляді.

Другий — знання розкидані всюди. По тікетах, по Confluence, по чатах, по коду, по головах людей. Ніхто — ні людина, ні агент — не бачить цілісної картини.

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

Четвертий — impact analysis на інтуїції. Хочеш щось змінити — і не знаєш, що посиплеться. Люди покладаються на «ну я ж тут давно працюю, я приблизно знаю». Продакт-овнери і бізнес-аналітики упускають деталі, які потім довго рефайниш і допрацьовуєш. А потім prod incidents.

П’ятий — вручну документувати неймовірно дорого. Бізнес-аналітику мало просто тікети вести. Треба ще описувати модулі, бізнес-процеси, залежності між ними. Сотні людино-годин. І все це застаріває через місяць, бо система не стоїть на місці.

Що я зробив

Я побудував фреймворк для модульної бізнес-документації. Не «попросив ChatGPT написати доку», а інженерну систему з правилами, типами документів, валідацією і пайплайном.

Ось що вона вміє:

• Генерувати документацію з Agile-артефактів або будь якої неструктурованої інформаціі (чати, транскрипціі мітингів, коміти в гіті) автоматично — агент читає інформацію і розкладає по поличках
• Тримати жорстку структуру — у кожного документа є тип, метадані, межі вмісту, зв’язки з іншими документами
• Підтримуватись інкрементально — зробив нову story, прогнав через той самий pipeline, документація оновилась
• Бути зручною для AI-агентів — метадані машинно-зчитувані, є граф залежностей, є механізм прогресивного завантаження (агент підвантажує тільки те, що йому зараз потрібно)

Ключова штука, яка відрізняє це від генерації доки з коду: фреймворк документує те, чого в гіті немає у явному вигляді. Бізнес-процеси, ролі, зв’язки між модулями на рівні семантики, а не на рівні імпортів між класами.

Як влаштований фреймворк

Шари

Вся документація розбита на семантичні шари:

L1 — це бізнес-процеси, і там заборонено писати про поля бази даних чи ендпоінти. L2 — платформні сутності (об’єкти, автоматизації), і там навпаки — без бізнес-наративу. Це не рекомендація типу «бажано дотримуватись», це контракт, який перевіряється валідаційним скриптом автоматично.

Можна додати ще L3 — інженерний шар (стандарти кодування, тестування, деплоймент), але я вирішив, що це опціонально. Суть-то фреймворку — документувати те, що з гіту не витягнеш. А код агент може й сам прочитати.

Посилання між документами теж мають правила: йдуть «вниз» по шарах (L0→L1→L2) або «вбік» (L2↔L2). Знизу вгору — тільки навігаційний тег participates-in, щоб від об’єкта можна було швидко знайти, у яких бізнес-потоках він задіяний.

Один документ = одна сутність

Це просто, але на практиці дуже важливо. Один файл описує рівно одну річ: один об’єкт, або одну автоматизацію, або одну фазу процесу. Завдяки цьому будь-який документ можна оновити незалежно. І граф залежностей не перетворюється на мотлох.

Композиція бізнес-потоків — над цим я думав найдовше

Ось це, мабуть, найцікавіша частина.

Задача: як документувати бізнес-процеси так, щоб це і масштабувалось, і не дублювалось, і щоб AI-агент міг вибірково завантажувати тільки те, що йому потрібно?

Стандартний підхід в IT — діаграми. BPMN, UML activity, swim-lane. Кожен сценарій — окрема діаграма. Але от уявіть бізнес-потік з п’ятьма етапами і десятьма розгалуженнями. Це ж десятки діаграм. А тепер уявіть, що вам їх ще й підтримувати в актуальному стані. Нереально. Плюс діаграми для AI-агента — не дуже зручний формат. Йому потрібен текст, модульний, з чіткими лінками.

Я довго крутив цю задачу і прийшов до трирівневої композиції, де бізнес-сценарій ніколи не описується цілком в одному документі. Замість цього він збирається з кубиків:

• Потік (flow) — просто список фаз у правильному порядку. І загальна інформація.
• Фаза (phase) — окремий етап процесу. Описує стандартний шлях. Ключовий момент: фаза може входити до кількох потоків.
• Варіація (variation) — відхилення від стандартного шляху фази. Описує лише дельту: «а от якщо клієнт на credit hold, тоді відбувається отаке».

Якщо проводити аналогію з кодом: потік — це функція, яка викликає інші функції (фази). Варіації — умовні розгалуження. Фаза, яка шариться між кількома потоками — це shared utility. Якщо потрібна поведінка, специфічна для конкретного потоку, — оформляєш як окрему варіацію.

Чому мені це подобається:

• Фаза написана один раз, навіть якщо входить до п’ятьох потоків. Ніякого copy-paste.
• Додати нову варіацію — це додати один файлик і лінк. Не переписувати діаграму.
• Агент завантажує рівно ту фазу чи варіацію, яка йому потрібна. Не весь потік цілком.
• Прийшла нова user story, яка міняє один етап? Оновлюєш один файл фази, не чіпаючи решту.

Наскільки я шукав, подібний модульний підхід до документування бізнес-потоків саме під AI-споживання раніше ніхто не описував. Можливо, я просто погано шукав — буду вдячний за посилання на аналоги.

Навіщо документувати автоматизації, якщо код і так в гіті

Це питання, яке мені задавали кілька разів, тому хочу пояснити.

Типова автоматизація в ентерпрайз-системі — це не один клас і не один файл. Це trigger handler, який смикає service class, який тягне за собою utility, який працює з трьома об’єктами і має купу guard conditions. Щоб AI-агент зрозумів, що робить ця автоматизація, йому треба завантажити в контекст файлів двадцять. Контекстне вікно не гумове.

А в бібліотеці — один документ на 500–1000 токенів. Написано людською мовою: «спрацьовує при такій події, робить ось це, має такі умови, залежить від таких об’єктів». Агент підвантажує один файлик — і вже розуміє контекст. Якщо потім йому потрібні деталі реалізації — іде в код. Бібліотека — це навігаційний і контекстний шар, не заміна коду.

Робиться це один раз. А потім, коли автоматизація змінюється через нову фічу чи story — прогоняєш через той самий pipeline, і документ оновлюється.

INDEX: зміст всієї системи за дві тисячі токенів

Є один документ, який тримає все до купи — INDEX.md. Він генерується автоматично скриптом. По суті, це оглавлення: посилання на кожен документ бібліотеки плюс коротка підказка — коли цей документ варто підвантажувати.

Ці підказки беруться з поля ai-when-to-load, яке є в кожному файлі:

ai-when-to-load: "Коли працюєш із процесом обробки замовлень або об'єктом Order"

Скрипт пробігає по всіх файлах, збирає ці підказки і формує каталог, згрупований по папках. На виході — щось на кшталт змісту книги, де кожний запис каже: «цей розділ читай, якщо займаєшся ось цим».

Для агента INDEX — це точка входу. Він не сканує файлову систему і не вгадує імена. Прочитав INDEX за пару тисяч токенів — і вже бачить усю систему: які є бізнес-потоки, об’єкти, автоматизації, інтеграції. Далі підвантажує 1–3 потрібних документи — і працює.

Фронтматер: метадані, які перетворюють текст на граф

На початку кожного документа стоїть YAML-блок — фронтматер. У ньому зібрано все, що потрібно для машинної обробки:

• тип документа (business-flow, object, automation тощо)
• унікальний ідентифікатор
• depends-on — від яких документів цей залежить
• consumed-by — хто залежить від цього (заповнюється автоматично скриптом)
• ai-when-to-load — підказка для агента, коли вантажити
• ai-token-estimate — скільки контексту з’їсть цей файл

Сенс у тому, що документація перестає бути просто текстом. Вона стає графом знань з формалізованими зв’язками. Агент може пройти по метаданих, побудувати картину залежностей і підтягнути повний текст тільки для тих документів, які реально потрібні під конкретну задачу.

Як працює pipeline

Stage 1: витягуємо знання з Agile-артефактів

На вході — JSON-файли. Кожна фіча експортована цілком, з усіма дочірніми stories і тест-кейсами (якщо є). На виході — структурована документація.

Архітектура агентна, два рівні:

Orchestrator бере з черги наступну необроблену фічу, передає її Knowledge Curator, чекає результат, просуває чергу далі.

Knowledge Curator — робочий кінь процесу. Він читає фічу, виковирює з неї сутності (об’єкти, автоматизації, персони, потоки), класифікує їх за типами, створює або оновлює документи. І — це важливо — після кожної фічі запускає валідацію. Тобто одразу бачить: о, цей документ виріс за ліміт токенів, а тут посилання бите, а тут контент вилізає за межі типу. І виправляє це в тій самій сесії.

Одна фіча — один виклик агента. Якщо щось крашнулося, я точно знаю, де зупинилось.

Інформації в stories і фічах вистачає для генерації нормальної бізнес-документації — там описано, хто що робить, які об’єкти задіяні, які сценарії є. Тест-кейси, коли вони є, дають додатковий контекст — передумови, кроки, очікувані результати. Але й без тест-кейсів все працює, просто десь будуть маркери [UNVERIFIED].

Агент не просто copy-paste тексту. Він робить структурні операції: мерджить документи, якщо вони про одне й те ж; розбиває, якщо документ роздувається; переносить фази між потоками; підвищує варіацію до фази, якщо вона того заслуговує; переіменовує, якщо канонічне ім’я змінилось. Такі собі рефакторинг-операції, тільки для доки.

Stage 2: перевіряємо документацію кодом (grounding)

Після першого проходу маємо бізнес-рівневу доку, побудовану з вимог. Але вимоги — це одне, а що реально є в коді — інше. Тому другий етап: верифікація документації проти реального репозиторію.

Це працює по треках — кожен трек перевіряє один тип сутностей. На моєму Salesforce-проєкті це виглядало так: спочатку об’єкти (перевірка проти метаданих), потім автоматизації (зіставлення з кодом), інтеграції, ролі, UI, заплановані задачі (scheduled jobs). Для іншої платформи треки будуть своїми.

Принцип той самий: оркестратор збирає докази з коду, але сам нічого не пише. Писати дозволено тільки Knowledge Curator.

Stage 3: живе підтримання

Після bootstrap і grounding документація підтримується тим самим процесом. Зробив фічу — прогнав Curator — він оновив що треба, запустив валідацію. Все. Документація живе разом з проєктом, а не гниє на Confluence.

Скільки це коштує

Ну от тут найцікавіше, мабуть.

GitHub Copilot, модель GPT-5.4 — у неї достатньо велике контекстне вікно, щоб обробити цілу фічу з десятками stories за одну сесію. Одна фіча — один premium-запит.

У проєкті було десь 300 фіч. На їх обробку пішло приблизно 600 premium-запитів (сам bootstrap плюс повторні прогони, бо паралельно допилював фреймворк). У мене enterprise-підписка через клієнта, тому реально я не платив нічого. Але якщо орієнтуватись на публічний прайс GitHub Copilot — базова підписка $10/місяць дає 300 premium-запитів. Тобто мої 600 запитів коштували б приблизно $20.

Двадцять доларів — і структурована база знань для системи, яку команда не змогла задокументувати за три роки. Ну, звичайно, це не «натиснув кнопку і полетіло». Потрібен час на налаштування фреймворку, review результатів, ручне вирішення конфліктів. Але сама генерація контенту — двадцятка. Порівняйте з вартістю бізнес-аналітика, який би сів писати це руками.

Історія з реального життя: як AI агент заплутався в іменах

Ось один випадок, який непогано ілюструє і сильні, і слабкі сторони підходу.

Був у нас об’єкт в Salesforce. Спочатку він назвався, скажімо, «А». Потім його перейменували на «Б». Через кілька спринтів повернули назад на «А». А ім’я «Б» тим часом забрали під абсолютно новий об’єкт з іншою семантикою.

Тепер уявіть: агент обробляє фічі хронологічно. У ранніх stories згадується «А». У середніх — «Б» (але це той самий об’єкт!). У пізніх — знову «А», але тепер це може бути або повернутий оригінал, або щось зовсім інше. Класична історія з «хронологічними патчами» — щоб розібратись, треба відтворити всю історію перейменувань.

Агент не зміг це розрулити сам. Саме для таких моментів і потрібен human-in-the-loop. Бажано, хтось зі знанням системи. Частину таких сценаріїв агент може підсвітити у session reports.

Як ми це використовуємо

Контекст для AI-агентів — основний use case. Саме для цього все і робилось. Агент-продакт-овнер готує нову фічу — відкриває INDEX, знаходить релевантні бізнес-потоки і автоматизації, підтягує залежності — і має повну картину для прийняття рішень. Не упускає деталі, які раніше випливали вже на етапі розробки. Агент-архітектор бачить граф залежностей і підсвічує ризики: «ця зміна зачепить ось ці три модулі і дві інтеграції». Impact analysis — по графу depends-on / consumed-by за хвилини.

Документація, яка не застаріває. Не Confluence-сторінка, яку хтось написав рік тому і більше не відкривав. А бібліотека, яка оновлюється тим самим процесом, що й розробка.

Онбординг — побічний, але цінний ефект. Новачок починає з INDEX, бачить усі потоки, об’єкти, інтеграції. Переходить у потрібний потік, дивиться фази, розуміє залежності. Структура, яка тебе веде, а не купа розрізнених сторінок. Ми робили це для агентів, але виявилося, що людям це теж дуже зручно.

Можна буквально спитати проєкт «як ти працюєш?» Підключаєш бібліотеку до агента — і задаєш питання: «як працює ескалація?», «які автоматизації зачіпають Order?». Він не повертає список статей, як векторна база. Він сам навігує по графу, збирає потрібне і формує нормальну відповідь.

Обмеження, без яких було б нечесно

Що на вході — те й на виході

Garbage in, garbage out. Якщо story написана як «зроби щоб працювало» — агент створить порожній документ з маркером [UNVERIFIED]. Але, якщо чесно, більшість проєктів має достатньо інформації в stories і фічах для генерації корисної документації. Тест-кейси допомагають, але без них теж ок.

Edge cases

Перейменування (як розповідав вище), неповні описи інтеграцій, моменти коли агент вирішує реструктурувати документи (merge, split, reparent) — це все потребує уваги. Не критично, але очікувати повну автоматизацію без review поки рано.

Висновки

Те що я зробив — це не «AI замість техрайтера». Це інженерна система, де агент працює виконавцем, а фреймворк задає правила гри. Без фреймворку агент генерує кашу. Без агента фреймворк вимагає сотень людино-годин ручної роботи. Разом — реалістичний спосіб побудувати бізнес-документацію для системи, де її ніколи не було.

Підхід не прив’язаний ні до Salesforce, ні до Rally. Шарова модель, трирівнева композиція потоків, фронтматер як контракт, валідаційний pipeline — це все переноситься на будь-яку ентерпрайз-систему з ієрархією Epic → Feature → Story. Міняєш формат експорту — і вперед.

Чи робив хтось щось подібне раніше? Я не знайшов. Можливо, погано шукав — буду радий, якщо хтось кине посилання. Але от що я бачу на практиці: маючи таку бібліотеку, можна вийти на принципово інший рівень роботи з AI — агенти, які справді розуміють проєкт без закидання тисяч файлів у контекст. Динамічна база знань, яка живе разом із продуктом, а не десь окремо.

Ну і головне, що я для себе виніс: AI працює найкраще не тоді, коли просиш «напиши доку», а коли даєш йому чіткі правила, типи, межі і контракти — і він діє в цих рамках. Оце і є різниця між «AI генерує текст» і «AI працює як інженерний інструмент».

Сподобалась стаття? Підписуйтесь на автора, щоб отримувати сповіщення про нові публікації на пошту.