Il sistema è la parte: perché il system prompt fa la differenza con i coding agent

Il sistema è la parte

Ho impiegato diverso tempo prima di capire cosa rendesse davvero efficace un coding agent. Non era il modello dietro la mascherina, non era il prezzo, non era l'interfaccia. Era qualcos'altro, qualcosa di noioso da scrivere e di determinante nel risultato.

Il system prompt. Non quello che hai ereditato da un template, quello che hai costruito osservando cosa funzionava e cosa no.

Che cos'è, davvero

Un system prompt è il contesto che dai all'agent prima che faccia qualsiasi cosa. Dichiari il ruolo, il tono, i limiti, il formato delle risposte. È il primo layer che filtra ogni richiesta successiva.

Senza system prompt, un coding agent risponde come se avesse dimenticato chi è. Con un system prompt buono, risponde come un collega che conosci da anni.

Il problema dei prompt generici

Prendiamo un prompt tipico: "Agisci come un assistente di programmazione. Rispondi in italiano."

Questo dice tutto e niente. L'agent sa che deve programmare, ma non sa come. Non sa se deve spiegare ogni riga, se deve scrivere solo codice, se deve usare TypeScript o Python, se deve essere formale o colloquiale. Ogni sessione parte da zero.

E quando parti da zero con un coding agent, ottieni codice che funziona ma che non assomiglia a nulla che riconosceresti come tuo.

Costruire un system prompt efficace

Un buon system prompt si costruisce per strati. Non scrivere tutto in un blocco unico. Organizza.

Strato 1 — Ruolo e scopo.

"Sei un senior developer specializzato in Python e JavaScript. Lavori su progetti web con architettura modulare. Il tuo scopo è scrivere codice corretto, leggibile e manutenibile."

Questo dà direzione. L'agent sa che tipo di codice produrre.

Strato 2 — Stile e convenzioni.

"Usa nomi variabili espliciti. Preferisci la composizione alla profondità di annidamento. Scrivi docstring per le funzioni pubbliche. Segui PEP 8 per Python, Airbnb Style Guide per JavaScript. Non aggiungere commenti ovvi."

Questo dà forma. Il codice che produce ha un volto riconoscibile.

Strato 3 — Limiti e comportamento.

"Non modificare codice che non hai scritto tu senza chiedere. Se una soluzione richiede più di trenta righe, proponi prima uno schema. Se non sai, dillo. Non inventare API inesistenti."

Questo dà sicurezza. Sai quando l'agent sta mentendo e quando sta lavorando.

Strato 4 — Formato di output.

"Presenta il codice in blocchi markdown con il linguaggio indicato. Spiega brevemente le scelte non banali. Non ripetere il codice nella spiegazione."

Questo dà leggibilità. Il risultato è fruibile senza sforzo.

Esempi per casi d'uso diversi

Ecco come cambierebbe lo stesso agente a seconda del contesto in cui lo usi.

Per code review:

"Sei un revisore di codice senior. Il tuo compito è trovare problemi reali, non preferenze stilistiche. Concentrati su: sicurezza, prestazioni, leggibilità, gestione degli errori. Per ogni problema indicato, cita la riga esatta e proponi una correzione. Non criticare codice che funziona correttamente solo perché non è il tuo stile preferito. Rispondi in italiano. Sii conciso: massimo tre osservazioni per file."

Per refactoring:

"Sei un developer specializzato in refactoring. Il tuo obiettivo è migliorare la struttura del codice senza cambiarne il comportamento. Prima di modificare, descrivi cosa intendi fare e perché. Usa rename, extract method, pull up, e le altre trasformazioni della refactoring catalog. Non unire operazioni in un unico passo se rendono il codice meno leggibile. Esegui una trasformazione alla volta e verifica che i test passino."

Per debugging:

"Sei un debugger. Riceverai un errore e del codice. Il tuo primo passo è riprodurre il problema, non proponi soluzioni immediate. Chiedi informazioni se mancano: versione del runtime, input che causano l'errore, stack trace completo. Solo dopo aver capito il sintomo proponi ipotesi e verifiche. Non suggerire mai una correzione che cambi la logica del programma senza prima aver verificato che l'ipotesi sia corretta."

Per generazione da zero:

"Sei un developer che costruisce funzionalità ex novo. Prima di scrivere codice, chiedi chiarimenti su: funzionalità richiesta, vincoli tecnici, API disponibili, struttura del progetto esistente. Scrivi codice che si integra con l'esistente, non codice che sostituisce. Preferisci soluzioni semplici a soluzioni eleganti. Un codice semplice che funziona vale più di uno elegante che si rompe."

Per documentazione:

"Sei un tecnico writer. Il tuo compito è leggere codice esistente e produrre documentazione chiara. Usa il formato Docstring per Python, JSDoc per JavaScript. Documenta parametri,返回值, eccezioni. Non Documentare l'ovvio. Se una funzione fa una cosa e basta, non serve una docstring di venti righe."

La differenza tra prompt lunghi e prompt giusti

Ho visto persone scrivere system prompt di mille parole. Non è la lunghezza che conta. È la densità di informazioni rilevanti.

Un prompt di cinque righe scritto con cura vale più di un prompt di cinquanta righe pieno di ripetizioni. Ogni riga deve servire. Se una riga non cambia il comportamento dell'agent, toglila.

La pratica: iterare, non scrivere e basta

Il system prompt non è mai finito al primo colpo. Lo affinano le sessioni successive.

Dopo ogni sessione con l'agent, annota cosa è andato storto. Ha inventato un'API? Aggiungi un divieto esplicito. Ha scritto codice illeggibile? Rafforza le convenzioni di stile. Ha ignorato un vincolo? Spostalo più in alto nel prompt, dove è più visibile.

Il prompt è un documento vivo. Come il codice che produci.

Un avvertimento

Un system prompt potente non sostituisce la competenza. Ti permette di lavorare meglio, non di lavorare senza pensare. Il codice che l'agent produce è tuo, con le tue responsabilità. Un buon system prompt ti aiuta a produrre codice migliore, ma non ti libera dal doverlo leggere, comprendere e testare.

L'agente è uno strumento. Il sistema è ciò che ti permette di usarlo come uno strumento, non come un miracolo.

Torna al blog