Як створювати і заповнювати документацію

CONVENTIONS — це правила формату. Цей файл — процес як реально побудувати доки з нуля або оновити існуючі. Читається як чекліст.

Головний принцип

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

Цикл заповнення ноди (універсальний)

Діє для UI, сервісу, сутності, flow — будь-якого файлу.

Юзер → важливі речі. Числа, умови, нюанси, причини. Без художки.
AI → аналіз + уточнення. Якщо є прогалини або двозначності — 3-5 вузьких питань. Якщо все зрозуміло — одразу п. 3.
AI → формулювання. Текст під шаблон сторінки. Тільки те що юзер сказав. Ніяких «для повноти».
Юзер → рев’ю і правки. Просить доповнити/виправити/прибрати. Повторюємо 2-4 поки не ок.
Фіксація → наступна нода.

Стоп-сигнали:

AI починає вигадувати деталі → зупиняємось, лишаємо TODO.
Юзер просить «розпиши глибше» без нових фактів → значить дійшли до межі знань, більше нема що додати.

Сценарій 1 — Старт у новому проекті

Робиться один раз при внесенні документації в новий репозиторій.

Скопіювати docs/CONVENTIONS.md з еталонного проекту
Скопіювати docs/AUTHORING.md (цей файл)
Створити CLAUDE.md в корені репо з посиланнями на CONVENTIONS.md і AUTHORING.md
Створити docs/glossary.md (порожній) — заповнюватиметься по ходу
Створити порожній docs/Canvas.canvas
Відкрити docs/ у Obsidian як vault

Сценарій 2 — Опис UI з нуля

Для нової програми або нової вкладки якої ще нема в доках. Протестовано — цей порядок дає найменше churn’у.

Фаза A — Скелет структури

Скріни з підписами блоків. Paint/Figma — виділити логічні зони прямокутниками і підписати назвами з розмови («колонка фаворитів», «хедер»). Не описувати що робить — тільки як називається.
Скинути скріни AI одним повідомленням. Попросити: структурно підсумувати що бачить + запитати термінологію яку не впізнав. Не просити одразу писати файли.
Термінологія → glossary. Перед створенням скелету зафіксувати всі абревіатури (RU, TU, LT, Pause, whitelist тощо). Без глосарію AI буде гадати і накидати різні варіанти.
Папки: AI створює docs/ui/, services/, entities/, flows/, system/. Імена UI-файлів — українською (див. CONVENTIONS).
Скелет UI-файлів. AI за шаблоном робить порожні сторінки: шапка + H1 + контекстна стрічка + порожні секції. Логіку не заповнюємо — тільки структура.
Canvas скелет. AI створює ноди для кожного файлу + групи по екранах (Login screen / App хедер / Workspace screen / Sender screen). Лінки і стрілки — в наступній фазі.

Фаза B — Заповнення по одній ноді

Йдемо послідовно, по одному файлу. Не більше одного в роботі.

Юзер видає важливі речі — що на цьому екрані/елементі дійсно важливо: числа, умови, фільтри, нюанси, нетипова поведінка. Короткими фразами, без художки.
AI аналізує і уточнює. Знаходить прогалини, суперечності, незрозумілі місця — задає 3-5 вузьких запитань. Якщо питань нема — одразу формулює.
AI формулює текст під шаблон сторінки. Без додаткових абзаців «для повноти» — тільки те що юзер сказав, переведене в структурований формат.
Юзер рев’ює результат: читає, просить редагувати неточності, прибрати зайве, доповнити пропущене.
Фіксуємо → переходимо до наступної ноди.

Правило зупинки: якщо AI починає вгадувати або додавати «для повноти» — юзер зупиняє. Краще лишити TODO: уточнити X ніж написати неправду.

Фаза C — Зв’язки з беком

Коли всі UI-файли заповнені — проходимо по кожній секції Зв'язки і додаємо лінки на бек-сервіси. Canvas дістає стрілки між UI і сервісами.

Сценарій 3 — Опис бек-сервісу з існуючого коду

Вказати AI шлях до файлу коду (src/...).
AI читає код і створює скелет за шаблоном Service: шапка з шляхом + Інтервал (якщо є) + Логіка + порожні Нюанси / Зв'язки.
Уточнення нюансів і причин. Це найцінніше в бек-доках. AI запитує або пропонує варіанти, розробник підтверджує/виправляє:
- чому саме такий таймаут
- чому саме такий захист (watchdog, stop-list, isBusy)
- які були інциденти/суперечки які сформували це рішення
Лінки на UI що показує результати цього сервісу — в Зв'язки.

Сценарій 4 — Опис Flow (процесу)

Напр. логін, логаут, ініціалізація ранера.

Назвати крок-за-кроком послідовність дій (AI читає код і пропонує, розробник коригує).
Якщо кроків ≤3 — описуємо в одному файлі секціями.
Якщо ≥4 — оглядова сторінка зі списком + окремий файл на крок.
Кожен крок отримує секції Що робить, Нюанси (якщо є), Зв'язки.

Сценарій 5 — Оновлення при зміні коду

Після зміни бізнес-логіки відкрити відповідний файл у docs/.
Коротко сказати AI: «онови docs/xxx.md під зміну в src/yyy.ts».
AI читає зміну, порівнює з поточним доком, робить правки. Людина рев’ює.
Якщо забули — AI нагадає при наступній дотичній задачі (через CLAUDE.md).

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

Сценарій 6 — Canvas

Canvas — візуальна мапа, головний вхід у доки.

Оновлюємо після того як тематична група файлів стабілізувалась (не після кожного окремого файлу — це churn).
Новий файл → нова нода на Canvas з кольором відповідного типу (див. CONVENTIONS → Canvas).
Стрілки підписуємо однаково: тригерить / оновлює / читає / стартує.
Групи (обведення прямокутником) використовуємо для ≥3 нод одного типу в одному місці.

Правила розмови з AI

Що говорити:

Точний шлях файлу коду або назву UI-елемента
Що саме змінилось (одна фраза)
Який файл у docs/ онови або створи

Що AI має робити само:

Читати CONVENTIONS перед роботою з доками
Задавати вузькі питання коли йому бракує інформації (не гадати)
Пропонувати оновити пов’язані файли через Зв'язки
Після оновлення нагадувати про Canvas якщо структура змінилась

Антипатерни:

«Опиши весь сендер» — надто широко, AI напише полотно → перевантажить деталями. Краще: «зроби скелет chat-sender.md за шаблоном і задай питання по нюансам».
Заповнювати одразу всі 20 файлів — втратиш якість, не зможеш рев’ювити уважно.
Описувати реалізацію замість поведінки (див. правила глибини в CONVENTIONS).

Чеклист перед комітом змін у docs/

Новий файл має шапку за шаблоном (теги + backlink + H1 + контекстна стрічка)
Тип теги правильний (#UI, #Service, #Entity, #Flow, #System, #Meta)
Секція Зв'язки заповнена або свідомо пропущена
Жодних описів синтаксису/транспорту без впливу на поведінку
Нові терміни додано в glossary
Якщо структурний файл — оновлено Canvas

Quartz 4

Explorer

AUTHORING