Quartz 4

CONVENTIONS

6 min read

Meta

CONVENTIONS

Правила ведення документації

Аудиторія: розробник проекту. Це особистий довідник, не онбординг. Мета: за 10 секунд згадати значення/умову/послідовність під час дискусії чи рефакторингу. Цей файл також читається AI (Claude Code, Cursor) — правила написані так, щоб AI міг за ними створювати й оновлювати документи без додаткових пояснень.

Процес заповнення (як робити поетапно) — в AUTHORING.

Принципи

  1. Довідник, не туторіал. Пишемо так, щоб знайти потрібне за 10 секунд, а не читати з початку.
  2. UI — хребет, бек — опорні картки. Читач стартує з UI (що бачить у програмі) і переходить на бек за лінками (що це тригерить / звідки оновлюється).
  3. Схематично + нюанси. Не описуємо що робить кожна стрічка. Описуємо що є, в якому порядку, які числа/умови, які нюанси і чому вони такі.
  4. Чому, не як. Якщо рішення неочевидне — пояснюємо чому так зробили, не як зроблено на рівні синтаксису.
  5. Один файл — одна одиниця. UI-секція і бек-сервіс живуть у різних файлах і пов’язуються лінками.
  6. Файл ↔ нода Canvas. Кожен файл у docs/ має бути представлений як нода на Canvas.canvas. Якщо підтема надто мала щоб мати окрему ноду — зливаємо з батьківським файлом у секцію. Схованих файлів без ноди не повинно бути.
  7. Не посилайся на те, чого немає на Canvas. Wiki-лінки [[X]] у тілі файлів можна ставити тільки на файли які представлені нодою на Canvas. Якщо хочеться послатись на дрібну підтему — злий її у файл, який є на Canvas, і посилайся на нього (можна на секцію через [[файл#секція|Секція]]).

Межа глибини

Описуємо:

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

Не описуємо:

  • Синтаксис виклику методів
  • Деталі транспорту (fetch vs axios, Promise.race vs Promise.all) — якщо не впливає на поведінку
  • Інфраструктура без бізнес-логіки (IPC, ping між вікнами, tab-to-tab запити)
  • Імена полів і типи які очевидні з коду

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

Структура docs/

docs/
├── CONVENTIONS.md       # цей файл
├── Canvas.canvas        # головний вхід — візуальна мапа
├── ui/                  # UI-екрани, секції, колонки, діалоги
├── services/            # бек-сервіси: інтервали, сендери, runner'и
├── entities/            # сутності даних: чат, лист, нотатка, таск, інвайт
├── flows/               # процеси: логін, логаут, ініціалізація
└── system/              # інфраструктура: БД, settings, tabs, update
  • UI-файли — українською як в розмові в команді (Чат.md, Колонка фаворитів.md, Sleep Mode.md). Це єдина мова якою ми обговорюємо інтерфейс — нема сенсу вгадувати англ відповідник для пошуку.
  • Для meta і flow-кроків — kebab-case або просте англ («Login.md»).
  • Виняток: для бек-файлів що відповідають класу/сервісу в коді — PascalCase, щоб назва файлу збігалась з іменем класу (напр. NetworkService.md, ChatSender.md). Це робить навігацію між кодом і доками швидшою.
  • Допускається один рівень вкладеності якщо тема розгалужується (напр. entities/chat/Invites.md). Глибше — знак що треба рефакторити.
  • Home.md не використовуємо — вхід через Canvas.canvas.

Шаблон сторінки

Обов’язковий початок

#Тег1 #Тег2
 
[[Назва-файлу]]
 
# Людська назва
 
`контекстна стрічка: шлях в коді або "(UI-елемент)"` — одна фраза опису
  • Теги — тип сторінки (див. нижче). Один рядок, без ком.
  • Backlink [[Назва-файлу]] — для зворотного пошуку в Obsidian.
  • H1 — як називаємо в розмові (для UI), або назва класу/сервісу (для бек).
  • Контекстна стрічка — для бек: шлях `src/main/...ts`. Для UI: (UI-елемент) або (UI-секція).

Опційні секції (використовувати за потреби)

## Що це / Що показує
Один абзац: роль елемента в системі.
 
## Числа / Інтервали / Таймаути
Таблиця або список з бізнес-значеннями.
 
## Логіка / Умови / Фільтри
Пронумерований список або таблиця.
 
## Нюанси
Неочевидні моменти з поясненням *чому*.
 
## Зв'язки
- Тригерить: [[...]]
- Оновлюється від: [[...]]
- Читає: [[...]]
- Стартує: [[...]]
 
## Чому так
Пояснення неочевидних архітектурних рішень. Тільки коли справді є причина.

Порядок секцій — приблизно такий як вище, але можна адаптувати. Обов’язкова тільки «шапка» (теги + backlink + H1 + контекстна стрічка + одна фраза).

Типи сторінок і теги

ТипТегВміст
UI-елемент#UIЕкран, секція, колонка, діалог, тулбар
Сервіс#ServiceФоновий процес, сендер, runner
Інтервал#IntervalДодатковий тег для сервісів з таймером
Сутність#EntityСтруктура даних: чат, лист, нотатка, таск
Процес#FlowПослідовність кроків: логін, логаут, ініціалізація
Система#SystemІнфраструктура без бізнес-логіки (БД, settings, tabs)
Мета#MetaСамі конвенції, індекси

Теги можна комбінувати (#Service #Interval). Теги — єдиний інструмент фільтрації, тримаємо їх дисципліновано.

Правила для UI-сторінок

  • Назва — як звемо в команді («колонка фаворитів»), а не як в коді (FavoritesColumn.tsx)
  • Шлях до коду — опційний. Якщо компонент складний — можна вказати, але зазвичай не треба
  • Обов’язкова секція Зв'язки — звідки дані (лінк на бек-сервіс), що тригерить (лінк на дію)
  • Описуємо: які дані показуються, які дії доступні, які фільтри й стани, які обмеження
  • Не описуємо: верстку, стилі, компоненти, імена пропсів

Правила для Service-сторінок

  • Шлях у коді — обов’язковий у шапці
  • #Interval — якщо є таймер
  • Секції: Інтервал (якщо є), Логіка, Нюанси, Зв'язки
  • Нюанси зазвичай найцінніше: stop-листи, watchdog’і, захисти від подвійного запуску, рандомізації

Правила для Entity-сторінок

  • Описуємо структуру даних і ключові властивості сутності
  • Приклад: для Chat — два режими відправки (Limited/Unlimited), типи повідомлень, черга
  • Лінки на сервіси які цю сутність продукують/споживають

Правила для Flow-сторінок

  • Структура — пронумерований список кроків
  • Короткі flow (≤3 кроки) — описуємо в одному файлі
  • Довгі flow — окрема сторінка на крок, у головній тільки список з лінками

Посилання і підфайли

Робимо підфайл:

  • Підтема має ≥5 рядків специфіки, не вписується в батьківську
  • На підтему може бути посилання з іншого місця (самостійна одиниця)

НЕ робимо підфайл:

  • Кілька рядків — просто секція в батьківському файлі
  • Тема має сенс тільки в контексті батька

Backlink у кожному файлі — [[Назва-файлу]] одразу після тегів. Це дає Obsidian видимість у графі навіть якщо на файл мало хто посилається.

Canvas

Canvas.canvas — головний і єдиний вхід у документацію. Відкриваючи docs/, відкриваємо саме його.

Кольори по типах

ТипКолірHex
UIблакитний#64b5f6
Service (operator-level)зелений#66bb6a
Service (lady-level)рожевий#f48fb1
Entityфіолетовий#9575cd
Flowжовто-зелений#00c853
Systemтемно-зелений#66bb6a (з групою)

Типи стрілок (підпис на стрілці)

  • тригерить — натискання/подія запускає процес
  • оновлює — сервіс пише дані в UI/entity
  • читає — UI читає дані з entity/store
  • стартує — один сервіс стартує інший (ініціалізація)
  • per-анкету — зв’язок типу one-to-many через скоуп анкети

Групи

Обводимо ноди одного типу в групу з кольоровим підписом (наприклад «Інтервали оператора», «Сервіси ТЮ»).

Як оновлювати

  1. Після зміни коду — відкрий відповідний файл у docs/ і онови його частиною того самого коміту. Коміт з логікою без оновлення доків — це борг.
  2. Через AI — «онови docs/xxx.md під зміну в src/yyy.ts». AI читає цей файл і дотримується формату.
  3. При видаленні коду — видаляй і відповідні доки. Мертвих сторінок бути не повинно.
  4. При додаванні нової логіки — новий файл за шаблоном.

Оновлюємо коли: змінюються числа, умови, фільтри, порядок кроків, залежності між сервісами.

НЕ оновлюємо для: рефакторингу без зміни поведінки (перейменування змінних, чищення типів, форматування).

Для AI-асистентів

Коли тебе попросили створити або оновити документ:

  1. Прочитай цей файл повністю перед роботою з docs/
  2. Визнач тип сторінки (UI/Service/Entity/Flow/System) і використовуй відповідний шаблон
  3. Дотримуйся межі глибини: бізнес-нюанси — так, синтаксис/транспорт — ні
  4. Перевір чи не треба оновити пов’язані файли (секція Зв'язки)
  5. Після оновлення сервісу перевір чи не треба оновити UI-сторінку що читає його дані, і навпаки
  6. Якщо створюєш новий файл — додай його ноду в Canvas.canvas з правильним кольором і типовими зв’язками

Graph View

Backlinks