Agenti autonomi e CLI: cosa cambia

Un agente CLI (Claude Code, Aider, OpenAI Codex CLI, Cline in modalità autonoma) opera come un junior che ha accesso al tuo terminale: legge file, scrive file, esegue comandi, vede output, decide il prossimo passo. È il livello di autonomia più alto disponibile oggi. Cambia tutto: il modo in cui prepari il contesto, scrivi i task e sorvegli il lavoro.

Perché questa lezione conta

Un agente CLI può chiudere in 10 minuti task che richiederebbero un’ora di chat con copia-incolla. Può anche, senza confini chiari, fare commit non richiesti, installare dipendenze indesiderate, modificare file critici, eseguire comandi distruttivi. La differenza fra moltiplicatore e disastro è la struttura del lavoro: repo pulita, istruzioni di progetto, task piccoli, sorveglianza umana attiva. Senza quella struttura, gli agenti producono risultati spettacolari di rado e disordine spesso.

Obiettivo operativo

Alla fine devi saper:

1. distinguere risposta testuale da agente operativo (cosa fa l’uno, cosa fa l’altro);
2. preparare repo, AGENTS.md/CLAUDE.md e task in modo che un agente lavori bene;
3. sorvegliare attivamente: cosa controllare durante e dopo l’esecuzione.

Nucleo della lezione

1. Risposta testuale vs agente operativo

Risposta testuale (chat, livelli 1-3 IDE): il modello produce testo. Sei tu che applichi le modifiche, esegui i comandi, leggi gli errori, ritorni al modello con il dato. L’iterazione è manuale.

Agente operativo (CLI, IDE livello 4): il modello produce un piano e poi lo esegue. Lo schema tipico è loop:

1. analisi del task;
2. esplorazione (read file, search, list directory);
3. modifica file (write/edit);
4. esecuzione comando (test, build, lint, run);
5. lettura output;
6. decisione: continua, corregge, chiede aiuto, dichiara fatto.

Il loop si ripete autonomamente finché l’agente non considera il task concluso o si blocca. Tu interrompi solo se vedi qualcosa che non va.

Differenza pratica: con la chat tu sei nel ciclo. Con l’agente tu sei sopra il ciclo, a sorveglianza. Cambia il tipo di attenzione richiesta.

2. Prerequisiti per usare bene un agente

Senza questi, anche il modello migliore produce caos:

• Repo pulita e tracciata in git: ogni modifica visibile via diff. Branch dedicato per la sessione agentica.
• File di istruzioni di progetto: AGENTS.md, CLAUDE.md, .cursor/rules, o equivalente. Contiene comandi di build/test, convenzioni, vincoli, file da non toccare.
• Comandi di verifica eseguibili: npm test, pytest, make check, bun run build. Se non hai comandi di verifica, l’agente non sa quando è “fatto”.
• Task di dimensione contenuta: 30 minuti di lavoro umano equivalente, non un’ora. Task grandi accumulano ambiguità.
• Confini espliciti: obiettivo singolo, file ammessi, file vietati, dipendenze permesse, criteri di stop.
• Permessi consapevoli: alcuni agenti chiedono conferma per ogni comando, altri eseguono in autonomia. Sai quale modalità usi.

Punto critico: gli agenti possono eseguire comandi distruttivi. Sapere quali permessi hai concesso è prerequisito di sicurezza, non un dettaglio.

3. Sorveglianza attiva

Cosa guardare mentre l’agente lavora:

• File toccati: l’agente sta modificando solo i file ammessi? Se appare un file fuori scope, fermalo.
• Comandi eseguiti: legge la lista comandi (la maggior parte degli agenti la mostra). rm, git push, npm install di pacchetti non autorizzati, modifiche a .env → fermati.
• Test/build: verde o rosso? Un agente che insiste su test rosso è sintomo di approccio sbagliato.
• Loop senza progresso: stesso file modificato 5 volte, stesso errore. Sintomo di confusione, fermalo e riformula.
• Riassunti vaghi: “ho aggiornato la logica” senza dettagli specifici → diff dice cosa davvero è cambiato.
• Dipendenze nuove: ogni package.json modificato va letto. Una dipendenza non chiesta è rumore architetturale.

Dopo: sempre git diff complessivo prima di accettare e fare commit. Mai commit cieco.

Procedura pratica

Sequenza per un task agentico ben fatto:

1. Branch dedicato: git checkout -b feat/nome-task.
2. Stato pulito: niente modifiche non committate prima di iniziare.
3. AGENTS.md/CLAUDE.md aggiornato: comandi correnti, vincoli vivi.
4. Task scritto: obiettivo, file ammessi, file vietati, dipendenze, criteri di “fatto”, comando di verifica.
5. Esecuzione: avvia agente. Sorveglia file modificati e comandi eseguiti.
6. Verifica: comando di verifica passa? Test passa? git diff pulito?
7. Lettura diff completa: file per file.
8. Commit (se ok), o reset (se no): git reset --hard HEAD.

Reset è meno traumatico di “salviamo qualcosa, poi pulisco”. Quando un agente sbaglia, ripartire pulito è più veloce di rattoppare.

Laboratorio guidato

Task agentico controllato:

Setup (10 min):

• branch lab/agente-test;
• progetto reale piccolo o demo;
• file AGENTS.md con: comandi build/test, convenzioni base, file vietati;
• task scritto: “aggiungi una funzione formatPrice(value, locale) con test, accetta number e ritorna string formattata. Solo file src/utils/format.ts e relativo test.”.

Esecuzione (20 min):

• avvia agente;
• monitora ogni file letto/scritto;
• nota se l’agente esce dallo scope (es. modifica file fuori src/utils/);
• nota se esegue comandi non richiesti;
• alla fine, leggi diff completo.

Riflessione (10 min):

• l’agente ha rispettato lo scope?
• ha eseguito comandi non chiesti?
• il diff finale è ciò che ti aspettavi?
• cosa cambieresti nel prossimo prompt?

Output atteso

Una scheda task per agenti CLI riusabile, con sezioni: obiettivo, file ammessi, file vietati, dipendenze permesse, comandi di verifica, criteri di “fatto”, rischi noti. Applicabile a ogni task futuro sostituendo solo il contenuto specifico.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: comprendere come cambia il lavoro quando l’AI può leggere, modificare, eseguire comandi e iterare nel progetto. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Differenza tra risposta testuale e agente operativo: piano, modifica file, esecuzione test, correzione degli errori.
• Importanza di repository pulita, istruzioni di progetto, task piccoli e confini espliciti.
• Sorveglianza umana: leggere log, diff, test falliti, dipendenze installate e modifiche non richieste.

3. Applicazione: svolgi il laboratorio: definire un task agentico di massimo trenta minuti con obiettivo, file probabili, comandi di verifica e criteri di stop. L’output da ottenere è: una scheda task pronta per un agente CLI, completa di rischi e verifiche da pretendere a fine lavoro.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• ho un branch dedicato per ogni sessione agentica;
• ho un AGENTS.md/CLAUDE.md aggiornato per il progetto principale;
• so distinguere modalità con conferma da modalità autonoma del mio agente;
• ho almeno una volta interrotto un agente che stava sbagliando, e ripartito pulito;
• leggo il diff completo prima di committare ciò che l’agente ha prodotto.

Errori comuni

Stato git sporco prima di iniziare. Modifiche non committate + agente al lavoro = impossibile distinguere cosa hai fatto tu e cosa ha fatto l’agente. Sempre stato pulito.

AGENTS.md assente o stale. Senza istruzioni di progetto, l’agente inventa convenzioni. Spesso quelle sbagliate per la tua codebase.

Permessi troppo ampi senza pensarci. “Sì a tutto” è veloce all’inizio, costoso al primo rm non desiderato o al primo git push --force.

Task troppo grande. “Ricostruisci l’autenticazione” → l’agente prende 30 decisioni in autonomia. Spezza in 5 task da 1 decisione l’uno.

Fidarsi del riassunto finale dell’agente. Il riassunto descrive cosa l’agente pensa di aver fatto. Il diff descrive cosa è successo davvero. Quando divergono, hai un problema.

Lasciare l’agente in autonomia totale e tornare dopo 30 minuti. Salvi qualche minuto, perdi ore se il loop è andato male. Sorveglia attivamente, almeno per task non banali.

Prompt di lavoro

Sei un agente CLI. Stiamo lavorando in branch dedicato.

Task: [descrizione in 3 righe]

Vincoli operativi:
- File ammessi (modificabili): [lista]
- File vietati: [lista esplicita + categoria "qualsiasi file di config, .env, lockfile, schema migration"]
- Comandi permessi: [es. npm test, npm run build] — niente altro senza chiedere
- Nuove dipendenze: NO senza approvazione esplicita
- Refactor non richiesti: NO

Comando di verifica finale: [es. npm test && npm run build]

Criterio di "fatto": [criterio osservabile, non sentimentale]

Procedura richiesta:
1. Esponi piano in 3-5 passi.
2. Lista file che intendi toccare e perché.
3. Lista assunzioni.
4. Aspetta autorizzazione.
5. Esegui un passo alla volta, mostrando diff dopo ognuno.
6. Al termine, esegui comando di verifica e mostra output.

Esercizio finale

Riguarda l’ultima sessione agentica. Quanti file ha toccato fuori scope? Quanti comandi ha eseguito non chiesti? Hai dovuto fare reset o pulizia post-hoc? Ogni sì è una riga di vincolo da aggiungere al prossimo prompt o al tuo AGENTS.md. È così che il file di regole cresce: a fronte di errori reali, non per completezza astratta.