Arcovia: інструмент інтелекту архітектури на основі правил для додатків React
Дізнайтеся, як проект хакатону аналізує кодові бази React та Next.js за допомогою детерміністичних правил, щоб оцінити стан архітектури та виявити прихований технічний борг.
Виклик, який породив цей проект
Під час нещодавнього хакатону OpenAI Build Week команда поставила собі просту мету: створити щось, що розробник дійсно захоче використовувати щодня.
До кінця першого вечора концепція була зрозумілою. Ще протягом двох днів ця концепція перетворилась на функціональний проект з відкритим кодом під назвою Arcovia.
Це мало бути не одноразове демонстраційне застосування ШІ. Метою було вирішити постійну проблему, з якою стикаються розробники під час підтримки великих кодових баз на React протягом тривалого часу.
Прогалина у існуючих інструментах
Вже існує багато якісних інструментів для підтримки чистоти коду.
- ESLint виявляє проблемні шаблони.
- Prettier займається форматуванням.
- SonarQube виявляє проблеми з якістю.
- Рецензенти на основі ШІ пропонують покращення на рівні окремих рядків.
Проте жоден з цих інструментів не може відповісти на більш структурні запитання, такі як:
- Чи знаходиться загальна архітектура у гарному стані?
- Які модулі перетворюються на узких місць?
- Де накопичується технічний борг?
- Які файли потребують першочергової оптимізації?
- Що саме призвело до певного рейтингу проекту?
Проблеми архітектури зазвичай проявляються лише під час обговорень у рамках перегляду коду, або, ще гірше, коли кодова база вже стає складною для роботи. Бракувало способу оцінити стан архітектури ще до того, як вона перетвориться на справжню проблему.
Познайомтеся з Arcovia
Arcovia — це інструмент Architecture Intelligence, створений для кодових баз React та Next.js.
Замість того, щоб надавати довгий список не пов’язаних між собою попереджень, він оцінює проект цілісно та генерує інтерактивний HTML-звіт.
Цей звіт включає:
- Оцінку стану архітектури
- Граф залежностей
- Критичні точки архітектури
- Розбір того, як була обчислена оцінка
- Висновки, засновані на правилах
- Показник обсягу роботи з технічним обслуговуванням
- Конкретні рекомендації
Arcovia не намагається замінити інструменти лінтингу. Його мета — надати розробникам уявлення про більшу структурну картину, яку окремі правила лінтингу не можуть виявити.
Як це працює
Інструмент внутрішньо виконує повністю детермінований процес аналізу.
Project
│
▼
Scanner
│
▼
AST Parser
│
▼
Project Model
│
▼
Dependency Graph
│
▼
Rule Engine
│
▼
Score Engine
│
▼
Interactive HTML Report
Аналізатор наразі може виявляти низку структурних проблем. Серед них:
- Надмірно централізовані „Бог-модулі“, від яких залежить занадто багато частин додатку
- Компоненти або файли з високим показником кількості залежностей
- Компоненти або файли з високим показником кількості експортованих залежностей
Замість того, щоб перераховувати ці знахідки окремо, Arcovia об’єднує їх у єдиний, зрозумілий бал архітектури.
Спочатку правила, потім ШІ
Одним із рішень, які створники вважають особливо правильними, є виключення ШІ з основної логіки аналізу.
Сам бал архітектури ніколи не створюється мовною моделлю.
Натомість Arcovia працює так:
- аналізує кодбазу через її AST
- створює графи залежностей
- пропускає результати через детерміністичні правила архітектури
- обчислює бали за кожною категорією
Завдяки такій конструкції результати залишаються послідовними та відтворюваними.
Ширша мета — щоб ШІ допомагав у покращенні якості, а не брав на себе функцію оцінювання. Плановані завдання включають:
- пояснення окремих результатів простою мовою
- пропозиції щодо рефакторингу
- надання посилань на відповідні навчальні ресурси
- відповідь на додаткові запитання щодо звіту
Детерміністичний аналіз залишається єдиним джерелом істини, а ШІ виступає як інтерпретатор над ним.
Робота з GPT-5.6 та Codex
Цей хакатон також став першою нагодою, коли команда використовувала ШІ як справжнього співробітника протягом усього процесу розробки, а не як просто покращену версію автодоповнення.
Протягом вихідних були використані GPT-5.6 та Codex для:
- підготовки ідей щодо того, які архітектурні правила варто включити
- удосконалення способу, яким модель оцінювання враховує різні фактори
- реалізації окремих функцій
- вдосконалення візуального дизайну звіту
- спрощення складної логіки
- перевірки рішень щодо реалізації на належність
Tакож був використаний ChatGPT Images для створення брендингу Arcovia, включаючи маскота у вигляді сови, логотип та інші матеріали для запуску.
Загальний процес роботи виявився більш природним, ніж очікувалося. Замість передачі цілих функцій на повну обробку, найбільша користь полягала у швидких ітераціях, схожих на роботу з другим інженером, який допомагає обговорювати варіанти дизайну та оцінювати компроміси.
Висновки вихідних
Стиснення цього проекту в одні вихідні дало кілька корисних уроків.
Архітектура не піддається простим метрикам
Оцінка якості коду окремо є досить механічною процедурою.
Оцінка архітектури набагато складніша, оскільки вона залежить від контексту, конкуруючих компромісів та ретельно налаштованих ваг у багатьох різних правилах.
Знаходження правильного балансу між справді корисними сигналами та шумними хибними позитивами залишається відкритою та постійною задачею.
Оцінка без контексту не є корисною
Надання комусь лише числа саме по собі мало що пояснює.
Розробникам потрібно бачити:
- чому оцінка вийшла саме такою
- які фактори вплинули найбільше
- які проблеми мають найвищу вагу
- що потрібно вирішити спочатку
Ось чому звіт було розроблено так, щоб пояснювати оцінку, а не розглядати її як незрозумілий результат.
Штучний інтелект прискорює роботу, але не так, як ви очікуєте
GPT-5.6 та Codex безумовно прискорили процес створення.
Проте найбільше покращення продуктивності сталося не завдяки швидшому генеруванню коду.
Воно виникло завдяки використанню ШІ як партнера для мислення: обговоренню варіантів дизайну, ставленню сумнівів до припущень та швидкому тестуванню різних ідей.
Що буде далі
Ця версія — лише початок.
Функції, які розглядаються для майбутніх версій, включають:
- Інтеграція з GitHub Action
- Відстеження історії звітів
- Аналіз тенденцій архітектури з часом
- Розширення для VS Code
- Порівняння проектів поруч один з одним
- Панелі керування для всієї команди
- Коучинг з архітектури за допомогою ШІ
Довгостроковою метою є допомога інженерним командам у постійному моніторингу, вимірюванні та вдосконаленні архітектури їхнього програмного забезпечення з часом.
Будемо вдячні за відгуки
Arcovia є повністю відкритим кодом, тож відгуки від розробників, які активно створюють додатки на React чи Next.js, будуть особливо цінними.
Кілька запитань, які варто розглянути:
- Чи здається, що оцінка архітектури відображає щось значуще?
- Які інші архітектурні проблеми слід виявляти?
- Що зробить такий звіт справді корисним у вашій щоденній роботі?
Код джерела проекту знаходиться у його репозиторії за адресою github.com/gkhan205/arcovia; пакет можна встановити безпосередньо з npmjs.com/package/arcovia, а повні документації розміщені на arcovia.ghazikhan.in.
Ідеї, відгуки та навіть критика є цілком бажаними, адже реальне використання — це найефективніший спосіб поступового вдосконалення Arcovia.
Пов’язана література
- 20 передових патернів Next.js для додатків App Router виробничого рівня — Дізнайтеся про двадцять патернів високого рівня для Next.js, які охоплюють серверно-орієнтоване проектування, стрімінг, кешування, маршрутизацію та оптимізацію продуктивності для створення швидших та масштабованих додатків.