Tutorial 2 How the Code Works pl

Samouczek 2 · Jak działa kod

Cel: zrozumieć garść decyzji projektowych, które czynią ten projekt łatwym — i bezpiecznym — do zmiany z agentem AI. Nie musisz zapamiętywać kodu; potrzebujesz modelu mentalnego, abyś mógł precyzyjnie kierować agentem.

← Poprzednio: Samouczek 1 Orientacja · Dalej: Samouczek 3 Twoje pierwsze zadanie dla agenta

---

Mapa

lockedin-cli/
├── bin/lockedin.js      # punkt wejścia — JEDYNA część wykonująca wejście/wyjście
├── src/lockedin.js      # rdzeń — czyste funkcje zwracające ciągi znaków
├── test/
│   ├── unit.test.js     # testuje funkcje rdzenia bezpośrednio
│   └── cli.test.js      # uruchamia prawdziwy plik wykonywalny i sprawdza jego wyjście
├── tools/screenshot.js  # renderuje pliki SVG widoczne w docs/
└── package.json         # metadane + skrypt `npm test`

Cztery pomysły sprawiają, że to działa. Naucz się ich, a będziesz mógł prosić agenta o niemal każdą zmianę z pewnością.

Pomysł 1 — Czysty rdzeń, który zwraca stringi

Otwórz src/lockedin.js. Zauważ, że funkcje renderujące nie drukują — one zwracają stringi:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...buduje tablicę wierszy...
  return out.join('\n');   // zwraca tekst; niczego nie drukuje
}

Całe faktyczne drukowanie (i odczyt Twoich naciśnięć klawiszy) dzieje się w bin/lockedin.js. Ten podział „rdzeń zwraca dane, brzeg robi I/O” to najważniejsza rzecz tutaj, bo funkcja, która po prostu zwraca string, jest trywialna do przetestowania:

const out = app.renderConnect();
assert.ok(out.includes("„Chętnie dodam cię do mojej profesjonalnej sieci.” — wysłane do "));

Bez mockowania terminala, bez przechwytywania stdout. Gdy prosisz agenta o dodanie funkcji, właśnie dlatego może też dodać do niej szybki, niezawodny test.

Pomysł 2 — Pule treści

Żarty żyją w zwykłych tablicach na górze src/lockedin.js:

const HOOKS = [ 'Niepopularna opinia:', 'Niech to wybrzmi.', /* ...~25 total... */ ];
const LESSONS = [ '→ Twoja sieć kontaktów to twoja wartość netto.', /* ... */ ];

Generatory wybierają z tych pul. W v1.2.0 każda pula urosła do ~25 wariacji, a dodano drugą warstwę pul szablonów (rzeczy takie jak POST_REVEALS i REFLECT_TAGSETS), aby struktura każdego wyjścia się zmieniała, nie tylko słowa. Dodawanie treści to często coś tak prostego jak dodanie stringów do tablicy — idealne pierwsze zadanie do przekazania agentowi.

Pomysł 3 — Losowość z ziarnem = deterministyczne testy

Losowe wyjście i automatyczne testy brzmią niekompatybilnie. Ten projekt godzi to za pomocą generatora liczb losowych z możliwością zasiania ziarna:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → to samo ziarno, ten sam post

Każdy losowy wybór przechodzi przez współdzielone funkcje pomocnicze pick() / shuffle(), które czerpią z tego generatora z ziarnem. Ustaw LOCKEDIN_SEED=42, a CLI jest w pełni odtwarzalne. Złota zasada dla każdej zmiany: nowa losowość musi używać pick / shuffle, nigdy Math.random bezpośrednio — w przeciwnym razie determinizm (i testy) się łamią. Trzymaj to w tylnej kieszeni; przypomnisz o tym agentowi w rozdziale 3.

Pomysł 4 — Dwie warstwy testów

• test/unit.test.js wywołuje funkcje rdzenia i sprawdza stringi, które zwracają (szybko, precyzyjnie).
• test/cli.test.js faktycznie uruchamia bin/lockedin.js i sprawdza jego prawdziwe stdout i kod wyjścia (dowodzi, że całość działa od początku do końca).

Razem stanowią bramkę. Kodują też niezmienniki — obietnice, które składa aplikacja. Na przykład post zawsze otwiera się znanym hookiem i zawsze zawiera co najmniej trzy lekcje →; ekran „connect” zawsze mówi incalculable. Gdy agent zmienia kod, te testy wychwytują wszystko, co po cichu złamało obietnicę.

---

Dlaczego to ma znaczenie w pracy z agentem

Połącz cztery pomysły razem, a otrzymasz bazę kodu, w której agent może:

1. Dodać funkcję jako czystą funkcję zwracającą string,
2. Dodać do niej test bez żadnej gimnastyki I/O,
3. Zachować wyjście odtwarzalne dzięki RNG z ziarnem, oraz
4. Udowodnić, że niczego nie zepsuł, uruchamiając istniejącą bramkę.

To jest pętla, którą uruchomisz w następnym rozdziale.

✅ Wypróbuj ze swoim agentem

Poproś swojego agenta, aby zweryfikował Twoje zrozumienie — czytając, nie edytując:

1. „Wypisz każdą pulę treści w src/lockedin.js i ile wpisów ma każda.”
2. „Pokaż mi jeden niezmiennik, który test/unit.test.js egzekwuje wobec generatePost, i wyjaśnij, co by go złamało.”
3. „Gdzie zdefiniowany jest RNG z ziarnem i które funkcje muszą go używać zamiast Math.random? Nic nie zmieniaj — po prostu wyjaśnij.”

Gdy odpowiedzi agenta pasują do tego rozdziału, jesteś gotów budować.

Dalej: Samouczek 3 Twoje pierwsze zadanie dla agenta