Курс із розробки ШІ-агентів, де відповідь студента перевіряє код, а не модель

У курсі про SQL перевірка була простою: виконай запит, звір таблицю. Тут виконувати нема чого — студент пише не запит, а артефакт: схему інструмента, SKILL.md, блок хуків, конфіг MCP або сам промпт. Тому «виконання» замінене на розбір артефакта і набір декларативних тверджень про нього, які лежать прямо в JSON уроку.

Словник тверджень навмисно вузький — одинадцять операторів: type, equals, oneOf, setEquals, contains, minLength, maxLength, minItems, regex, notRegex, absent. Кожне твердження несе власне повідомлення, тому студент бачить не «невірно», а причину — і бачить її навіть тоді, коли все зійшлося.

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

У пісочниці працює Claude — і це принципово: предмет вивчення там сам формат tool_use, stop_reason й input_schema, тож підміна провайдера означала б учити не тому. Запит іде з браузера ключем самого користувача, режим виділений в окрему вкладку з попередженням, а ключ лежить лише в localStorage і не потрапляє ні на сервер, ні в хмарну синхронізацію.

Помічник — інша роль: він пояснює урок. Його запит іде на Cloud Function, яка авторизується у Vertex службовим акаунтом, тож ключа в сторінці немає взагалі. Звідси головне обмеження, зашите в системну інструкцію на сервері: помічникові заборонено називати імена полів і параметрів API Anthropic, яких немає в тексті переданого уроку. Модель іншої компанії знає чужий API неповно, і впевнено названий неіснуючий параметр гірший за відмову відповісти.

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

Лічильники живуть у Firestore і скидаються за київським часом, а не за UTC: інакше квота оновлювалася б серед робочого дня. Колекція в них своя, окрема від сусіднього курсу в тому ж проєкті, — спільний лічильник означав би, що активний день в одному курсі з'їдає добу другого.

Прогрес зберігається в localStorage: працює без мережі й без реєстрації. Синхронізація між пристроями опційна — вмикається в налаштуваннях і кладе знімок у Firestore під випадковим двадцятисимвольним ключем, який достатньо ввести на другому пристрої. Алфавіт ключа без l, o, 0 і 1, щоб його можна було продиктувати. Ключ Anthropic у хмару не їде ніколи.

Service worker кешує різне по-різному: шрифти назавжди, код і контент — мережа першою з кешем як запасним варіантом. Окремо доводиться захищатись від власного хостингу: він налаштований як SPA і на невідомий шлях повертає сторінку з кодом 200, тож відсутній файл контенту приходить не як помилка, а як цілком успішна відповідь.

// якщо просили дані, а прийшла сторінка — не кешуємо
const wantsData = /\.json$/i.test(new URL(req.url).pathname);
const head = (await res.clone().text()).slice(0, 40).trimStart();
return head.startsWith('<!doctype') || head.startsWith('<html');

Фронтенд — дев'ять ES-модулів, близько 4 800 рядків, які браузер вантажить напряму: немає ні складальника, ні кроку збірки, ні node_modules. Усе, що зазвичай приносить фреймворк, тут написане рівно в потрібному обсязі: хеш-роутер, власний помічник для DOM, рендер markdown, підсвічувач коду шести мов (JSON, YAML, Python, TypeScript, bash і окремо XML — бо в модулі про промптинг теги не ілюстрація, а предмет), єдиний індекс пошуку по чотирьох джерелах і алгоритм інтервального повторення SM-2.

Тіло уроку набирається серифом, а інтерфейс лишається на гротеску, і межа між ними проходить по одному класу. Причина проста: урок — це 700–1300 слів суцільного тексту, і саме він займає майже весь час людини в застосунку, тоді як кнопки й чипи сканують, а не читають. Довжина рядка обмежена 74 знаками, тож праворуч лишається порожнє поле — навмисно: рядок на всю ширину екрана втомлює око раніше, ніж закінчується абзац. Таблиці й блоки коду з обмеження виведені.

Акцент навмисно приглушений. Насиченіша теракота виглядала ефектніше на скріншоті, але у застосунку, де сидять щодня, вона втомлює: акцент потрібен, щоб показати, куди натиснути, а не щоб привертати увагу. Усі поєднання перевірені на контраст — від 4.6:1 у світлій темі до 9.3:1 у темній.

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

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

node tools/validate_lessons.mjs   # контент
node tools/smoke.mjs              # екрани й консоль