Розширення та система знань

Репозиторій, текстове виробництво й публікаційна архітектура курсу

Коли коротка Jira-задача просить пояснити складну тему, авторові легко відразу попросити агента «написати главу». Але до тексту ще треба з’ясувати, що…

Глава 75Заморожене українське видання

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

У цій главі ми розглянемо три пов’язані рішення: який файл є джерелом знань; як із перевіреного дослідження зробити повну навчальну главу; як провести її через рецензування (review) та публікацію так, щоб вебкнига не підмінила редагований текст.

Навчальний результат

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

Потрібні поняття з попередніх глав: Git як історія змін, Markdown як текстовий формат, зміст і передумови курсу, Pull Request (PR — запит на включення змін до спільної гілки), агентні інструкції та перевірка результатів. Практичні приклади нижче повністю розібрані авторами; це навчальні пояснення, а не вправи для читача.

Блок A. Джерела та формати

1. Репозиторій зберігає редагований оригінал

Джерело книги — текстові файли, які можна відкрити, прочитати, змінити, переглянути в різниці між ревізіями й відновити з історії Git. За стандартом курсу, визначеним в Epic A1M-28 і конкретизованим у A1M-103, редагованим першоджерелом є модульні файли Markdown (.md) або Quarto Markdown (.qmd). Одна задача відповідає темі, але велика тема може мати кілька змістовно пов’язаних підглав. Моноліт на весь курс ускладнює рецензування й розподіл відповідальності; десятки дрібних файлів без навчальної причини ускладнюють навігацію.

Стан репозиторію потрібно прив’язувати до конкретної ревізії. Перший перевірений знімок main у commit fa561feca48fd8c1662beee0b13170f27581fc7c, від 23 вересня 2026 року, містив README.md і глави 1–31, але не конфігурацію Quarto чи збірку книги. До фіналізації цієї глави курс виріс: знімок main у commit fde287efd92cedcc13906e9e58e304eebcd87148, перевірений 25 вересня, містить глави 1–74, _quarto.yml, перевірку реєстрації глав і автоматизований процес безперервної інтеграції (continuous integration, CI). Він збирає HTML (HyperText Markup Language — мова гіпертекстової розмітки), PDF (Portable Document Format — формат документа зі збереженим компонуванням) через Typst, EPUB (Electronic Publication — електронне видання) та документи Word (.docx), а тоді зберігає результат як тимчасовий артефакт. Процес перевіряє й пакує книгу, але не публікує її на відкритому сайті; перевірені файли репозиторію не містять окремого кроку розгортання, а зовнішні налаштування хостингу не перевірялися. Стандарт курсу визначає модульні .md / .qmd файли як редаговане першоджерело, а HTML-книгу — як основний формат читання.

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

Матеріал	Яке запитання закриває
README.md	Що це за курс, де його зміст, як зробити внесок і як знайти актуальні інструкції?
Специфікація курсу та список глав	Які цілі курсу, порядок тем і правила приймання?
Jira-задача	Який конкретний навчальний результат, зміст, приклади й критерії цієї глави?
Модульна глава у форматі .md або .qmd	Що читачеві потрібно зрозуміти й чому?
Нотатки дослідження	На які питання автор шукав відповідь, що саме прочитав, що підтверджено й що лишилося невідомим?
Налаштування збірки, наприклад _quarto.yml	Які файли входять до книги, у якому порядку й у які формати їх збирають?
Зібраний сайт або файл книги	Що читач відкриває після побудови, але не редагує як першоджерело?

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

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

2. Розрізняйте джерело, збірку й публікацію

HTML-книгу затверджено як основний формат читання, але вона не стає редагованим оригіналом лише тому, що її відкриває браузер. PDF та EPUB можуть бути додатковими похідними форматами. Бібліотека Конгресу США подає Electronic Publication як повну назву та описує EPUB як формат цифрових публікацій. Рекомендація Консорціуму Всесвітньої павутини (World Wide Web Consortium, W3C — міжнародна організація, що розробляє вебстандарти) EPUB 3.3 описує технічний формат як спосіб пакувати структурований вебвміст у контейнерний файл (Library of Congress: опис формату EPUB; W3C: специфікація EPUB 3.3). Усі ці формати створюються з текстових джерел і конфігурації. Якщо в збірці виявлено друкарську помилку, її виправляють у джерелі й будують файл заново; ручна правка згенерованого HTML зникне під час наступної збірки.

Quarto Books — засіб, яким цей репозиторій збирає затверджену HTML-книгу: він пов’язує окремі документи конфігурацією проєкту, підтримує навігацію й може створювати HTML, PDF, EPUB та інші формати. Документація Quarto вказує типовий каталог результатів _book, але проєкт може задати інший (налаштування виходу книги). У перевіреній ревізії main конфігурація _quarto.yml описує книгу, а список її файлів задає порядок глав. Наявний процес безперервної інтеграції перевіряє збірку, проте не має кроку публічного розгортання; зовнішнє налаштування хостингу цією перевіркою не встановлено. Документація Quarto про книги і структуру книги показують, як файл-зміст пов’язує окремі глави в один читацький продукт.

Межу між редагованим джерелом, затвердженим форматом читання й можливими додатковими виходами можна уявити так:

Шар	Приклад	Чи редагуємо безпосередньо?	Роль
Редаговане джерело	Модульні глави .md або .qmd, зокрема файл цієї глави	Так	Первинний текст для змін і версійної історії.
Конфігурація книги	`_quarto.yml`	Так, через окрему погоджену зміну	Список матеріалів, навігація й параметри виходу для Quarto; CI перевіряє конфігурацію на PR.
Локальна збірка	`_book/` за типової конфігурації Quarto	Ні, відтворюємо зі джерела	Похідний результат для перевірки; те саме налаштування збирається в CI.
HTML-книга	Зібраний HTML і його ресурси	Ні, відтворюємо з прийнятого джерела	Затверджений основний формат читання книги.
PDF або EPUB	Файл, побудований з того самого рукопису	Ні	Можливі додаткові завантажувані формати, якщо їх погоджено.

Quarto рекомендує створювати проєкт книги з індексною сторінкою та переліком глав у конфігурації; його HTML-книга є спеціальним видом вебсайту. Водночас верстка PDF, підтримка частин книги у форматах і назви опцій можуть змінюватися. Такі деталі слід брати з поточної документації та перевіряти реальною збіркою, а не переписувати з пам’яті.

Публікація теж окремий шар. За стандартом курсу модульні .md / .qmd файли є редагованим першоджерелом, а HTML-книга — основним форматом читання. У поточній конфігурації вже є Quarto-збірка, але перевірений CI лише створює файли для огляду; у його налаштуваннях немає кроку розгортання публічного сайту. Quarto є вже обраною реалізацією книги, тоді як місце, власник і дозволений процес публічного випуску мають визначатися окремо. Зібраний сайт лишається похідним артефактом, а не авторським текстом. Якщо для хостингу потрібні зібрані файли в спеціальній гілці або каталозі, це має бути явною домовленістю про процес. Збірка й публікація можуть мати окремі перевірки та дозволи.

3. Документи знань та агентні інструкції мають різні ролі

Довідкова інформація, продуктова інструкція, авторський процес, контроль доступу й автоматична перевірка — не один механізм. README вводить людину в репозиторій; специфікація курсу тримає спільні цілі; Jira-задача звужує обсяг конкретної глави; сама глава навчає; агентна інструкція задає поведінкові очікування для конкретного інструмента. Жоден текстовий файл сам по собі не є технічним бар’єром проти забороненої дії.

Codex сьогодні документує власні глобальні інструкції поза проєктом, правила репозиторію та вкладені правила з визначеним порядком; є також файли-перевизначення (override), резервні назви файлів (fallback) та обмеження сукупного обсягу. Офіційна документація Claude Code описує окрему семантику CLAUDE.md, правил і читання AGENTS.md. За актуальними документами Claude Code напряму читає AGENTS.md, починаючи з v2.1.277, але умови залежать від наявності інших файлів інструкцій, налаштування та режиму сесії. Це важливий приклад зміни в продукті: не можна припускати, що одна назва файла має однакове значення в кожній версії й кожному середовищі. Документація Codex про AGENTS.md та документація Claude Code про пам’ять проєкту є чинними описами цих конкретних клієнтів на дату дослідження, не універсальним стандартом.

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

Інструкції теж не повинні накопичувати історію збоїв без аналізу причини. Якщо агент помилився через невідомий порядок глав, іноді корисніше додати коротке правило про джерело порядку, ніж вставити в кореневий файл увесь план курсу. Якщо помилка вимагає заблокувати команду або шлях, поведінкового нагадування може бути недостатньо: потрібен окремий механізм керування правами, ізольоване середовище виконання (sandbox) або автоматизована перевірка безперервної інтеграції (CI — Continuous Integration). Підтримуйте знання поруч із джерелом і власником; не перетворюйте кожне виправлення на довічне правило.

Блок B. Будова повноцінної глави

4. Від питання до зрозумілого висновку

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

Корисна послідовність:

Ситуація або запитання: яку практичну невизначеність читач має розв’язати?
Навчальний результат: що людина зможе пояснити після читання?
Передумови: які поняття вже знайомі, а які треба коротко нагадати чи вперше визначити?
Механізм: як явище працює, які компоненти взаємодіють і де проходить межа?
Повні приклади: вхідна ситуація, вибір дії, наслідок, пояснення й невдалий варіант або альтернатива.
Межі та компроміси: коли метод не підходить, на які дані чи умови спирається?
Підсумок: не повторення заголовків, а короткі рішення й сигнали для розпізнавання.
Локальні джерела та нотатки дослідження: читач може простежити важливі твердження до матеріалів, які автор справді читав.

У багатотемній главі кожен ключовий блок має отримати потрібний контекст і приклад. Структура Jira-задачі задає мінімальні вимоги, але автор має з’єднати їх у навчальну логіку, не зводити главу до точного копіювання переліку пунктів.

5. Приклад навчає, але не стає домашнім завданням

API (Application Programming Interface — програмний інтерфейс взаємодії) — спосіб, яким програми домовляються про запити й відповіді. Щоб читач зрозумів, чому перелік результатів запиту API є лише частиною контракту, автор сам проходить цілісний розбір: називає учасників, показує запит і відповідь, пояснює погоджені очікування, відстежує помилкову зміну та формулює межу висновку. Не слід після пояснення писати «тепер самостійно опишіть свій API» — це перетворює приклад на невиконану вправу.

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

У кожній самостійній главі нові англійські абревіатури розшифровують при першій появі, перекладають і пояснюють простими словами. Наприклад: «PR (Pull Request — запит на включення змін)». Назви продуктів і протоколів, які не є абревіатурами, не треба штучно розшифровувати. Англійські назви механізмів варто зберегти для пошуку, але поряд дати зрозуміле пояснення українською.

Тон має бути доброзичливим і точним. Не замінюйте пояснення рекламною тезою про швидкість агента, не перетворюйте складний компроміс на правило «завжди робіть X» і не приписуйте читачеві знання з невказаної сфери. На початку пояснюйте термін до того, як на нього спирається наступний абзац.

Блок C. Дослідження, книжки й джерела

6. Починайте з питань, не зі списку посилань

Дослідження для глави — це короткий процес з перевіреними відповідями:

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

Починайте з офіційних специфікацій, документації продукту, матеріалів автора й першодосліджень або інженерних звітів. Для практичного досвіду перевіряйте автора, дату, контекст, версію, що саме було відтворено й чим завершилось. GitHub PR, issue, discussion або код можуть показати реальну історію рішення; випадкова публікація або позитивні реакції самі по собі не доводять, що метод універсально працює.

Наприклад, OpenAPI Specification — специфікація опису вебпрограмного інтерфейсу (API, Application Programming Interface) — прямо визначає себе як машиночитаний та зрозумілий людині опис інтерфейсу. З цієї властивості можна обережно вивести, що формальний опис може зменшити здогадки клієнта про доступні операції. Але одна специфікація не доводить, що кожна реалізація відповідає їй або що схема повністю описує бізнес-правила. Для цих тверджень потрібні окремі перевірки й джерела. У цьому прикладі використано версію 3.2.1 від 10 вересня 2026 року. OpenAPI Specification v3.2.1

Для технічного продукту фіксуйте, про який саме продукт і інтерфейс ідеться: Codex у застосунку, термінальному інтерфейсі чи хмарному середовищі; Claude Code, Claude chat чи API. Назва компанії не визначає однакову поведінку для всіх її продуктів. Прайси, доступність, назви моделей, шляхи конфігурації, релізний статус і можливості конкретних клієнтів змінюються; повертайтеся до офіційної сторінки на дату написання.

7. Зберігайте журнал, який дозволяє продовжити перевірку

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

Поле запису	Приклад
Питання	Чим відрізняється файл інструкцій від правила, яке реально обмежує інструмент?
Прочитаний матеріал	Офіційна документація Codex про AGENTS.md та Claude Code про CLAUDE.md і AGENTS.md; звірено 10.10.2026.
Що підтверджено	Конкретні клієнти мають описану документацією семантику завантаження; сама інструкція задає контекст, а окреме налаштування може застосовувати обмеження.
Що не підтверджено	Немає доказу, що всі версії, постачальники чи режими однаково завантажують ті самі файли.
Наслідок для тексту	Пояснити версійність, назву продукту й дату; не називати AGENTS.md універсальним стандартом.

Записуйте джерело відразу після читання, а не наприкінці дня з пам’яті. Для сторінки зі змінним вмістом вказуйте дату доступу; для специфікації чи релізу — точну версію й дату випуску; для коду, PR або issue — пряме посилання на файл, ревізію чи окрему дискусію, коли важливий точний стан. Якщо сторінка перенаправляє на нову документацію, фіксуйте актуальну адресу й помітну зміну маршруту за потреби.

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

Ідею з книги потрібно вплести в міркування, а не лишити одним записом у списку літератури. У цій главі використано як аналогію підхід E-Myth: робота має повторювану систему й не повинна залежати від пам’яті одного виконавця. Ми спираємося лише на статтю E-Myth про ролі техніка, менеджера й підприємця; повний текст книги тут не читався, а стаття є матеріалом E-Myth, написаним Трішією Гюбнер, а не уривком, який можна приписати Майклу Герберу. У головному тексті це адаптація до процесу написання, не доказ про продуктивність агентів штучного інтелекту. Стаття E-Myth про три ролі

Блок D. Організація виробництва й приймання

8. Повторюваний процес для окремої глави

Щоб якість не залежала від того, що один автор пам’ятає, завдання проходить видимі етапи. Люди можуть поєднувати ролі, але важливі твердження мають перевірятися за матеріалами й доказами, а не за кількістю агентів, які з ними погодилися.

Етап	Рішення автора	Результат, за яким це перевіряють
Приймання	Прочитати поточний README, інструкції репозиторію, специфікацію курсу, опис задачі та доступні сусідні глави. Позначити чого ще немає.	Чітко визначені результат навчання, обсяг, передумови й критерії; не вигадані каталоги чи налаштування.
Дослідження	Перетворити невідоме на питання та таблицю «твердження — джерело — версія/дата — межа». Прочитати джерела, а не лише результати пошуку.	Джерело підтверджує саме те твердження, для якого його цитують; прогалини лишилися видимими.
План	Побудувати логічний ланцюжок понять, визначити два або більше повних прикладів і пояснити місце глави в курсі.	План охоплює всі критерії й не вимагає від читача вправи чи знання наступних глав.
Написання	Пояснити механіку простими словами, визначити терміни до використання, додати повні приклади, помилки й альтернативи.	Це навчальний текст, а не новий план, список посилань або перелік термінів.
Перевірка джерел	Звірити кожен мінливий факт, версію, адресу, цитату та приклад. Позначити невідоме.	Посилання відкрите; версія/дата читається; немає твердження, сильнішого за джерело.
Технічне рецензування	Незалежно звірити механізми, умовні обчислення, шляхи конфігурації та різницю між виконаним і прикладним кодом.	Не названо виконаними перевірки, яких не запускали; продуктові функції віднесено до точного клієнта.
Редакторське рецензування	Перевірити причинність, терміни, переходи, тон, повноту прикладів і зв’язки із сусідніми главами.	Новачок може зрозуміти рішення й межі, не виходячи з глави шукати визначення.
Перевірка збірки	Для затвердженої HTML-книги відкрити локальний попередній перегляд або побудувати саме змінені формати за наявною конфігурацією Quarto.	Перевірено навігацію, локальні посилання та результат збірки; вказані фактично виконані команди й відомі прогалини.
PR	Показати зміни, пов’язати їх із Jira-задачею, додати карту покриття, джерела й дати, фактичні перевірки та невизначеності.	Reviewer може швидко зіставити текст із вимогами й доказами.
Приймання та публікація	Власник репозиторію переглядає й схвалює зміни. Публічне розгортання виконує лише затверджений процес.	Немає прихованого merge чи публікації з чернетки; актуальна збірка походить з прийнятої ревізії.

GitHub описує гілки як спосіб ізолювати роботу, а PR — як пропозицію змін; рецензент бачить коміти, файли та різницю між базовою й запропонованою версіями. Для спільної роботи важливі не тільки зелені автоматичні перевірки: вони не замінюють технічну й навчальну оцінку змісту. У PR-описі цієї книги корисно вказати пункт Jira, перелік файлів, які критерії покрито, які джерела реально прочитані, коли перевірено мінливі твердження, які команди справді запускались і що ще не перевірено. GitHub: створення PR та рецензування запропонованих змін описують загальний механізм; налаштування захисту гілок і обов’язкових рецензентів залежить від конкретного репозиторію. Не зливайте й не публікуйте зміни автоматично без належного доручення.

9. Від локального попереднього перегляду до публікації

У знімку репозиторію від 25 вересня 2026 року, зафіксованому в commit fde287efd92cedcc13906e9e58e304eebcd87148, Quarto вже налаштовано в кореневому _quarto.yml: проєкт має тип book, джерела впорядковані за частинами курсу, а HTML, PDF через Typst, EPUB і Word описані як вихідні формати. Зміна для глави 75 додає її файл до списку в частині XI; scripts/check-chapters.sh перевіряє, що файли глав зареєстровані й існують. Це конкретна реалізація стандарту, а не припущення про майбутню конфігурацію.

У тому самому історичному знімку файл .github/workflows/build.yml запускав перевірку структури для PR і змін у main, встановлював Quarto 1.10.18, виконував quarto render, перевіряв вихідні файли й завантажував повну книгу та окремі формати як артефакти на 14 днів. Перевірений PR #83 історично зібрав HTML, PDF, EPUB і Word у GitHub Actions за 9 хвилин 13 секунд. Це результат CI на тому PR, а не локальна збірка цієї глави. Workflow прямо зазначав, що нічого не публікує; документація Quarto відрізняє побудову налаштованих форматів від окремо обраної публікації (Quarto: створення книги і основи публікації).

Цей опис стосується саме закріпленого знімка: у origin/main, перевіреному під час підготовки цієї редакції, .github/workflows/build.yml уже відсутній. Тому наведений workflow і строк зберігання артефактів є історичним прикладом; вони самі по собі не доводять, який процес CI чи публікації діє зараз. Наявність _quarto.yml доводить конфігурацію джерел і вихідних форматів, але не зовнішній хостинг чи фактичний публічний реліз.

У зафіксованому workflow були три видимі стани:

Джерело редагується: зміни є у гілці PR; повний список змін і текст доступні для рецензування.
Артефакт попереднього перегляду: CI збирає формати й прикріплює їх до запуску. У цьому історичному процесі їх використовували для перевірки, не як публічний сайт; через 14 днів артефакти видалялися.
Прийнятий випуск: після перевірки, злиття та дозволу власника публічну версію формує окремий видавничий процес. У закріпленому workflow такого кроку не було; зовнішній хостинг тим знімком не встановлено.

Окремо власник курсу має визначити, хто схвалює публічне розгортання, де зберігаються сталі копії видань і як попередній перегляд відрізняється від доступної всім версії. Тимчасовий CI-артефакт доступний із конкретного запуску й згодом видаляється; він не замінює постійний сайт чи архів.

Якщо після приймання вручну змінити HTML на сервері, а не джерело, наступна збірка поверне старий текст і не відтворить виправлення. Якщо редагувати лише PDF, вебкнига лишиться з іншою версією. Якщо згенеровані файли потрібно зберігати в репозиторії для конкретного хостингу, позначте їх як похідні, зафіксуйте спосіб відтворення та визначте, хто перевіряє відповідність джерелу. Не підміняйте текстову задачу розробкою системи публікації, налаштуванням системи керування навчанням (LMS — Learning Management System) чи випуском бінарних видань.

10. Підтримка глави після приймання

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

У реальному docs-репозиторії одна сторінка може бути частиною ширшого навігаційного дерева, мати локальний стиль, збірку й попередній перегляд. README відкритого репозиторію quarto-web описує опубліковану документацію, локальну збірку й попередній перегляд, а також різницю між зміною звичайного Markdown-документа та документа з обчисленнями. Це приклад живого процесу, а не рекомендований шаблон, який треба механічно перенести в невеликий курс. Закріплений README репозиторію quarto-web

Його PR №1555 показує, що навіть мала документаційна зміна потребує перевірки місця й повного контексту: автор запропонував ширше пояснення заголовків callout-блоків — виділених у тексті приміток, порад або попереджень, — а рецензент обговорював, чи має цей матеріал бути в розділі мовних опцій замість поточної сторінки; бот автоматичного розгортання підготував попередній перегляд сайту. Сторінка PR була позначена як відкрита на дату перегляду, тому цей PR показує процес обговорення, а не доказ, що саме ця пропозиція увійшла в основний сайт. Обговорення в PR #1555

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

Повністю розібрані приклади виробництва

Приклад 1. Коротке завдання про API-контракти стає повною главою

Вигадане коротке завдання Jira: «Пояснити, навіщо клієнту й сервісу узгоджений API-контракт і що він не гарантує».

Рішення автора. Автор спершу визначає результат навчання: після глави читач зможе розрізнити опис інтерфейсу й поведінку живого сервісу, назвати, що потребує перевірки, і оцінити наслідок несумісної зміни. Це точніше, ніж загальна ціль «вивчити API».

Питання дослідження. Що саме формально описує OpenAPI Specification? Яка зміна порушить очікування вже випущеного клієнта? За яких умов додаткова необов’язкова можливість сумісна зі старими клієнтами? Що опис схеми може підтвердити, а що треба перевірити на реальній реалізації?

Дослідження і межі джерел. Автор перевіряє точну версію OpenAPI Specification та офіційну документацію використаного інструмента. Специфікація підтримує вузьке твердження: структурований опис показує операції й очікувані частини запиту та відповіді. Вона не доводить, що production-сервіс реалізує кожне описане правило. Якщо глава порівнює контракт зі споживчими тестами, для другого механізму потрібне окреме першоджерело; формулювання не треба виводити лише зі специфікації OpenAPI.

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

Повний вигаданий приклад 1 — несумісна зміна. Сервіс бронювання має операцію POST /bookings. Попередній контракт вимагає roomId і час початку, а успішна відповідь містить ідентифікатор бронювання. Клієнт мобільного застосунку вже надсилає запит без поля guestCount. Команда хоче додати облік гостей і робить guestCount обов’язковим. Якщо серверну перевірку ввімкнути до оновлення клієнта, старий запит відхилять і користувач не зможе створити бронювання. Тому автор спершу показує зміну як несумісну: новий контракт має або зберегти старий запит, або потребує узгодженого оновлення обох сторін і плану переходу. Специфікація робить нову вимогу видимою, але сама по собі не доводить, як розгорнутий сервер відповість на старий запит; це перевіряють на реалізації та клієнтському сценарії.

Повний вигаданий приклад 2 — необов’язковий параметр із незмінним типовим результатом. Та сама система надає GET /bookings для переліку бронювань. Команда додає необов’язковий параметр status, щоб нові клієнти могли просити лише підтверджені або скасовані бронювання. У контракті й сервері параметр має значення «усі статуси», якщо його не передали. Старий мобільний клієнт і далі робить попередній запит без status і отримує той самий перелік за тією самою умовою; новий клієнт передає status=confirmed і отримує відфільтрований перелік. Зміна сумісна саме за цієї вигаданої умови, що значення за замовчуванням і формат старої відповіді збереглися. Висновок не переноситься на випадок, коли сервер змінює поведінку без параметра або вимагає його: тоді старі клієнти можуть побачити інший результат чи помилку.

Рішення рецензента. Під час першого рецензування технічний рецензент просить уточнити, що необов’язковий status сумісний лише якщо збережено старе типове значення, а схема не перевіряє фактичну поведінку сервісу. Автор додає ці межі й окремо показує ризик обов’язкового guestCount. Після звірки прикладів із OpenAPI Specification рецензент схвалює пояснення: воно розрізняє контракт, поведінку реалізації й припущення про старих клієнтів. У PR додають карту вимог короткого завдання, джерела з версіями, дату дослідження та команду збірки лише якщо її справді запускали. Якщо Quarto-проєкту ще немає, автор повідомляє про це й не видає Markdown-перегляд за повну збірку книги.

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

Приклад 2. Анотація книги й допис Reddit не обґрунтовують сильний висновок

Вигаданий сценарій. Автор уявно має коротку анотацію книги про архітектуру сервісів і умовний допис на Reddit, де один розробник позитивно описує перебудову своєї команди; це не реальні цитати чи посилання. Автор планував написати: «Книга доводить, що всі команди мають переходити на мікросервіси, бо так доставка стає швидшою».

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

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

Запис у журналі. «Перевірено: анотація описує предмет; Reddit-пост — одиничний досвід без достатніх даних для порівняння. Твердження про загальне прискорення не включено. Повний текст книги недоступний у межах дослідження; книгу не позначено як прочитану». Джерело Reddit може залишитися в нотатці як свідчення практичного контексту, якщо його автор, дата й зміст важливі; воно не мусить з’явитися серед підтримувальних джерел глави.

Чому це правильно. Кількість посилань не виправляє невідповідність між ними та твердженням. Чесна межа — це корисний результат: читач дізнається, що вдалий приклад не робить практику універсальним стандартом і що книжкову тезу не можна підтверджувати анотацією.

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

Приклад 3. Офіційний продукт змінив правила завантаження репозиторних інструкцій

Вигадана фраза у навчальній чернетці: «Claude Code не читає AGENTS.md; додайте CLAUDE.md у кожен репозиторій». Така інструкція може лишитися в опублікованій главі й після того, як офіційна документація змінилась.

Сигнал і перевірка. Рецензент помічає суперечність у чинній статті Claude Code про пам’ять проєкту. Поточна документація каже, що пряме читання AGENTS.md потребує Claude Code v2.1.277 або новішої версії. За замовчуванням Claude читає AGENTS.md, коли в робочому каталозі чи вище немає CLAUDE.md або CLAUDE.local.md; за наявності таких файлів завантажуються файли CLAUDE.md, доки налаштування Project instructions не змінено. До v2.1.281 деякі сесії, зокрема на Amazon Bedrock або з вимкненою телеметрією, читали лише CLAUDE.md; у деяких сесіях підтримка AGENTS.md може бути недоступна. Офіційні Codex docs окремо описують власні назви й порядок. Отже, важать версія, режим і конфігурація конкретного продукту, а не лише назва файла.

Обмежене оновлення. Автор змінює абзац, який стверджував, що Claude завжди ігнорує AGENTS.md: обмежує його конкретною версією/умовою; додає посилання на документацію; перевіряє приклад спільних інструкцій, що залежав від старого правила; шукає в курсі другі місця з такою самою застарілою заявою. Глава про Codex залишається окремою й містить його поточний порядок; автор не копіює в неї поведінку Claude. У журналі лишається дата, версія, умови й невідомі режими.

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

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

Приклад 4. Реальний документаційний PR показує зміну місця, а не тільки фрази

У відкритому репозиторії документації Quarto внесок PR #1555 запропонував краще пояснити, як змінювати заголовки callout-блоків — виділених приміток, порад або попереджень. Під час рецензування супровідник підтвердив, що запропонована поведінка працює, але поставив питання, чи належить їй місце в параметрах мови, які насамперед відповідають за інтернаціоналізацію. Він зауважив, що таке налаштування може вимагати окремого ключа callout: або документації для інших елементів, і порівняв його з окремими параметрами для перехресних посилань. PR містить попередній перегляд розгорнутого сайту й залишається відкритим станом на 10 жовтня 2026 року; це обговорення пропозиції, не доказ її злиття.

Короткий підсумок

Модульні .md / .qmd файли — редаговане першоджерело курсу, а HTML-книга — затверджений основний формат читання; PDF і EPUB можуть бути додатковими виходами.
Quarto налаштовано для збірки книги, а CI зберігає похідні формати для перевірки. У перевіреному процесі автоматичної збірки немає кроку публічного розгортання; зовнішнє налаштування хостингу не перевірялося.
README, курсова специфікація, предметна Jira-задача, авторські нотатки, агентні інструкції та перевірки відповідають на різні запитання. Не вигадуйте відсутню структуру й не дублюйте одні й ті самі правила без власника.
Повна глава веде читача від питання до пояснення, містить щонайменше два завершені приклади, помилки й межі; вона не містить домашнього завдання, вправ або обов’язкового встановлення інструментів.
Цінність дослідження — у відповідності доказу твердженню. Зберігайте нотатки про прочитані джерела, версію, дату, невідоме та зміну, яку треба внести в текст.
PR — етап рецензування змін; їх злиття й публікація мають бути окремими рішеннями уповноваженого власника. Попередній перегляд не є публікацією, а зібраний сайт не є рукописом.

Джерела та подальше читання

OpenAPI Initiative, OpenAPI Specification v3.2.1, опубліковано 10.09.2026. Підтримує визначення стандарту опису веб-API та версійність специфікації. Пряма версія v3.2.1. Доступ: 10.10.2026.
Quarto Project, Creating a Book. Офіційні пояснення структури проєкту книги, джерел, збірки та вихідних форматів. quarto.org/docs/books. Доступ: 10.10.2026.
Quarto Project, Book Structure. Підтверджує роль індексу, списку глав, частин, бібліографії та параметрів структури книги. quarto.org/docs/books/book-structure. Доступ: 10.10.2026.
Quarto Project, Customizing Book Output. Поточні вихідні формати, стилі й типовий каталог _book. quarto.org/docs/books/book-output. Доступ: 10.10.2026.
Quarto Project, Publishing Basics. Розмежовує форматовані результати, процес публікації, сервіси та збірку в автоматизованому процесі. quarto.org/docs/publishing. Доступ: 10.10.2026.
GitHub Docs, About Git. Пояснення версійного контролю й роботи Git із GitHub. docs.github.com/en/get-started/using-git/about-git. Доступ: 10.10.2026.
GitHub Docs, Best practices for repositories. Рекомендації щодо README, базових можливостей безпеки репозиторію та використання гілок замість внесків між репозиторіями. Для конкретних правил захисту гілок, обов’язкового рецензування та перевірок див. About protected branches та Managing a branch protection rule. Основна сторінка best practices. Доступ: 10.10.2026.
GitHub Docs, Creating a pull request. Офіційний порядок пропонування змін та пов’язування PR із issue. docs.github.com/en/pull-requests/how-tos/create-pull-requests/creating-a-pull-request. Доступ: 10.10.2026.
GitHub Docs, Review pull requests. Матеріали про огляд комітів, змінених файлів, різниці між ревізіями й відгуків. docs.github.com/en/pull-requests/how-tos/review-pull-requests. Доступ: 10.10.2026.
OpenAI, Custom instructions with AGENTS.md. Поточні офіційні правила завантаження й шарування інструкцій Codex; вебадресу документації було перенаправлено з developers.openai.com/codex/guides/agents-md на Learn. learn.chatgpt.com/docs/agent-configuration/agents-md. Доступ: 10.10.2026.
Anthropic, How Claude remembers your project. Поточне пояснення CLAUDE.md, авто-пам’яті та умов читання AGENTS.md у Claude Code; на сторінці вказано v2.1.277 як мінімум для прямого читання, а до v2.1.281 деякі сесії могли не читати цей файл. code.claude.com/docs/en/memory. Доступ: 10.10.2026.
quarto-dev, quarto-web README. Власні інструкції живого docs-репозиторію про рендеринг, заморожений стан обчислень, середовища та попередній перегляд. Закріплений README на commit 434822607608036b37673e5ed193be773c1cce74. Доступ: 10.10.2026.
quarto-dev/quarto-web, PR #1555: Documentation: Add section about changing titles for callout blocks. Первинний запис пропозиції, коментарів рецензента й попереднього перегляду. github.com/quarto-dev/quarto-web/pull/1555. Створено 23.01.2025; відкритий на час перевірки 10.10.2026. Доступ: 10.10.2026.
Тріша Гюбнер, E-Myth, Business Personalities: Entrepreneur, Manager & Technician. Авторський матеріал про бізнесові ролі та систематизацію роботи; не повний текст книги Гербера. emyth.com/inside/the-three-business-personalities-entrepreneur-manager-technician. Доступ: 10.10.2026.
Library of Congress, EPUB (Electronic Publication) File Format Family, останнє суттєве оновлення 06.05.2024. Підтримує повну назву EPUB і загальний опис контейнерного формату. Format Description Document fdd000310. Доступ: 10.10.2026.
World Wide Web Consortium (W3C — Консорціум Всесвітньої павутини; організація, що розробляє вебстандарти), Publishing Maintenance Working Group, EPUB 3.3, Recommendation, опубліковано 13.01.2026. Підтверджує технічний опис формату й контейнера для вебвмісту. Точна версія EPUB 3.3. Доступ: 10.10.2026.
A1-Marketing-NO, ai_development_course, історичний знімок fa561feca48fd8c1662beee0b13170f27581fc7c (гілка main, стан на 23.09.2026). Підтверджує ранній стан дерева файлів: README та глави 1–31 без Quarto-конфігурації. Репозиторій приватний; потрібен автентифікований доступ із правами читання. Пряме посилання на commit. Перевірено через автентифікований read path: 23.09.2026.
A1-Marketing-NO, ai_development_course, знімок fde287efd92cedcc13906e9e58e304eebcd87148 (гілка main, стан на 25.09.2026 перед додаванням глави 75). Підтверджує наявність глав 1–74, _quarto.yml, перевірки структури й workflow повної збірки без публікації сайту. Репозиторій приватний; джерела перевірено автентифікованим read path: commit, _quarto.yml, workflow. Перевірено 25.09.2026.