Tutorial 2 How the Code Works ru

Урок 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("“Буду рад(а) добавить вас в свою professional network.” — отправлено "));

Никакого мока терминала, никакого захвата 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 Ваша первая задача для агента