Tutorial 2 How the Code Works it

Tutorial 2 · Come funziona il codice

Obiettivo: capire la manciata di scelte di design che rendono questo progetto facile — e sicuro — da cambiare con un agente di IA. Non devi memorizzare il codice; ti serve il modello mentale, per poter dirigere l'agente con precisione.

← Precedente: Tutorial 1 Orientamento · Avanti: Tutorial 3 Il tuo primo task con l'agente

---

La mappa

lockedin-cli/
├── bin/lockedin.js      # punto d'ingresso — l'UNICA parte che fa input/output
├── src/lockedin.js      # il core — funzioni pure che restituiscono stringhe
├── test/
│   ├── unit.test.js     # testa direttamente le funzioni del core
│   └── cli.test.js      # lancia il binario reale e controlla il suo output
├── tools/screenshot.js  # genera gli SVG che vedi in docs/
└── package.json         # metadati + lo script `npm test`

Quattro idee lo fanno funzionare. Imparale e potrai chiedere all'agente quasi qualsiasi cambiamento con fiducia.

Idea 1 — Un core puro che restituisce stringhe

Apri src/lockedin.js. Nota che le funzioni di render non stampano — restituiscono stringhe:

function renderConnect() {
  const names = shuffle(NAMES).slice(0, 6);
  // ...costruisce un array di righe...
  return out.join('\n');   // restituisce testo; non stampa nulla
}

Tutta la stampa vera (e la lettura dei tuoi tasti) avviene in bin/lockedin.js. Questa separazione «il core restituisce dati, il bordo fa I/O» è la cosa più importante qui, perché una funzione che si limita a restituire una stringa è banale da testare:

const out = app.renderConnect();
assert.ok(out.includes("“Mi piacerebbe aggiungerti alla mia rete professionale.” — inviato a "));

Niente mock di un terminale, niente cattura di stdout. Quando chiedi all'agente di aggiungere una funzionalità, è per questo che può anche aggiungerle un test rapido e affidabile.

Idea 2 — Pool di contenuti

Le battute vivono in semplici array vicino all'inizio di src/lockedin.js:

const HOOKS = [ 'Opinione impopolare:', 'Lascia che sedimenti.', /* ...~25 in totale... */ ];
const LESSONS = [ '→ Il tuo network è il tuo net worth.', /* ... */ ];

I generatori scelgono da questi pool. In v1.2.0 ogni pool è cresciuto a ~25 varianti, ed è stato aggiunto un secondo livello di pool di template (cose come POST_REVEALS e REFLECT_TAGSETS) così che vari la struttura di ogni output, non solo le parole. Aggiungere contenuti è spesso semplice come aggiungere stringhe a un array — un primo task perfetto da affidare a un agente.

Idea 3 — Casualità con seed = test deterministici

Output casuale e test automatizzati sembrano incompatibili. Questo progetto quadra il cerchio con un generatore di numeri casuali con seed:

setSeed(42);
const a = generatePost();
setSeed(42);
const b = generatePost();
// a === b  → stesso seed, stesso post

Ogni scelta casuale passa per gli helper condivisi pick() / shuffle(), che attingono da quel generatore con seed. Imposta LOCKEDIN_SEED=42 e la CLI è del tutto riproducibile. La regola d'oro per qualsiasi cambiamento: la nuova casualità deve usare pick / shuffle, mai Math.random direttamente — altrimenti il determinismo (e i test) si rompono. Tienilo a portata di mano; lo ricorderai all'agente nel Capitolo 3.

Idea 4 — Due livelli di test

• test/unit.test.js chiama le funzioni del core e verifica le stringhe che restituiscono (veloce, preciso).
• test/cli.test.js lancia davvero bin/lockedin.js e controlla il suo stdout reale e il codice di uscita (dimostra che il tutto funziona dall'inizio alla fine).

Insieme sono la barriera. Codificano anche gli invarianti — promesse che l'app fa. Per esempio, un post apre sempre con un gancio noto e contiene sempre almeno tre lezioni →; la schermata di "connect" dice sempre incalculable. Quando un agente cambia il codice, questi test intercettano qualsiasi promessa infranta in silenzio.

---

Perché questo conta quando lavori con un agente

Metti insieme le quattro idee e ottieni un codice dove un agente può:

1. Aggiungere una funzionalità come funzione pura che restituisce una stringa,
2. Aggiungere un test per essa senza acrobazie di I/O,
3. Mantenere l'output riproducibile tramite l'RNG con seed, e
4. Dimostrare di non aver rotto nulla eseguendo la barriera esistente.

Questo è il ciclo che eseguirai nel prossimo capitolo.

✅ Provaci con il tuo agente

Chiedi al tuo agente di verificare la tua comprensione — leggendo, non modificando:

1. "Elenca ogni pool di contenuti in src/lockedin.js e quante voci ha ciascuno."
2. "Mostrami un invariante che test/unit.test.js impone su generatePost, e spiega cosa lo romperebbe."
3. "Dove è definito l'RNG con seed, e quali funzioni devono usarlo al posto di Math.random? Non cambiare niente — spiega soltanto."

Quando le risposte dell'agente coincidono con questo capitolo, sei pronto/a a costruire.

Avanti: Tutorial 3 Il tuo primo task con l'agente