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

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

Класифікуйте класи за відповідальністю

R3el використовує власний Common Unified Development Process як стиль розробки. Класи поділяються за роллю:

Категорія	Відповідальність	Приклади
Interface	З’єднує технологію, API або протокол та керує механікою взаємодії.	`DbMgr` для MariaDB, `FileMgr` для файлової системи, класи транспорту ZeroMQ.
Activity	Перетворює, обчислює та виконує операції застосунку над даними.	Нормалізація метаданих, зіставлення записів каталогу.
Entity	Зберігає дані постійно або в пам’яті.	Запис медіафайлу чи результат у пам’яті.

Розділяйте обов’язки, щоб не створювати монолітні класи. Activity працює з Entity та звертається до Interface для читання, запису й зовнішньої взаємодії. Entity постійних даних не повинна одночасно керувати підключенням і механікою збереження.

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

Тут «interface class» означає технологічний адаптер. В інших розділах «інтерфейс» може означати публічний контракт компонента; сама наявність публічних методів не робить клас технологічним Interface.

Організовуйте код за відповідальністю

Групуйте компоненти в r3el/:

Пакет	Відповідальність
`app/`	Логіка програми й робочі процеси.
`activity/`	Спільні операції, зокрема встановлення схеми й підготовка подій.
`entity/`	Дані, наприклад MediaFile, MediaFileBatch, Identification.
`server/`	Точки входу серверів та оркестрація.
`interface/`	Зв’язок із зовнішніми службами й компонентами застосунку.
`constants/`	Спільні константи застосунку.
`zmq/`	Компоненти транспорту ZeroMQ.

Створюйте новий пакет лише коли для відповідальності потрібне окреме місце; структура має залишатися сфокусованою на реальній функціональності.

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

from r3el.constants.DR3el import DR3el

Код відображення та його ресурси тримайте разом і окремо від логіки. Ініціалізатори пакетів мають бути короткими. Для виконуваного пакета використовуйте __main__.py; під час рефакторингу зберігайте задокументовані точки входу.

Відділяйте значення операцій від механіки реалізації

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

Універсальні помічники не мають залежати від правил і схеми R3el. Рішення застосунку залишаються на рівні, що розуміє R3el; з’єднання рівнів виконується явно через композицію.

Довіряйте внутрішнім контрактам

Передавайте завдання LLM як JSON окремо від інструкцій. Спрощуйте дані перед поданням: сортуйте списки файлів, призначайте послідовні числові ID, зберігайте точні шляхи й таблицю ID на сервері. Детермінований код виконує облік, LLM — інтерпретацію.

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

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

Внутрішні помилки програмування мають виявлятися явно, навіть якщо це зупинить застосунок. Виправляйте першопричину та додавайте регресійний тест. Не ховайте помилки широкими except, мовчазними типовими значеннями, приведеннями типів чи гіпотетичним відновленням.

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

Використовуйте спільний рівень доступу до даних

Компоненти, що працюють із MariaDB, повинні використовувати один спільний рівень доступу. Відділяйте операції застосунку від механіки БД.

Інтерфейс програми відповідає за:

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

Помічник бази даних відповідає за:

Створення з’єднання MariaDB, облікові дані, тайм-аути й закриття.
Створення, використання й закриття курсорів; курсори не виходять за межі цього рівня.
Побудову SQL, перевірку та цитування ідентифікаторів і параметризовані значення.
Транзакції: початок, фіксацію, відкіт і лише-читання.
Узгоджену обробку результатів та помилки БД зі збереженою причиною.

Дозволяйте помилкам виходити з блоку транзакції, щоб помічник міг відкотити її й повідомити про збій. Обробляйте їх поза блоком; не придушуйте помилку й не продовжуйте виконувати SQL у тій самій транзакції. Покладайтеся на блокування рядків і обмеження MariaDB, а не дублюйте перевірки узгодженості.

Помічник БД не повинен знати правила R3el. Компоненти застосунку не створюють альтернативні механізми з’єднань або SQL. Побічні ефекти мають бути явними; відкриття з’єднання не повинно запускати сторонню роботу.

Тримайте перевірку конфігурації за одним інтерфейсом

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

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

Рефакторинг маленькими кроками для перевірки

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

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

Запускайте відповідні тести. Для меж рівнів перевіряйте атомарність транзакцій, відкіт, очищення ресурсів, перетворення помилок і використання спільних інтерфейсів. Перевіряйте точки входу й завантаження ресурсів після переведення модуля в пакет.

Розрізняйте нові та наявні помилки. Явно повідомляйте обмеження перевірки, зокрема коли не запускали тести з реальною БД.

Використовуйте процеси BMForge вибірково

Користуйтеся правилами BMForge, де вони корисні для конкретної задачі. R3el зберігає власну архітектуру, правила коду, залежності, гілки, інструменти встановлення та процес випусків. Не перетворюйте R3el на новий проєкт BMForge, не встановлюйте початковий greenfield-каркас і не переписуйте код задля формальної відповідності. Читання специфікацій не означає відповідності та не дозволяє міграції.

Використовуйте такі процеси за потреби:

До реалізації визначайте результат і перевірні критерії прийняття. Пряме прохання реалізувати функцію дозволяє виконати саме її без додаткового погодження кожного файлу. Для суттєвого розширення обсягу, нових залежностей чи архітектурних змін потрібно схвалення.
Перевіряйте відповідну поведінку пропорційними тестами. Повідомляйте виконані перевірки, старі помилки й обмеження; оновлюйте документацію та списки файлів встановлення, якщо завдання їх зачіпає.
Для розслідування виробничих проблем дотримуйтеся BMForge RCA: лише читання з дозволених серверів, далі відтворення й виправлення локально.
Для дозволеного розгортання спочатку перевіряйте служби, файли, конфігурацію й дані, захищайте параметри користувача та збережені дані й перевіряйте встановлену поведінку. Користуйтеся інструментами R3el; публікація релізу та розгортання — окремі дії.
Для релізів використовуйте scripts/new-release.sh та наявні правила гілок. Коміти, push, релізи й розгортання вимагають окремого дозволу; дозвіл реалізувати не включає їх автоматично.

Перед першим редагуванням, пов’язаним із BMForge, у сеансі виконуйте локальну перевірку лише для читання з кореня репозиторію:

python3 .agents/bmforge/manage.py check --project .

Повідомляйте про доступні оновлення або недоступність перевірки. Вона використовує локальний знімок і не завантажує upstream. Продовжуйте з зафіксованими навичками; оновлення або нові навички потребують явного дозволу.

Оновлюйте CHANGELOG.md

Для кожної завершеної логічної зміни дотримуйтеся процесу ведення журналу BMForge:

Оновлюйте CHANGELOG.md у межах того самого завдання, до повідомлення про завершення чи коміту. Зазначайте дрібні виправлення, тести, документацію, налаштування, залежності й технічні роботи, а не тільки функції.
Завершені результати записуйте в єдиний розділ ## [Unreleased], пояснюючи, що змінилося й навіщо. Об’єднуйте пов’язані файли в один короткий запис на логічну зміну; не описуйте відкинуті спроби чи незавершені плани.
Для суттєвих покращень додайте або оновіть один ### Summary відразу під ## [Unreleased]. Достатньо одного-двох речень зрозумілою мовою. Для дрібного виправлення помилки друку може вистачити одного пункту.
У кожному розділі — не більше одного Summary. У міру нових змін освіжайте його. Використовуйте ### Added, ### Changed, ### Fixed, ### Removed за потреби, без порожніх заголовків.
Перед передаванням перевіряйте, що кожну завершену зміну описано, Summary актуальний, а старі неопубліковані записи й історія випусків збережені.
Номери версій, дати й кодові назви належать наявному процесу релізів R3el. Скрипт релізу переносить неопубліковані записи під нову версію й залишає Unreleased для наступної роботи.

Nadim-Daniel Ghaznavi

Правила розробки