Ogni settimana esce un articolo che promette che l’agente di coding “scriverà il codice al posto tuo”. Poi arriva la realtà: serve contesto, servono vincoli, serve qualcuno che valida. Prima di usare qualsiasi strumento — GitHub Copilot, Claude Code, Cursor, opencode, Codex, Gemini CLI — conviene capire cosa c’è sotto il cofano.

Un agente di coding è un programma che usa un modello linguistico per interpretare istruzioni, leggere la codebase e modificare i file. Non è un mago: è un collega molto veloce con una pessima memoria.

L’architettura dell’agente 🏗️

Tutti gli agenti di coding condividono la stessa struttura di base, in quattro pezzi:

1. Contesto — l’insieme di informazioni che l’agente riceve: file aperti, istruzioni del repository, cronologia della conversazione. È ciò che il modello “vede”.
2. Modello — il motore che interpreta il contesto e decide l’azione successiva. Diversi modelli hanno capacità e costi diversi.
3. Strumenti — le capacità operative: leggere e scrivere file, eseguire comandi, cercare nel codice. Senza strumenti l’agente sarebbe solo una chat.
4. Loop — il ciclo in cui il modello osserva, decide, esegue e osserva di nuovo, finché il task non è completo o si ferma.

Il loop è il motivo per cui un agente è diverso da un assistente di autocompletamento: non si limita a suggerire, agisce. E ogni azione può avere conseguenze sui tuoi file.

Cosa può eseguire 🛠️

Le capacità operative si riducono a tre famiglie:

• Lettura e scrittura dei file — creare, modificare, eliminare file del repository. È la competenza che usi di più, e quella da cui derivano i rischi più concreti.
• Esecuzione di comandi — build, test, lint, installazione di dipendenze. L’agente può lanciare quello che lanceresti tu da terminale.
• Ricerca — cercare simboli, riferimenti e pattern in tutto il repository, molto più velocemente di quanto faresti a mano.

Questa è la parte buona. La parte che manca è quella che fa la differenza.

Cosa NON può fare 🚫

Tre aspettative magiche da sfatare subito:

• Non conosce la tua codebase. L’agente impara il progetto dal contesto che gli fornisci a ogni richiesta. Se non gli mostri niente, produce codice generico che somiglia vagamente a ciò che vuoi. Un prompt senza contesto è come consegnare a un nuovo assunto una scrivania vuota e chiedergli di mantenere il tuo servizio.
• Non valida il proprio lavoro. “Ho verificato che funziona” pronunciato dall’agente non vale nulla. L’unica prova di correttezza sono build, test e lint eseguiti davvero. Il testo non è un test.
• Non ha giudizio architetturale. Sa quali sono i pattern comuni, non quali ha scelto il tuo team. Senza istruzioni esplicite, inventerà una convenzione nuova ogni volta che gli viene comodo.

Il modello mentale: il nuovo assunto 👨‍💻

Il modo più onesto di pensare a un agente è un nuovo assunto: intelligente, rapido, instancabile, ma con tre problemi — non conosce il progetto, non conosce le convenzioni e non sa quando sta sbagliando.

Con un nuovo assunto non lanceresti “sistemiamo l’autenticazione” e lo lasceresti solo. Gli daresti:

• il contesto (dov’è il codice, com’è organizzato);
• le regole (convenzioni, confini, comandi di build);
• un obiettivo piccolo e verificabile;
• un controllo su ogni passo.

Con l’agente funziona allo stesso modo. La differenza è che il nuovo assunto ti fa domande; l’agente, se lasciato a sé, indovina — e indovinare su una codebase è il modo più rapido per produrre un disastro con aria di competenza.

Sicurezza e permessi 🔐

Per questo gli agenti moderni hanno un modello di permessi:

• Sola lettura nelle fasi di analisi e pianificazione: può esplorare, ma non modificare nulla.
• Approvazione prima delle operazioni sensibili: modifiche a file, esecuzione di comandi.
• Confini configurabili: file o directory che non deve toccare, comandi che non deve lanciare.

Impostare questi confini non è burocrazia: è il controllo che eserciteresti su qualsiasi strumento che può modificare il tuo lavoro. Tratta le capacità di esecuzione comandi come una chiave di accesso: concedila con criterio, revocala quando non serve.

Quando NON usare l’agente ⛔

L’agente non è la risposta a tutto:

• Task più lenti da delegare che da fare: modifiche di un paio di righe dove sai esattamente cosa scrivere.
• Codebase senza contesto e senza test: se non puoi validare l’output, stai affidando la qualità a una chat.
• Decisioni architetturali di alto livello: la scelta tra due design non si delega a chi non conosce i vincoli di business.
• Sicurezza e dati sensibili: quando le regole non sono ancora chiare, l’agente non deve avere accesso ai segreti del progetto.

Checklist finale ✅

• Ho fornito il contesto minimo necessario (file, istruzioni, percorso)?
• Ho definito obiettivo, vincoli e criteri di accettazione?
• Le regole costanti stanno nel repository, non nel prompt?
• Ho configurato i permessi e i confini prima di iniziare?
• Validerò l’output con strumenti deterministici (build, test, lint)?

Approfondimenti 📚

• Prompt engineering — i fondamenti del prompting per modelli linguistici.
• Anatomia di un LLM — come funziona il motore sotto il cofano.
• Blog: Context engineering e Maintain a rich context.