Tutorial 2 How the Code Works fi

Tutorial 2 · Miten koodi toimii

Tavoite: ymmärtää se kourallinen suunnitteluvalintoja, jotka tekevät tästä projektista helpon — ja turvallisen — muuttaa tekoälyagentin kanssa. Sinun ei tarvitse ulkoa opetella koodia; tarvitset mentaalimallin, jotta voit ohjata agenttia täsmällisesti.

← Edellinen: Tutorial 1 Orientaatio · Seuraava: Tutorial 3 Ensimmäinen agenttitehtäväsi

---

Kartta

lockedin-cli/
├── bin/lockedin.js      # sisääntulopiste — AINOA osa, joka tekee syöttöä/tulostetta
├── src/lockedin.js      # ydin — puhtaita funktioita, jotka palauttavat merkkijonoja
├── test/
│   ├── unit.test.js     # testaa ydinfunktioita suoraan
│   └── cli.test.js      # käynnistää oikean binäärin ja tarkistaa sen tulosteen
├── tools/screenshot.js  # renderöi SVG:t, jotka näet docs/-kansiossa
└── package.json         # metadata + `npm test`-skripti

Neljä ideaa saavat sen tikittämään. Opi nämä, niin voit pyytää agentilta lähes mitä tahansa muutosta luottavaisin mielin.

Idea 1 — Puhdas ydin, joka palauttaa merkkijonoja

Avaa src/lockedin.js. Huomaa, että renderöintifunktiot eivät tulosta — ne palauttavat merkkijonoja:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...rakentaa rivitaulukon...
  return out.join('\n');   // palauttaa tekstiä; ei tulosta mitään
}

Kaikki varsinainen tulostus (ja näppäinpainallustesi lukeminen) tapahtuu bin/lockedin.js:ssä. Tämä "ydin palauttaa dataa, reuna tekee I/O:n" -jako on tärkein yksittäinen asia täällä, koska funktiota, joka vain palauttaa merkkijonon, on triviaalia testata:

const out = app.renderConnect();
assert.ok(out.includes("\"Haluaisin lisätä sinut ammatilliseen verkostooni.\" — lähetetty "));

Ei terminaalin mockkaamista, ei stdoutin kaappaamista. Kun pyydät agenttia lisäämään ominaisuuden, tästä syystä se voi myös lisätä nopean, luotettavan testin sille.

Idea 2 — Sisältöpoolit

Läpät asuvat tavallisissa taulukoissa lähellä src/lockedin.js:n alkua:

const HOOKS = [ 'Epäsuosittu mielipide:', 'Anna sen upota.', /* ...~25 yhteensä... */ ];
const LESSONS = [ '→ Verkostosi on nettovarallisuutesi.', /* ... */ ];

Generaattorit valitsevat näistä pooleista. Versiossa v1.2.0 jokainen pooli kasvoi ~25 vaihteluun, ja toinen kerros mallipooleja lisättiin (kuten POST_REVEALS ja REFLECT_TAGSETS), jotta kunkin tulosteen rakenne vaihtelee, ei vain sanat. Sisällön lisääminen on usein yhtä yksinkertaista kuin merkkijonojen lisääminen taulukkoon — täydellinen ensimmäinen tehtävä agentille.

Idea 3 — Siemennetty satunnaisuus = deterministiset testit

Satunnainen tuloste ja automatisoidut testit kuulostavat ristiriitaisilta. Tämä projekti ratkaisee sen siemennettävällä satunnaislukugeneraattorilla:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → sama siemen, sama julkaisu

Jokainen satunnainen valinta kulkee jaettujen pick() / shuffle() -apufunktioiden kautta, jotka ammentavat tuosta siemennetystä generaattorista. Aseta LOCKEDIN_SEED=42, ja CLI on täysin toistettavissa. Kultainen sääntö mille tahansa muutokselle: uuden satunnaisuuden täytyy käyttää pick/shuffle, ei koskaan suoraan Math.random — muuten determinismi (ja testit) hajoavat. Pidä tämä takataskussasi; muistutat siitä agenttia luvussa 3.

Idea 4 — Kaksi testikerrosta

• test/unit.test.js kutsuu ydinfunktioita ja tekee väitteitä merkkijonoista, jotka ne palauttavat (nopea, tarkka).
• test/cli.test.js todella käynnistää bin/lockedin.js:n ja tarkistaa sen oikean stdoutin ja poistumiskoodin (todistaa, että koko homma toimii päästä päähän).

Yhdessä ne ovat portti. Ne myös koodaavat invariantteja — sovelluksen antamia lupauksia. Esimerkiksi julkaisu alkaa aina tunnetulla koukulla ja sisältää aina vähintään kolme →-oppia; "connect"-näyttö sanoo aina incalculable. Kun agentti muuttaa koodia, nämä testit nappaavat kaiken, mikä hiljaa rikkoi lupauksen.

---

Miksi tämä on tärkeää agentin kanssa työskentelylle

Yhdistä nämä neljä ideaa, niin saat koodikannan, jossa agentti voi:

1. Lisätä ominaisuuden puhtaana funktiona, joka palauttaa merkkijonon,
2. Lisätä sille testin ilman I/O-akrobatiaa,
3. Pitää tulosteen toistettavana siemennetyn RNG:n kautta, ja
4. Todistaa, ettei se rikkonut mitään ajamalla olemassa olevan portin.

Se on silmukka, jonka ajat seuraavassa luvussa.

✅ Kokeile agenttisi kanssa

Pyydä agenttiasi vahvistamaan ymmärryksesi — lukemalla, ei muokkaamalla:

1. "Listaa jokainen sisältöpooli src/lockedin.js:ssä ja kuinka monta merkintää kussakin on."
2. "Näytä minulle yksi invariantti, jonka test/unit.test.js pakottaa generatePost:ille, ja selitä mikä sen rikkoisi."
3. "Missä siemennetty RNG on määritelty, ja mitkä funktiot sitä täytyy käyttää Math.random:n sijaan? Älä muuta mitään — vain selitä."

Kun agentin vastaukset täsmäävät tähän lukuun, olet valmis rakentamaan.

Seuraava: Tutorial 3 Ensimmäinen agenttitehtäväsi