Tutorial 4 Prompting and Reviewing it

Tutorial 4 · Prompt e revisione

Obiettivo: la meta-abilità. Ora sai costruire una funzionalità con un agente — questo capitolo riguarda il farlo senza attriti e in modo ripetibile: scrivere prompt che centrano il bersaglio al primo colpo, rivedere i diff con efficienza, iterare quando le cose vanno storte e mantenere lo slancio tra una sessione e l'altra.

← Precedente: Tutorial 3 Il tuo primo task con l'agente · Avanti: Tutorial 5 Localizzazione

---

Scrivi prompt come un lead, non come una barra di ricerca

L'agente è un ingegnere junior rapido, letterale ed entusiasta. Guidalo come guideresti uno bravo:

• Enuncia l'obiettivo e i vincoli. «Aggiungi endorse» è debole. «Aggiungi endorse seguendo il pattern di connect, solo RNG con seed, con test, la barriera resta verde» è forte. I vincoli sono il modo per ottenere codice che si incastra.
• Indica esempi. «Segui il pattern usato da renderConnect» batte un paragrafo di descrizione. Il codice esistente è la migliore specifica.
• Chiedi un piano prima delle modifiche su qualsiasi cosa non banale. Reindirizzare un piano costa poco; disfare dieci file modificati costa caro.
• Un task per prompt. Mettere insieme «aggiungi endorse, refactorizza anche l'RNG, aggiorna anche il README» produce un diff ingarbugliato e difficile da rivedere.
• Dagli la barriera dei test. «Esegui npm test e non considerarlo finito finché non è verde» trasforma l'agente in qualcosa che controlla il proprio lavoro.

Rivedi il diff ogni volta

La velocità è il senso di un agente — ma la velocità non letta è come si pubblicano i bug. Costruisci un riflesso di revisione rapido e coerente:

1. Ambito: ha cambiato solo ciò che doveva? Righe non correlate che si spostano sono un campanello d'allarme.
2. Pattern: combacia con il codice circostante, senza nuove dipendenze e senza I/O dentro src/?
3. Le regole del progetto: per questo repo, sono solo RNG con seed (fai grep di Math.random nel diff), testo visibile all'utente nei bundle di lingua (non hardcoded), e le righe delle schede non superano mai la larghezza a cui il layout applica il padding.
4. Accessibilità: il nuovo output sopravvive a --accessible? Esegui lockedin --accessible <your command> e controlla che si legga come testo semplice e pulito — nessun nuovo glifo decorativo che sguscia oltre a11yFilter.
5. Test: c'è un nuovo test, e fallirebbe davvero se la funzionalità si rompesse? Chiedi: "Quale riga cambierei per far fallire questo nuovo test?"
6. Eseguilo: npm test, poi esegui il comando e guarda l'output.

Non devi capire ogni carattere — ma devi capire ogni decisione. Se non riesci a spiegare un cambiamento, chiedi all'agente di spiegartelo prima di accettarlo.

Itera quando non è verde

Una barriera rossa è un passo normale, non un fallimento. La soluzione è un feedback preciso:

"npm test fallisce con: [paste the exact error]. Il test di larghezza di renderEndorse si aspetta che ogni riga della scheda sia ≤ 60 colonne visibili. Correggilo senza indebolire il test."

Incolla il testo reale dell'errore. «È rotto» fa tirare a indovinare all'agente; lo stack trace lo fa correggere. E preferisci continuare la stessa conversazione invece di ricominciare da capo — l'agente ha già il contesto di ciò che ha appena scritto. Se due o tre iterazioni non convergono, fai un passo indietro e ridefinisci l'ambito: il task potrebbe essere troppo grande per un solo prompt.

Mantieni lo slancio tra le sessioni

Il lavoro reale si estende oltre una singola seduta. Due abitudini mantengono un agente efficace nel tempo:

• Memoria / convenzioni. Se il tuo agente supporta una memoria persistente o un file di istruzioni del progetto, registra lì le regole che deve sempre seguire (ad es. «tutta la casualità deve usare pick/shuffle», «esegui npm test prima di dichiarare finito»). Enunci una convenzione una volta invece che a ogni prompt.
• Una nota di passaggio di consegne. Questo repo mantiene un documento di stato breve e ripulito in docs/HANDOFF.md: cos'è il progetto, come è costruito, come è testato e cosa viene dopo. Quando torni (o passi il lavoro a un collega — o a un altro agente), quella nota ricostruisce il contesto in pochi secondi. Chiedi al tuo agente di tenerla aggiornata come parte di un cambiamento.

Guardrail che vale la pena mantenere

• La barriera non è negoziabile. Test verdi prima di pubblicare qualsiasi cosa. È ciò che ti permette di andare veloce e di fidarti dell'output.
• Sei tu il revisore responsabile. L'agente scrive; tu decidi. Accettare un diff significa che ne rispondi.
• Passi piccoli e verificabili battono un unico salto gigante. Ogni cambiamento accettato dovrebbe lasciare l'app funzionante.

---

✅ Provaci con il tuo agente

1. Scrivi una specifica di un paragrafo per un comando mentor («dispensa consigli non richiesti»), vincoli inclusi, e fai in modo che l'agente lo costruisca con i test prima di tutto — piano, test, codice, barriera — rivedendo a ogni passo.
2. Chiedi all'agente di aggiornare docs/HANDOFF.md perché menzioni il nuovo comando.
3. Rompi qualcosa di proposito (ad es. cancella una voce di un pool), esegui npm test ed esèrcitati a fornire all'agente l'errore esatto da correggere.

---

Dove andare dopo

• Scorri il codice reale in src/lockedin.js — ora ne conosci la forma.
• Leggi docs/HANDOFF.md per le note di stato e architettura del progetto stesso.
• Goditi le battute nel Riferimento dei comandi.

Questo è il tutorial. Ora sai dirigere un agente di IA per costruire e cambiare software reale dietro una barriera dei test — usando l'esempio più tronfio che si possa immaginare. D'accordo? 👇