Ship Skills, Not Docs: як ми перетворили SaaS-інтеграцію на агентний процес

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

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

Ця стаття буде корисною командам, які розробляють SaaS-платформи, B2B-сервіси або інші продукти й модулі, що потребують комплексної інтеграції із системами клієнтів.

Я працюю CTO Kinoa з 2022 року. Нашою метою було побудувати LiveOps-платформу (SaaS-рішення для керування налаштуваннями, монетизаційними кампаніями та іншими LiveOps-активностями у застосунках), яка могла б працювати з різними жанрами, технологіями та архітектурами мобільних ігор і застосунків. Основним KPI ми визначили швидкість інтеграції. Другою амбіцією було створити функціонал, який не поступався б внутрішнім платформам найбільших ігрових компаній. Третьою — адаптивність: одне рішення мало однаково добре працювати для клієнтів різного масштабу, з різними жанрами, технологіями та архітектурами.

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

Чому документації недостатньо

Щоб досягти цієї мети, ми побудували гнучку модель інтеграції: основна логіка залишалася на боці нашої платформи, але клієнт міг розширювати її у власній системі. У результаті технічна частина інтеграції зводилася до реалізації набору сценаріїв — наприклад, реєстрації користувача, передавання його подій, обробки згенерованих системою pop-up повідомлень, а також обробки й оновлення динамічних конфігурацій. Це лише кілька прикладів: на практиці таких інтеграційних модулів було значно більше.

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

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

Ми додавали документацію, приклади й готові шаблони. Спочатку це допомагало. Але коли обсяг матеріалів зріс, ефект став протилежним: розробнику було дедалі складніше знайти потрібний для його проєкту сценарій інтеграції. Деякі клієнти просто копіювали шаблони як є, не реалізовуючи навіть вкладені TODO, які мали зв’язати інтеграційний код із самою грою.

Перший експеримент: відправити людину

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

Однак цей підхід мав серйозні обмеження. Не всі компанії готові надати зовнішнім інженерам доступ до свого коду. Сам підхід погано масштабується, його складно планувати, а окупність залишається низькою. Крім того, внутрішній команді клієнта було складніше надалі розвивати таку інтеграцію: навіть після детальних code review і тестів вона часто залишалася для команди своєрідною чорною скринькою.

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

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

Як передати агенту експертизу платформи

У 2026 році я познайомився з концепцією skills у Claude Code. Для мене це стало відповіддю на попередній експеримент: skill разом із coding agent може виконувати роль нашого інженера, якого ми відправляли до клієнта. Але тепер цей «інженер» працює безпосередньо з кодовою базою клієнта: досліджує її структуру, читає вимоги й діє в контексті конкретного проєкту.

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

По суті, skill перетворює знання наших інженерів з інтеграції на повторюваний робочий процес. Це вже не документація, яку розробник має прочитати й самостійно застосувати, і не разовий запит із проханням написати код. Skill веде агента через послідовність дій і містить правила, за якими той досліджує проєкт, приймає рішення, генерує код, налаштовує платформу та перевіряє результат.

Від першого skill до повторюваної схеми

Перше, що ми зробили, — створили один невеликий skill. Він мав отримати необхідні токени з правами доступу, знайти в коді всі поля користувача, створити клас, що описує стан гравця для передавання в нашу систему, та згенерувати код, який це реалізує.

Оскільки набір полів і їхні типи визначає клієнт, їх також потрібно зареєструвати в нашій платформі. Для цього ми додали до skill простий Python-скрипт. Він приймав bearer-токен розробника та виконував REST-запити до платформи, автоматично реєструючи знайдені поля від імені акаунта розробника. Завершальним кроком була генерація інтеграційного тесту з використанням технологій і тестової інфраструктури клієнтського проєкту.

Перший результат виглядав чудово: skill знайшов поля, написав код, налаштував платформу та створив тест. Але чи означало це, що інтеграція справді готова? Насправді значну частину знайдених полів узагалі не потрібно було передавати. Такий pull request не пройшов би code review. Після автоматичної генерації все одно залишалася ручна робота: видалити зайві поля й код, виправити тест і синхронізувати зміни з конфігурацією платформи.

Рішенням став окремий етап погодження до початку імплементації. Після етапу дослідження skill генерує HTML-звіт зі знайденими полями та їхніми типами. Розробник може видалити непотрібні поля, виправити інформацію або змінити вибрані опції. Якщо чогось бракує, він може дати coding agent додаткові інструкції, попросити повторити пошук і згенерувати сторінку ще раз.

Лише після погодження звіту skill генерує код, синхронізує конфігурацію платформи та створює тести. Завдяки цьому обсяг інтеграції визначено ще до появи pull request, а кількість фінальних правок значно зменшується.

Discovery → Approval → Implementation and platform sync → Verification → Final report

Спочатку агент досліджує систему й визначає обсяг інтеграції. Потім людина його погоджує. Після цього skill реалізує інтеграцію та синхронізує конфігурацію платформи, перевіряє результат і формує звіт про виконану роботу. Цю схему легко застосувати до інших модулів інтеграції.

Модульний підхід до інтеграції

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

Перевага такого поділу полягає у вузькій спеціалізації та повторному використанні: частину subskills можна запускати самостійно в різних інтеграціях. Наприклад, один із них приймає приклад конфігурації та відтворює її структуру в платформі. Інший отримує скриншот pop-up повідомлення й створює відповідний шаблон.

Для кожного інтеграційного модуля ми маємо окремий skill-оркестратор, який викликає потрібні subskills і керує послідовністю їхньої роботи. Над ними працює загальний оркестратор, який відповідає за інтеграцію всіх модулів і керує залежностями між ними.

Повна інтеграція може тривати довго, тому її стан не варто зберігати лише в контексті агента. Результати дослідження, погоджений обсяг інтеграції, виконані кроки та створені артефакти ми записуємо в окремий файл. Завдяки цьому процес можна зупинити на будь-якому етапі й пізніше продовжити без повторного дослідження кодової бази.

Той самий механізм дає змогу розширювати вже готову інтеграцію. Можна повернутися до конкретного модуля, додати нові поля користувача, конфігурації або шаблони для pop-up повідомлень, не запускаючи весь процес із початку.

Де цей підхід не працює

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

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

На цьому рівні AI починає губитися, тому що фактично ніколи не має повного контексту всієї розподіленої системи. Він може добре працювати всередині окремої codebase, але не здатен самостійно відновити архітектурні зв’язки, яких у доступному контексті просто немає. Тут skill уже не замінює архітектурну роботу: спочатку люди мають визначити, де формується потрібний стан і як його зібрати, і лише після цього агент може допомогти реалізувати рішення.

Як побудувати систему integration skills: вісім практичних правил

У результаті ми отримали повноцінну систему skills і для зручності запакували її у Claude Code plugin. Це дало змогу легко передавати систему клієнтам і використовувати однаковий workflow у різних проєктах. Тривалість базової інтеграції скоротилася до двох робочих днів. Але ще важливішим результатом стало суттєве зростання якості інтеграцій і скорочення часу, який наша команда витрачала на консультації та супровід клієнтів.

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

Це не прибирає людину з процесу. Саме вона приймає рішення, ескалює бізнесу запитання, на які не має відповіді, і зрештою несе відповідальність за результат. Кожна інтеграція унікальна, а результат роботи ШІ недетермінований, тому людський фактор досі залишається ключовим. Роль агента — максимально полегшити інженеру роботу: допомогти вести інтеграцію, сформулювати правильні запитання та підготувати рішення.

Нижче — вісім принципів, які сьогодні допомагають нам будувати й підтримувати цю систему. Вони напевно змінюватимуться разом із розвитком інструментів, але саме на них ми спиралися, створюючи фреймворк для інтеграції платформи Kinoa за допомогою ШІ.

• Один великий skill не масштабується. Skills можуть викликати один одного, тому відповідальність можна розподіляти між окремими спеціалізованими subskills. Для одного інтеграційного модуля можуть існувати окремі skills для discovery, конфігурації платформи, написання тестів або навіть підготовки початкових бізнес-вимог. Ми винесли конфігурацію в окремий skill, а дослідження codebase та розробку залишили разом. Якщо платформа ще не має MCP-сервера, skill може запускати Python-скрипт, який виконує необхідні дії через REST API.
• Погоджений scope — передумова будь-яких реальних змін. Перед генерацією коду або конфігурацією платформи розробник має побачити й підтвердити сформований scope. Найефективнішим форматом для нас виявилася web-сторінка: skill генерує її, розробник переглядає результати, редагує дані або вибирає потрібні опції, а потім натисканням кнопки зберігає погоджений результат в окремий файл. Після цього skill читає файл і продовжує роботу. Кожен такий файл має отримувати унікальну назву.
• Стан інтеграції має зберігатися поза контекстом агента. Skill не повинен тримати весь стан інтеграції лише у своєму контексті. Результати discovery, погоджені рішення, завершені кроки та наступні дії варто записувати в окремі файли. Завдяки цьому інтеграцію можна будь-коли поставити на паузу, а потім продовжити без повторного дослідження всього проєкту.
• Telemetry — частина системи від самого початку. Skills підтримують hooks, і цей механізм можна використати для спостереження за процесом інтеграції. Ми підняли невеликий сервіс з endpoint, куди skill надсилає telemetry про проходження workflow. Це не дає нам доступу до коду клієнта, але показує, як клієнт взаємодіє зі skill і як skill реагує на його дії. Завдяки цьому ми значно швидше знаходимо проблемні місця та вдосконалюємо процес.
• Skills потребують такого самого рівня тестування, як продуктовий код. У Claude Code є плагін skill-creator, який допомагає створювати skills і тести до них. Але згенеровані тести все одно потрібно уважно перевіряти, доповнювати й писати для найдрібніших сценаріїв. У певний момент навіть добре структурована система skills стає настільки складною, що якісно перевірити її лише за допомогою code review майже неможливо.
• Реалістичні застосунки — обов’язкова частина перевірки інтеграції. Ізольованих тестів самого skill недостатньо. Ми згенерували кілька різних застосунків на різних frameworks і запускали інтеграцію всередині кожного з них. Так можна перевірити не лише інструкції skill, а й те, як він адаптується до різних архітектур, моделей даних та способів запуску тестів.
• Доставка та versioning — частина архітектури системи skills. Якщо інтеграція використовує SDK, відповідний skill має жити всередині цього SDK. Тоді кожен release міститиме протестований skill, сумісний із конкретною версією. У нас є інтеграції і через API, і через SDK, тому спільні skills імпортуються з одного проєкту в інший. Насамперед це стосується конфігурації платформи: такі skills залежать від змін у платформі, а не від версії SDK, тому їхній життєвий цикл потрібно вести окремо.
• Перший робочий результат важливіший за ідеальне рішення. Найважче — отримати перший робочий результат. Навіть якщо skill автоматизує або спрощує лише 10% інтеграції, це вже дає реальний feedback, надію та мотивацію рухатися далі. Не варто чекати ідеального рішення, перш ніж показати його клієнту й перевірити на практиці.

Що далі

Далі ми плануємо ще більше подрібнити наявні skills та зробити оркестратори розумнішими. Вони мають відповідати не лише за початкову інтеграцію, а й за її подальше розширення та перехід на нові версії API після їх появи.

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