IDE AI: completamento vs agente

Dentro un IDE AI moderno (Cursor, Windsurf, VS Code con Copilot, Zed) l’AI opera a quattro livelli di autonomia diversi. Confonderli porta a usare lo strumento giusto al momento sbagliato. Ognuno ha rischio, contesto e modalità di verifica diversi.

Perché questa lezione conta

Un autocomplete che propone la riga successiva è una cosa. Un agente che modifica 12 file in 5 minuti è un’altra. Stesso strumento, stessa interfaccia, comportamenti incomparabili. Senza distinguere i livelli, finisci a dare a un agente lo stesso livello di attenzione che daresti a un autocomplete — e l’agente ne approfitta per fare cose che non avevi chiesto.

Obiettivo operativo

Alla fine devi saper:

1. nominare i quattro livelli di autonomia e cosa cambia fra l’uno e l’altro;
2. scegliere il livello giusto per un task specifico;
3. impostare confini espliciti quando passi a livelli alti.

Nucleo della lezione

1. Quattro livelli di autonomia

Livello 1 — Autocomplete inline. Mentre digiti, AI propone il completamento della riga o di poche righe. Tu accetti con Tab o ignori. Ambito: una funzione, raramente più. Rischio: basso. Esempio: GitHub Copilot autocomplete, Cursor Tab.

Livello 2 — Inline edit. Selezioni un blocco di codice, premi una scorciatoia (Cmd+K in Cursor, Cmd+I in altri IDE), descrivi la modifica. AI riscrive il blocco. Ambito: una funzione, un componente, raramente un file. Rischio: medio. Punto chiave: vedi diff prima di accettare.

Livello 3 — Chat nel progetto. Pannello chat che vede file aperti, può leggere altri file su richiesta. Risponde con codice da incollare, o propone modifiche con anteprima. Tu autorizzi ogni applicazione. Ambito: 1-3 file, conversazione iterativa. Rischio: medio-alto. Esempio: Cursor Chat, Continue.

Livello 4 — Agente multi-file. AI riceve task, esplora la codebase, modifica più file, esegue comandi (test, build, install), itera. Ambito: feature intere, refactor cross-file. Rischio: alto. Esempio: Cursor Composer / Agent, Claude Code, Aider, Cline.

Differenza chiave: ai livelli 1-2 sei tu che dirigi e l’AI completa. Ai livelli 3-4 l’AI prende decisioni, tu sorvegli.

2. Accesso al filesystem: doppio taglio

Più alto è il livello, più l’AI tocca il filesystem. Vantaggio: contesto reale, modifiche coerenti su più file, esecuzione di test. Svantaggio: rischio di modifiche fuori scope.

Cose che un agente può fare e che devi sapere:

• modificare file che non hai citato (perché “sembravano collegati”);
• aggiungere dipendenze (npm install, pip install) senza chiedere esplicitamente;
• cancellare file che ritiene obsoleti;
• riformattare grandi porzioni di codice;
• eseguire comandi (test, build, migrazioni database in alcuni setup).

Mitigazioni:

• usa branch git separato per ogni sessione agentica importante;
• abilita modalità di approvazione se lo strumento la offre (ogni edit chiede conferma);
• esamina diff completo prima del commit (mai commit cieco);
• definisci scope esplicito nel prompt: file ammessi, file vietati, dipendenze permesse.

3. Impostare confini

Per livelli 3 e 4, il prompt deve includere:

• File coinvolti (lista esplicita), oppure pattern (src/components/Button/*).
• File vietati (es. “non toccare configurazione, .env, file di build”).
• Obiettivo singolo (“aggiungi validazione email al form X” invece di “migliora il form”).
• Test attesi: cosa deve passare prima di considerare il task fatto.
• Divieto di refactor non richiesto: “non rinominare variabili esistenti, non spostare codice in altri file”.
• Divieto di nuove dipendenze se non esplicitamente richiesto, oppure approvazione preventiva.

Senza confini, l’agente interpreta come può, e tendenzialmente più ampio.

Procedura pratica

Decidere il livello giusto per un task:

1. Una riga, dentro funzione esistente → livello 1 (autocomplete).
2. Riscrivi questa funzione, stesso comportamento, stile diverso → livello 2 (inline edit).
3. Aggiungi una feature piccola che tocca 1-3 file noti → livello 3 (chat nel progetto).
4. Refactor che attraversa la codebase, o feature complessa → livello 4 (agente). Solo dopo: piano scritto + branch + scope esplicito.

Regola di soglia: se non sai esattamente quali file verranno toccati, fermati prima di passare a livello 4 e chiedi un piano.

Laboratorio guidato

Tre task, stesso giorno, stesso IDE AI, livelli diversi:

1. Livello 1: aprendo un file esistente, completa una funzione di utility (es. formatta data in stringa). Conta quante Tab accetti vs quante ignori.
2. Livello 2: seleziona una funzione di 20 righe, chiedi “estrai la validazione in funzione separata”. Leggi diff, accetta o rifiuta.
3. Livello 4: chiedi a un agente “aggiungi internazionalizzazione i18n al progetto”. Senza scope esplicito → osserva quanti file modifica e quante dipendenze installa. Poi ripeti con scope esplicito (file ammessi, libreria specifica, no nuove dipendenze fuori da quella). Confronta i due diff.

Il secondo run dovrebbe essere drasticamente più piccolo e mirato.

Output atteso

Una tabella personale a 4 righe (livelli) e 4 colonne (tipo task adatto, esempio reale del tuo lavoro, scorciatoia/comando, modalità di verifica). Riferimento da consultare prima di iniziare un task: sei sicuro che il livello sia il più basso che basta?

Studio passo passo

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

1. Prima lettura: chiarisci l’obiettivo: capire la differenza tra assistenza locale sul codice e intervento agentico su più file del progetto. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Autocomplete, inline edit, chat nel progetto, agenti multi-file: quattro livelli diversi di autonomia.
• Perché l’accesso al file system migliora il contesto ma aumenta il rischio di modifiche troppo ampie.
• Come impostare confini: file coinvolti, obiettivo singolo, test attesi, divieto di refactor non richiesti.

3. Applicazione: svolgi il laboratorio: far modificare a un IDE AI una piccola funzione, poi ripetere con una richiesta più grande e confrontare i diff. L’output da ottenere è: una lista di regole personali per decidere quando usare completamento, edit puntuale o agente.

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

• so distinguere autocomplete da inline edit da chat da agente;
• ho un esempio concreto di task per ogni livello;
• ho un branch dedicato per ogni sessione agentica importante;
• ho almeno una volta osservato un agente fare modifiche fuori scope, e so come limitarlo.

Errori comuni

Usare livello 4 quando bastava livello 2. “Refactor questa funzione” non richiede un agente: lo fai con inline edit in 30 secondi. L’agente è overkill e introduce rischio.

Accettare diff senza leggere. Più il diff è grande, più la tentazione di scorrere senza leggere. Soglia: se diff > 100 righe, dividi il task.

Non usare branch separati per agenti. Una sessione agentica andata male su main può richiedere ore di pulizia. Branch dedicato → reset in un comando.

Permettere npm install in autonomia. Una nuova dipendenza è una decisione architetturale, non un dettaglio. Va approvata, non subìta.

Confondere “ho letto il riassunto del modello” con “ho letto il diff”. Il riassunto è marketing dell’agente. Il diff è la realtà.

Prompt di lavoro

Task: [descrizione in 2 righe]

Modalità: agente con scope ristretto.

File ammessi (modificabili): [lista esplicita]
File vietati: configurazione, .env, file di build, lockfile, schema migrazioni
Nuove dipendenze: NO. Se serve nuova libreria, fermati e chiedi.
Refactor laterale: NO. Tocca solo ciò che è strettamente necessario al task.
Test/build da eseguire prima di chiudere: [comandi]
Criterio di "fatto": [criterio osservabile]

Prima di partire:
1. Conferma file che intendi toccare.
2. Conferma che non tocchi nient'altro.
3. Lista assunzioni.

Aspetta autorizzazione esplicita prima di modificare file.

Esercizio finale

Riguarda l’ultima sessione agentica significativa che hai fatto. Quanti file ha toccato? Quanti erano davvero necessari? Quante dipendenze ha aggiunto? Hai letto il diff completo o ti sei fidato del riassunto? Le risposte a queste domande sono la differenza fra usare un agente come moltiplicatore e usarlo come moltiplicatore di rischio.