Tutorial 2 How the Code Works uk

Урок 2 · Як працює код

Мета: зрозуміти жменьку проєктних рішень, що роблять цей проєкт простим — і безпечним — для зміни з ШІ-агентом. Запам'ятовувати код не потрібно; потрібна ментальна модель, щоб точно скеровувати агента.

← Назад: Урок 1 Орієнтація · Далі: Урок 3 Ваше перше завдання для агента

---

Карта

lockedin-cli/
├── bin/lockedin.js      # точка входу — ЄДИНА частина, що робить ввід/вивід
├── src/lockedin.js      # ядро — чисті функції, що повертають рядки
├── test/
│   ├── unit.test.js     # тестує функції ядра напряму
│   └── cli.test.js      # запускає справжній бінарник і перевіряє його вивід
├── tools/screenshot.js  # рендерить SVG, які ви бачите в docs/
└── package.json         # метадані + скрипт `npm test`

Чотири ідеї змушують це працювати. Вивчіть їх, і ви зможете попросити агента про майже будь-яку зміну з упевненістю.

Ідея 1 — Чисте ядро, що повертає рядки

Відкрийте src/lockedin.js. Зверніть увагу, що функції рендерингу не друкують — вони повертають рядки:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...збирає масив рядків...
  return out.join('\n');   // повертає текст; нічого не друкує
}

Увесь справжній друк (і читання ваших натискань) відбувається в bin/lockedin.js. Цей поділ «ядро повертає дані, край робить I/O» — це найважливіша річ тут, бо функцію, що просто повертає рядок, тривіально тестувати:

const out = app.renderConnect();
assert.ok(out.includes("“Буду радий додати тебе до моєї професійної мережі.” — надіслано "));

Жодного моку терміналу, жодного захоплення stdout. Коли ви просите агента додати функцію, саме тому він може додати й швидкий, надійний тест для неї.

Ідея 2 — Пули контенту

Жарти живуть у простих масивах ближче до початку src/lockedin.js:

const HOOKS = [ 'Непопулярна думка:', 'Дайте цьому осісти.', /* ...~25 усього... */ ];
const LESSONS = [ '→ Твій нетворк — це твій net worth, тільки без ліквідності.', /* ... */ ];

Генератори обирають із цих пулів. У v1.2.0 кожен пул виріс до ~25 варіацій, і був доданий другий шар пулів шаблонів (такі як POST_REVEALS і REFLECT_TAGSETS), щоб структура кожного виводу варіювалася, а не лише слова. Додавання контенту часто таке ж просте, як додавання рядків у масив — ідеальне перше завдання для передачі агентові.

Ідея 3 — Випадковість із seed = детерміновані тести

Випадковий вивід і автоматичні тести звучать несумісно. Цей проєкт розв'язує цю дилему за допомогою генератора випадкових чисел із seed:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → той самий seed, той самий допис

Кожен випадковий вибір проходить через спільні помічники pick() / shuffle(), що черпають із цього генератора з seed. Задайте LOCKEDIN_SEED=42, і CLI повністю відтворюваний. Золоте правило для будь-якої зміни: нова випадковість має використовувати pick / shuffle, ніколи Math.random напряму — інакше детермінізм (і тести) ламаються. Тримайте це напоготові; ви нагадаєте про це агентові в Розділі 3.

Ідея 4 — Два шари тестів

• test/unit.test.js викликає функції ядра й стверджує про рядки, які вони повертають (швидко, точно).
• test/cli.test.js реально запускає bin/lockedin.js і перевіряє його справжній stdout і код виходу (доводить, що все працює від початку до кінця).

Разом вони — бар'єр. Вони також кодують інваріанти — обіцянки, які дає застосунок. Наприклад, допис завжди відкривається відомим hook-ом і завжди містить щонайменше три → уроки; екран «connect» завжди каже incalculable. Коли агент міняє код, ці тести ловлять усе, що тихо порушило обіцянку.

---

Чому це важливо для роботи з агентом

Складіть чотири ідеї разом, і ви отримаєте код, у якому агент може:

1. Додати функцію як чисту функцію, що повертає рядок,
2. Додати тест для неї без жодної гімнастики з I/O,
3. Зберегти вивід відтворюваним через генератор із seed, і
4. Довести, що нічого не зламав, запустивши наявний бар'єр.

Це цикл, який ви проженете в наступному розділі.

✅ Спробуйте зі своїм агентом

Попросіть агента перевірити ваше розуміння — читаючи, не редагуючи:

1. «Перелічи кожен пул контенту в src/lockedin.js і скільки записів у кожному.»
2. «Покажи мені один інваріант, який test/unit.test.js забезпечує для generatePost, і поясни, що б його зламало.»
3. «Де визначено генератор із seed, і які функції мають використовувати його замість Math.random? Нічого не змінюй — просто поясни.»

Коли відповіді агента збіжаться з цим розділом, ви готові будувати.

Далі: Урок 3 Ваше перше завдання для агента