Перейти до основного вмісту

Організований робочий процес.

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

Що потрібно агенту від фреймворку.​

Штучному інтелекту, який генерує код для роботи з незнайомим API, зазвичай потрібні:

  1. Невелика загальнодоступна площа — менша кількість типів означає, що потрібно вивчити менше.
  2. Типи, що самостійно описують себе — сигнатура типу має містити повне визначення контракту, а не лише натякати на нього.
  3. Один із способів виконання кожної дії — наявність кількох еквівалентних шляхів є саме тим типом вибору, в якому агент може помилитися.
  4. Суміжні документи — агент читає короткі описи @brief, а не великі технічні документи на 8000 рядків. Важливий контекст має бути розміщений поруч із відповідним символом.
  5. Детерміновані результати — коли агент створює знімки для тестування, детермінованість на рівні окремих байтів забезпечує їхню стабільність.
  6. Помилки, які вказують на першопричини — коли щось не працює, повідомлення про помилку має чітко вказувати, який саме модуль/контракт/параметр є несправним, а не просто «Збірка графа не вдалася».
  7. Артефакти для відтворення помилки — якщо код агента працює некоректно, він може вставити рядок repro_gst_launch у налагоджувач і повторювати спроби без повторного запуску агента.
  8. Відсутність прихованих глобальних змінних — кожна поведінка має бути аргументом конструктора або опцією Node, а не змінною середовища, яка зчитується під час виконання.
  9. Стабільні ідентифікатори — однакові вузли + однакові параметри ⇒ однакові назви елементів ⇒ однакова команда запуску ⇒ стабільні тестові набори.
  10. Архів моделі як дані, а не код — модель є набором даних, який завантажує фреймворк, а не заголовком, який агент має скомпілювати.
  11. Компоненти, з яких можна створювати складні структури — вузли, моделі та фрагменти графа, які можна повторно використовувати, легко поєднуються; агенту не потрібно знати, які комбінації «підтримує» фреймворк, оскільки планувальник визначає це під час створення.
  12. Гучна перевірка під час збирання — помилки виявляються на етапі Graph::build(), а не під час першого pull(). Цикл ітерацій агента потребує, щоб на помилку було вказано у відповідному рядку коду.
  13. Структурований GraphReport — програмний доступ до інформації про те, що було виконано під час збірки, щоб агент міг перевірити результати своєї роботи.
  14. Поступове розкриття інформації — Model — це найпростіший шлях, Graph::add() — наступний, а спеціальні вузли — це більш складний шлях. Агент спочатку обирає найпростіший шлях.
  15. Версіоновані контракти MPK — архів моделі містить достатньо метаданих, тому агенту, який генерує код на основі цих даних, не потрібно звертатися до зовнішньої документації.

Вони проявляються в усій структурі як конкретні рішення щодо проєктування:

  • Невелика загальнодоступна поверхня (модель, тензор, зразок, вузол, граф і виконання) – це все, що потрібно агенту для навчання, щоб застосовувати код.
  • Graph::describe() повертає структурований звіт, що містить основні відомості про план, — агенти можуть перевіряти власні конвеєри.
  • NeatError містить error_code() і GraphReport — агенти можуть активувати цей код.
  • Node::backend_fragment() є детермінованим — агенти можуть створювати тестові приклади, що містять «золоті рядки», для перевірки роботи конвеєрів.
  • MpkContract — це єдиний авторитетний опис моделі, і агентам, які генерують код для з’єднання на основі цієї моделі, більше нічого не потрібно.

Яка вигода для розробників застосунків?​

Навіть якщо ви не є розробником, ви отримаєте вигоду від зручного для розробників дизайну API: ті самі характеристики, які роблять автоматизоване генерування коду надійним, також полегшують ручну перевірку коду, роблять рефакторинг безпечнішим, а розробку з використанням штучного інтелекту (Claude Code, Copilot, Cursor) — продуктивнішою для коду Modalix.

Для подальшого ознайомлення​

  • «Представляємо Neat» — розділ 0.1, присвячений детальному аналізу дизайну.
  • Graph::describe() — стислий огляд програмного плану.
  • NeatError — структурований тип помилки.
  • Model — завантажено архів моделі та проаналізовано контракт MPK.