Tutorial 3 Your First Agent Task it

Tutorial 3 · Il tuo primo task con l'agente

Obiettivo: aggiungere un comando nuovo di zecca alla CLI — dall'inizio alla fine — dirigendo il tuo agente. Aggiungeremo lockedin endorse: valida perfetti sconosciuti per skill che quasi sicuramente non hanno. In pieno stile.

Questo è il cuore del tutorial. Eserciterai il ciclo reale: specifica → test → implementazione → barriera verde → revisione.

← Precedente: Tutorial 2 Come funziona il codice · Avanti: Tutorial 4 Prompt e revisione

---

Passo 0 — Decidi come appare il "fatto"

Prima di scrivere qualsiasi prompt, scrivi tu stesso/a la specifica in linguaggio semplice. Le richieste vaghe producono codice vago — da un umano o da un agente.

endorse stampa 5–7 righe, ognuna che valida una persona scelta a caso (riusa il pool NAMES esistente) per una skill di buzzword scelta a caso (un nuovo pool). Termina con una battuta satirica di una riga. Deve essere raggiungibile come lockedin endorse, come /endorse dentro la sessione, e comparire in help. Tutta la casualità deve usare gli helper con seed pick/shuffle così che l'output resti deterministico. npm test deve restare verde, e ci deve essere un nuovo test che fissa almeno un invariante.

Quel paragrafo è ciò che consegnerai all'agente. Nota che nomina i vincoli del Capitolo 2 (RNG con seed, la barriera dei test, l'abitudine agli invarianti).

Passo 1 — Chiedi all'agente di pianificare, non di programmare

Comincia chiedendo un piano. È la tua occasione per intercettare un approccio sbagliato prima che cambi qualsiasi file.

"Voglio aggiungere un comando endorse a LockedIn CLI. Ecco la specifica: [paste your spec]. Prima di scrivere codice, dimmi quali file cambierai e il tuo approccio, così posso approvarlo. Segui i pattern esistenti per un comando come connect."

Un buon piano menziona: un nuovo pool SKILLS + un renderEndorse() in src/lockedin.js, il collegamento in dispatch() e handleSlash(), l'aggiunta di una riga in renderHelp(), l'esportazione della nuova funzione/pool e l'aggiunta di test in entrambi i file di test. Se il piano dimentica la regola dell'RNG con seed o i test, dillo subito.

Passo 2 — Prima i test

Chiedi all'agente di scrivere i test prima dell'implementazione. I test prima di tutto trasformano la tua specifica in qualcosa di eseguibile, e mantengono l'agente onesto.

"Ottimo. Prima, aggiungi solo test che falliscono: un test unitario che renderEndorse() restituisce testo che menziona una skill nota e almeno 5 endorsement, e un test in cli.test.js che lockedin endorse esce con 0 e stampa un endorsement. Usa un seed fisso. Non implementare ancora renderEndorse — vediamo prima fallire i test."

Eseguili e guardali fallire per la ragione giusta (la funzione non esiste ancora):

npm test

Passo 3 — Lascia che l'agente implementi

Ora dai il via libera all'implementazione:

"Ora implementalo per far passare quei test, seguendo il pattern di connect. Aggiungi un pool SKILLS di ~25 skill di buzzword, un renderEndorse() che restituisce una stringa, collega dispatch e handleSlash, aggiungi una riga in help ed esporta ciò che hai aggiunto. Usa solo pick/shuffle per la casualità."

Ciò che l'agente produce dovrebbe assomigliare molto al resto del file. Per esempio, un pool SKILLS e un renderizzatore:

const SKILLS = [
  'Thought Leadership', 'Sinergia', 'Vibes', 'Blockchain (in teoria)',
  'Essere Umiliati', 'Tornare sul Punto', 'Aura Farming', /* ...~25 in totale... */
];

function renderEndorse() {
  const people = shuffle(NAMES).slice(0, 5 + Math.floor(rand() * 3)); // 5–7
  const skills = shuffle(SKILLS);
  const out = [''];
  people.forEach((n, i) =>
    out.push('  ✔ Hai validato ' + n + ' per ' + skills[i % skills.length]));
  out.push('', '  Hai validato 6 sconosciuti per skill che non puoi verificare. Ti valideranno a loro volta entro un\'ora.');
  return out.join('\n');
}

…più una riga ciascuno in dispatch() e handleSlash(), una riga in renderHelp(), e SKILLS, renderEndorse aggiunti a module.exports.

Passo 4 — La barriera

npm test

Verde? Hai appena pubblicato una funzionalità con un agente, con i test prima di tutto. Non verde? È normale — vai al ciclo di iterazione del Capitolo 4 e di' all'agente esattamente cosa è fallito.

Poi dai un'occhiata alla cosa vera (i test controllano il testo, ma dovresti comunque guardare):

node bin/lockedin.js endorse
LOCKEDIN_SEED=1 node bin/lockedin.js endorse   # riproducibile

Passo 5 — Rivedi prima di accettare

Non accettare mai un diff che non hai letto. Scorri in particolare questi punti:

• Ha seguito il pattern? Il nuovo comando dovrebbe rispecchiare connect — nessuna nuova dipendenza, nessun console.log dentro src/.
• Solo RNG con seed? Cerca Math.random nel diff. Non dovrebbe essercene nessuno.
• Ha toccato qualcosa che non doveva? Il cambiamento dovrebbe essere additivo; le righe non correlate non dovrebbero spostarsi.
• Il nuovo test è significativo? Dovrebbe fallire se qualcuno in seguito rompe la funzionalità — non limitarsi a verificare true.

Se qualcosa non va, chiedi una correzione (Capitolo 4). Se è a posto, hai finito.

---

✅ Provaci con il tuo agente

Fai davvero l'intero ciclo qui sopra. Poi, per un credito extra, chiedi all'agente di estenderlo:

• "Fai in modo che endorse accetti un nome opzionale: lockedin endorse Ada dovrebbe validare Ada in particolare. Aggiungi un test, mantieni la barriera verde."

Ora hai costruito una funzionalità dall'inizio alla fine. L'ultimo capitolo riguarda il farlo senza attriti — scrivere prompt e revisionare come un lead engineer.

Avanti: Tutorial 4 Prompt e revisione