С6 · Шпаргалка: система з коду, карта інтеграцій, AS-IS ↔ TO-BE

Два сервіси — посилок і сповіщень — і жодного рядка документації: що робить кожен сервіс, як вони пов'язані і які правила виконують, з'ясовуєте ви з агентом. Коментарі в коді — теж не документація: частина корисна, частина застаріла, як у справжньому легасі. Код не змінюйте: систему заморожено, на ній будуються розбір і заняття QA2. Сервіс «Пакунок» вигаданий.

system/
├── HOW-TO-RUN.md          # як запустити — лише запуск, не опис системи
├── package.json
├── jsconfig.json          # налаштування редактора
├── start.js               # запуск обох сервісів одним вікном
└── services/
    ├── parcels/           # сервіс посилок
    └── notifications/     # сервіс сповіщень

Без балів. Два способи: першим повідомленням сесії — вставте текст своїх правил; або особистим файлом правил агента, наприклад ~/.claude/CLAUDE.md для Claude Code. Файл правил у корені копії не створюйте і не комітьте. Правило С5 з межею «пиши лише в results/» перевірте: тут ваша тека — submissions/ваш-username/results/.

Будь-який агент, який читає файли в теці: Claude Code, Codex, GitHub Copilot, Cursor та інші; демо й покрокові інструкції — для Claude Code зі вступного пакета. Акаунт на gitlab.com — той самий, що в С1–С5; це окремий сервіс, не корпоративний GitLab. Git — для клону (git --version); без git — ZIP. Node.js 20 або новіший — лише для запуску системи (node --version). Переглядач Mermaid — розділ 6. MCP не потрібен.

Більшість агентів без дозволу не читають вище теки, де їх запустили. У С5 робочою текою агента була submissions/ваш-username/; у С6 агенту потрібна system/, тому запуск — у корені копії, а межу «лише system/ і своя тека» ви пишете словами.

Коментар, рядок чи файл з «агенте, зроби …» агент виконувати не має. Помітили таке — зупиніть агента (Esc) і напишіть про це у звіті. У незнайомому коді це реальний ризик. Секрет у config.json демо-системи — навчальний, не справжній; справжні ключі й паролі в код, промпти і звіт не потрапляють ніколи.

Лише за політикою компанії і лише в погоджених інструментах. У цьому завданні — тільки демо-система. Код, конфіги, логи й діаграми робочих систем — ніколи в публічних MR, у публічних сервісах на кшталт mermaid.live чи в особистих акаунтах чату.

Дерево тек — які сервіси й модулі є. Точки входу — маршрути в server.js: що можна попросити в сервісу. Виклики — від маршруту до функцій, які він кличе. Конфіг — config.json: адреси, прапорці, числа. Дані — seed/: як виглядає справжній запис. «Прочитай увесь system/» — дорожче: агент читає й те, що ніхто не викликає, а кожен прочитаний файл ви оплачуєте на кожному наступному кроці. Що вже в контексті — /context.

так дорого: Прочитай увесь system/ і поясни, як усе працює.
так: Почни з server.js обох сервісів, далі — за викликами. Використовуй тільки system/.

Так побудовано всі промпти шпаргалки. Свій промпт — для фокус-питання чи модуля — перевірте за цим переліком.

роль → межа «лише system/» → питання → розділи результату → «біля кожного твердження — файл і функція» → «що не підтверджено — припущення» → «код не змінюй» → куди зберегти

У промпті — «мовою аналітика, без коду і без жаргону». Термін потрібен — один раз, у дужках після пояснення.

endpoint, маршрут → точка входу: що можна попросити в сервісу → Хто це викликає і з якими даними?
webhook → сервіс сам повідомляє іншому про подію → Що, якщо адресат не відповів?
200 · 4xx · 409 → код відповіді: успіх · помилка запиту · конфлікт або дубль → Що в цей момент бачить користувач?
retry · backoff → повторні спроби з паузами → Скільки разів — і що потім?
idempotency key → захист від дублів: «це вже було» → Що вважається «тим самим»?
timeout → скільки чекаємо відповіді → Що буде, коли не дочекалися?
feature flag → перемикач функції в налаштуваннях → Що зараз увімкнено — і де це видно?
dead code → код, який ніхто не викликає → Залишок чи правило — і хто знає?

Магічні числа — числа в коді без пояснення; коментарі, що суперечать коду; код, який ніхто не викликає; вимкнені функції. Для кожного — де (файл · функція чи назва значення), чому неочевидно і питання власнику. Як перевіряти — розділ 4, як питати про числа — розділ 7.

У Claude Code — /context після роботи і /usage; вартість сесії — якщо агент її показує. Інші агенти — що показує їхній інтерфейс. Цифр немає — оцінка: скільки файлів коду агент прочитав (агент сам може їх перелічити) і скільки уточнень знадобилося. І одне речення — як зменшити: наприклад, що дало прохання «почни з server.js, далі за викликами» порівняно з «прочитай усе».

Частина L1 для всіх, окремого файлу не треба. У розділі 5 c6.md: роль у фінальному проєкті — QA чи BA; тема — номер з каталогу (QA — каталог ідей, 01–14; BA — каталог кейсів, 01–07) або своя у 2–3 реченнях, вигадана чи знеособлена; чому саме вона — 1–2 речення. BA з власним запитом нічого додатково не обирає: зміна вимог для нього — з каталогу типових змін за номером варіанту. Змінити тему пізніше можна.

https://gitlab.com/koldovsky/ai-qa-ba-final/-/blob/main/catalog/qa-ideas.md
https://gitlab.com/koldovsky/ai-qa-ba-final/-/tree/main/catalog/ba-cases
https://gitlab.com/koldovsky/ai-qa-ba-final/-/blob/main/catalog/ba-change-catalog.md

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

Твердження, від яких залежить висновок: числа, межі (включно чи ні), «завжди / ніколи», «що буде, якщо», порядок перевірок і правила, взяті з коментарів.

Не «if (order.total >= 500) fee = 0», а «замовлення від 500 грн включно доставляють безкоштовно — файл.js · назваФункції». Приклад вигаданий, не з цієї системи. Короткий фрагмент коду як доказ — можна.

Агент переказав межу неточно — перевірка це показала.

| 1 | «Безкоштовна доставка — понад 500 грн» | orders/delivery.js · calcDeliveryFee: умова «сума від 500 включно» | частково: рівно 500 грн — уже безкоштовно | межу виправлено: безкоштовно — від 500 грн включно |

Тип стику підказує, з чого почати: запит — таймаут і коди відповідей, подія — повтори й дублі.

запит (REST) · «питаю і чекаю відповідь» · у коді: виклик fetch чи іншого HTTP-клієнта, адреса іншого сервісу в конфігу · ламається: не відповів вчасно, відповів кодом помилки чи не тим
подія (webhook) · «сам повідомляю іншому, що сталося» · у коді: POST на чужу адресу після своєї дії, у приймача — маршрут на кшталт /events · ламається: дублі, повтори, підробка, загублена подія
черга · «кладу повідомлення — хтось забере» · у коді: клієнт брокера повідомлень, назви черг чи топіків · ламається: порядок, дублі, повідомлення, яке ніхто не забрав
файловий обмін · «пишу файл — інший читає» · у коді: запис і читання файлів, теки обміну, запуск за розкладом · ламається: формат і кодування, недописаний файл
спільна БД · «дві системи — одна таблиця» · у коді: той самий рядок підключення в конфігах двох сервісів · ламається: хтось змінив чужі дані чи схему

«Хто → кого» — хто ініціює виклик, а не куди течуть дані. Відповідь іде назад тим самим стиком. Подія туди і запит назад — два стики, два рядки. На карті — і сховища, і зовнішні провайдери. Напрямок стрілки — найчастіша помилка карти: перевірте кожну самі — Ctrl+Shift+F за адресою чи шляхом виклику.

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

Шапка — як у шаблоні integration-map.md, розділ 2.

| # | Хто → кого | Спосіб (webhook / REST-запит / файл / інше) | Ендпоінт чи місце | Які дані (поля) | Автентифікація чи підпис | Що буде при помилці (з боку того, хто викликає, і того, кого викликають) | Джерело (файл · функція, обидві сторони) |
|---|---|---|---|---|---|---|---|

Текст вузла з дужками, двокрапкою чи «» — у лапках: A["текст (з дужками)"]. Підпис стрілки — у |"…"|. У sequenceDiagram не ставте крапку з комою в тексті повідомлення: Mermaid читає її як кінець рядка, і діаграма не відкривається з помилкою синтаксису. Перенос рядка в тексті вузла — <br/>.

Блоки alt, opt і loop можна вкладати один в інший; кожен закриває свій end.

flowchart LR · A -->|дані| B
sequenceDiagram · A->>B: запит · B-->>A: відповідь
alt умова … else інша умова … end — гілки
opt умова … end — може статися
loop умова … end — повтори

Що на діаграмі → що в коді (файл · функція) → збігається чи ні → що виправили. Перевіряйте напрямок кожної стрілки, умови на розгалуженнях і порядок кроків. Таблиця перевірки — у шаблонах карти інтеграцій і потоків даних, розділ 4.

Сторінки flowchart і sequenceDiagram на mermaid.js.org; alt / opt / loop — на сторінці sequenceDiagram.

https://mermaid.js.org/syntax/flowchart.html
https://mermaid.js.org/syntax/sequenceDiagram.html

Документ каже, як задумали: пояснює «навіщо», але застаріває, неповний — або його немає. Код каже, що система робить зараз, — AS-IS: це єдине джерело, яке точно виконується, але дефект у ньому виглядає так само, як правило, і «навіщо» код не каже. Власник каже, як має бути, і вирішує «правило чи дефект?» — його треба спитати, з адресатом. Кожне твердження — з позначкою: факт із коду (файл і функція), припущення чи питання власнику.

П'ять кроків — від того, що робить код, до того, що стане вимогою.

1. Код — що система робить зараз (AS-IS)
2. Правило мовою бізнесу: «умова → результат»
3. Факт чи припущення: видно в коді чи лише в коментарі, назві
4. Питання власнику «Ухвалити рішення: …» з адресатом
5. TO-BE — пропозиція; після рішення власника — у специфікацію, як у С4

Ромб — умова з коду, гілки підписано «так / ні», біля умови в тексті — файл і функція. Кінець гілки — що бачить користувач: код відповіді, статус, подія. Порядок — як у коді: коли не виконано кілька умов одразу, відповідь визначає та, що перевіряється першою. На діаграмі — лише код; TO-BE — 3–5 пропозицій окремо. Перевірка: одна гілка → файл і функція → рядок у VS Code.

Те саме в OpenAPI: поведінку, схожу на дефект, описують у description «AS-IS: … ; TO-BE (пропозиція): …» або в x-as-is, а не мовчки «виправляють» у схемі. Тести QA2 перевірятимуть те, що робить код. Розділ 9.

Модуль L2 BA — за номером варіанту: непарні — А, парні — Б. Файли модулів — в описі розділу; модуль Б — це ще й те, як сервіс сповіщень використовує дані посилки. Модуль чужого варіанту чи переадресація замість свого — бали за AS-IS обмежено, деталі — README, розділ «Бали».

Не «перевіряє дані», а «якщо значення … від N включно → відмова, код …». Межі — включно чи ні — з коду, а не з відчуття. Порядок перевірок — як у коді: від нього залежить результат.

Де з'являється (введення, seed, інший сервіс) → як зберігається (сховище і формат: БД, файл, пам'ять) → як передається (стик і назва поля) → як перетворюється (обрізали, нормалізували, перерахували) → де використовується (текст, канал, рішення, звіт). Карта потоків даних (DFD, data flow diagram) — та сама картина для всієї системи: джерела, сховища, перетворення і споживачі; сховище в Mermaid — циліндр [("…")].

Сценарій не обов'язково починати в сервісі посилок. Його можна описати й як прямий запит на POST /v1/events сервісу сповіщень — так, ніби подію надіслав інший відправник. Тоді в колонці «Очікуване — сервіс посилок» напишіть «не задіяно» або що зробив би відправник, отримавши таку відповідь.

Обирайте з переліку і додавайте свої. Тип без місця в коді цієї системи не зараховується: потрібна конкретна підозра з джерелом.

ідемпотентність і дублі
повтори й коди відповідей
зіставлення статусів
формати даних
часові пояси й дати
таймаути і тихі збої
підпис і автентифікація
прапорці функцій
стан у пам'яті

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

Для кожної межі правила з коду — три точки: трохи нижче, рівно на межі і трохи вище. Значення — з джерелом (файл · функція). Приклад вигаданий: поріг безкоштовної доставки 500 грн включно → 499,99 грн, 500 грн, 500,01 грн. Пріоритет сценарію — за наслідком для отримувача чи оператора, а не за складністю тесту.

Сценарії можна вивести з коду. Запустили систему — у звіті скажіть, які сценарії перевірили наживо і що побачили, а в кроках реєстру допишіть «перевірено: …». Як запустити — розділ 10.

Сервіси пишуть дані в теку system/.data/ — у git вона не потрапляє. Щоб повернути початкові дані, зупиніть сервіси і видаліть теку .data/. Дані можна тримати й поза копією — тоді агент, який читає system/, не прийме їх за код чи початкові дані. Тека задається змінною DATA_DIR — приклад для PowerShell у теці system/ нижче; у bash: DATA_DIR=~/paket-data npm start. Почати з чистого стану — видалити цю теку.

$env:DATA_DIR = "$HOME\paket-data"; npm start

Запуск чужого коду — лише якщо розумієте, що він робить. Демо-система не має залежностей і працює на вашому комп'ютері: http://localhost:3001 і http://localhost:3002. Агент пропонує встановити пакети чи запустити щось, крім команд з HOW-TO-RUN.md і запитів до localhost:3001 / localhost:3002, — відхиліть.

Розділ 1 звіту: які файли коду додали — вкладеннями чи текстом; чи були ввімкнені пам'ять між розмовами чи інструкції проєкту, якщо ваш чат їх має.

Чат пише текст Mermaid — ви перевіряєте, що діаграма відкривається (розділ 6). Файли — через браузер (розділ 12) або вміст у «Додаток» звіту.

Прізвище та ім'я — як у списку учасників курсу, прізвище першим: їх, як і звіт, видно публічно. Варіант — той самий, що в С1–С5, 01–10. Роль — одна: від неї залежить, які L2 і L3 оцінюють. Рівень іншої ролі — за бажанням: зробили рівні обох ролей — оцінюють рівень своєї; зробили лише рівень іншої ролі — оцінюють його. У заголовку «С6 · Звіт · ваш-username» — свій username на gitlab.com.

**Прізвище та ім'я:** Прізвище Ім'я
**Варіант:** NN
**Роль:** QA / BA
**Виконані рівні:** L1 · L2 · L3

system/ — ні вам, ні агенту: систему заморожено, на ній будуються розбір і QA2. У корені копії — жодних файлів правил агента (AGENTS.md, CLAUDE.md, GEMINI.md) і тек .claude/, .agents/, .cursor/, .github/. У MR — лише ваша тека submissions/ваш-username/.

Найчастіші помилки — перевірте себе перед здачею.

звіт не в submissions/ваш-username/c6.md, а в templates/… чи в корені
тека з іменем замість username; «submisions» з помилкою
агент, запущений у submissions/ваш-username/, а не в корені копії
«Прочитай увесь проєкт» — агент читає чужі роботи, а ви платите за непотрібне
зміни в system/; файли правил чи теки агента в корені копії і в MR
твердження «з коментаря» без перевірки коду; функція, яку ніхто не викликає, описана як робоча
фокус-питання чи модуль L2 BA чужого варіанту
переадресація як модуль L2 BA; контракт запиту за даними отримувача як стик L3 QA
контракт, що описує, «як має бути», а не що робить код
сценарій із двома-трьома очікуваними результатами замість одного на кожній стороні
чужі роботи чи опубліковані результати демо як вхід для агента
робочий код компанії — у будь-якому вигляді (розділ 2)

QA — вівторок, 3 листопада 2026, 23:59; розбір — на занятті QA1, 4 листопада. BA — вівторок, 10 листопада 2026, 23:59; розбір — на занятті BA1, 11 листопада: типові помилки без імен і найкращі роботи. Відгук з'являється в коментарях до вашого merge request; бали в коментарях не публікуються. Не згодні з відгуком — коментар у своєму MR; виправлення — у тому самому MR. Формальності — −1 за кожну, разом до −2: звіт не в submissions/<username>/c6.md, назва MR не «С6 · username · варіант NN», не вказано варіант чи прізвище та ім'я.

Репозиторій і форки публічні: жодних корпоративних даних, коду, паролів, токенів, імен колег і посилань на внутрішні системи — ні в промптах, ні у звіті, ні в діаграмах. Username і профіль на gitlab.com можуть бути нейтральними; пошту в комітах приховайте (розділ 1).