Prompt engineering per task tecnici complessi

Sono Davide Cocozza, co-founder di Datazen e dev da oltre 5 anni. Negli ultimi 18 mesi ho scritto migliaia di prompt per Claude Code, Cursor, GPT-5 e modelli locali, lavorando su progetti reali con clienti italiani — dal refactoring di legacy PHP a sistemi di lead generation B2B. Questa guida raccoglie i pattern che funzionano davvero su task tecnici complessi, non gli esempi giocattolo da tutorial.

Se cerchi il contesto generale sull'ecosistema AI coding leggi prima la mia guida all'AI per sviluppatori italiani 2026. Qui andiamo subito sul pratico: cosa scrivere, come strutturarlo, perché funziona.

Cosa rende un prompt tecnico veramente efficace nel 2026

Un prompt tecnico efficace nel 2026 non è una frase. È un documento strutturato con ruolo, contesto, vincoli, esempi e schema di output. I dev senior che usano LLM come daily driver scrivono prompt che assomigliano più a una spec funzionale che a una chat. La differenza in produttività è misurabile.

I numeri arrivano da fonti differenti: la documentazione ufficiale Anthropic Prompt Engineering Guide descrive le tecniche che spostano il success rate da 40% a oltre 70% su task complessi, il OpenAI Cookbook raccoglie pattern simili con metriche di benchmark, e il DSPy framework di Stanford ha dimostrato in paper peer-reviewed che prompt programmatici strutturati battono i prompt naive di 15-30 punti percentuali su task di reasoning. Il dato sui 1.450 token medi viene dai miei log Claude Code degli ultimi 6 mesi su progetti client reali.

Tre principi che ho interiorizzato:

• Il contesto vale più del modello. Un GPT-5 con prompt vago perde contro un Claude 3.5 con prompt strutturato bene. Il modello migliore è quello a cui hai dato più contesto rilevante.
• I vincoli espliciti riducono allucinazioni. "Non inventare nomi di file, usa solo quelli che leggi" è la singola istruzione che cambia di più la qualità su task multi-file.
• Lo schema di output è il moltiplicatore di affidabilità. Chiedere JSON, XML o un formato preciso elimina il 70% degli errori di parsing nei flussi automatizzati.

I 5 pattern di prompt engineering tecnico

Questi sono i 5 pattern che uso ogni giorno. Coprono il 90% dei task tecnici complessi.

Quale scegliere quando? Ecco la mappa che uso io:

Pattern 1 come usare il template role task format constraints

Il template Role-Task-Format-Constraints (RTFC) è la base. Lo uso in oltre metà dei miei prompt tecnici. La struttura è semplice ma va rispettata in ordine.

Esempio completo di prompt RTFC per un task reale di refactoring TypeScript:

Ruolo: sei un senior TypeScript engineer specializzato in refactoring 
verso pattern funzionali. Lavori su una codebase Next.js 15 production.

Task: refactora la funzione `processUserOrders` nel file 
`src/services/orders.ts`. Obiettivo:
- ridurre complessità ciclomatica da 14 a sotto 8
- estrarre i side effect (DB writes, email) in funzioni pure 
  composte via Result<T, E>
- mantenere la signature pubblica identica
- tutti i test in `orders.test.ts` devono continuare a passare

Formato output:
- codice completo del file `orders.ts` modificato
- lista bullet point dei cambi (max 5 righe)
- NO spiegazioni intermedie, NO markdown fence ```

Vincoli:
- non aggiungere dipendenze npm
- non modificare altri file
- non rinominare export pubblici
- se trovi ambiguità sull'API esistente, STOP e fai una domanda 
  invece di assumere
- se la complessità target non è raggiungibile senza breaking 
  change, dimmelo prima di scrivere codice

Questo prompt è circa 200 token. Su Claude Sonnet ha un one-shot success rate stabile sopra l'80% nei miei test interni. La parte che fa la differenza è l'ultimo vincolo: dire al modello cosa fare quando non sa è molto più potente di sperare che indovini.

Pattern 2 few shot examples per task ambigui

Il few-shot prompting è la mossa che usi quando il task ha uno stile specifico che è difficile da spiegare a parole ma facile da mostrare. Per la teoria di base ti rimando alla mia guida completa zero-shot vs few-shot prompting. Qui ti mostro come applicarlo a task tecnici reali.

Use case tipico: hai una convention di naming proprietaria nei tuoi commit message. Spiegarla a parole prende 200 token e il modello la sbaglia comunque. Mostrarla con 3 esempi prende 150 token e funziona quasi sempre.

Ruolo: generatore di commit message per il team Datazen.

Convention: <type>(<scope>): <imperativo breve, max 60 char>

Esempi:
Input: aggiunto endpoint POST /api/leads con validazione zod
Output: feat(api): aggiungi endpoint POST /api/leads con zod

Input: fix race condition su retry queue del webhook stripe
Output: fix(webhook): risolvi race condition su retry queue stripe

Input: refactor del modulo billing per estrarre invoice service
Output: refactor(billing): estrai invoice service da modulo billing

Task: genera commit message per: 
"aggiornata libreria openai sdk da 4.2 a 5.1, rimossi tipi deprecati 
e fixati 3 call site"

Tre regole sui few-shot examples che ho imparato sbagliando:

• Usa esempi diversi tra loro. Se tutti i tuoi esempi iniziano con feat(api) il modello pensa che sia obbligatorio. Mostra varietà nei pattern che vuoi catturare.
• Mostra anche il caso edge. Se un campo a volte è opzionale, includi un esempio con e uno senza. Altrimenti il modello assume "sempre presente".
• Da 3 a 5 esempi è il sweet spot. Sotto 3 il pattern non si stabilizza. Sopra 5 stai pagando token per zero accuracy marginale e il context starts shifting.

Su LLM moderni (Claude Sonnet 3.5+, GPT-5, Gemini 2.5+) il few-shot non serve quasi mai per task standard. Serve eccome per task che hanno DNA proprietario.

Pattern 3 plan then execute per task multi step

Il pattern Plan-then-Execute è quello che ha più impatto su task complessi reali. Lo applico ogni volta che un task tocca 3+ file o quando il rollback è costoso. La logica: il modello prima produce un piano testuale, tu come dev lo leggi e lo correggi, poi il modello esegue il piano approvato.

Il punto chiave è che plan-then-execute non è solo una tecnica di prompt, è un cambio di workflow. Stai trattando il modello come un dev junior bravo ma overconfident. Il piano scritto è la tua superficie di review. Senza piano, stai approvando codice a scatola chiusa.

Sul fatto che proteggere il codice durante prompting sia anche un tema di privacy, ho scritto una guida dedicata: AI coding privacy come usare l'AI senza esporre il codice. Vale la lettura se lavori su codebase con NDA strict.

Errori più comuni nei prompt tecnici

Otto errori che vedo costantemente nei prompt di dev italiani (junior e senior). Se li fai, stai bruciando token e produttività.

• Prompt vago senza criteri di successo misurabili ('rendi questo codice migliore')
• Zero vincoli espliciti su cosa NON fare — il modello assume libertà di modificare tutto
• Nessun esempio quando il task ha stile proprietario o naming convention specifica
• Output schema implicito — chiedi 'JSON' senza specificare i campi, il modello inventa
• Nessun fallback istruito per ambiguità — il modello indovina invece di chiedere
• Single-attempt mindset — non itererai mai sul prompt, accetti il primo output
• Context dump senza prioritizzazione — incolli 50K token sperando che il modello capisca
• Niente test di regressione sul prompt — non sai se il prompt v2 è meglio o peggio di v1

L'errore più costoso in produzione è il numero 5: nessun fallback su ambiguità. Un modello senza istruzione esplicita "se non sai, fermati e chiedi" inventerà. Inventerà nomi di funzioni che non esistono, importerà librerie non installate, assumerà che un endpoint risponda in un certo modo. Una sola riga nel prompt — "Se non sei certo, STOP e fai una domanda" — taglia gli errori di allucinazione del 50-70% nei miei test.

L'errore numero 8 (assenza di test del prompt) è quello che separa i dev che fanno prompt engineering serio da quelli che fanno prompt-and-pray. Tieni un file prompts.md versionato in repo, con prompt vincenti per i task ricorrenti del tuo team. Quando modifichi un prompt, fallo su un branch e confronta output su almeno 5 casi di test prima di mergeare.

Prompt template riusabili Datazen per dev italiani

Tre template copy-paste che uso settimanalmente. Sostituisci le parentesi quadre con il tuo contesto. Per il workflow di code review più avanzato vedi anche la guida AI code review tool e workflow dev 2026.

Template 1 — Debugging di un bug riportato dal cliente:

Ruolo: senior debugger TypeScript/Node.js. Approccio Sherlock Holmes: 
ipotesi, evidenze, conclusione.

Contesto: questo errore appare in produzione su Next.js 15 + Prisma:
[INCOLLA STACK TRACE]

File rilevanti che ti passo:
[FILE 1]
[FILE 2]

Task: 
1. Elenca 3 ipotesi sulla causa root, dalla più probabile alla meno
2. Per ciascuna ipotesi indica quali file/log/test guarderesti per 
   confermarla
3. NON scrivere fix prima che io confermi quale ipotesi è giusta

Vincoli: se mancano informazioni per formulare le 3 ipotesi, chiedi 
i 2-3 dati specifici che ti servono. Non assumere.

Template 2 — Code review pre-merge:

Ruolo: senior code reviewer. Stile: diretto, concreto, no fluff.

Task: review questo diff PR. Output strutturato in 4 sezioni:
1. BLOCKER (bug, security issue, breaking change non documentato)
2. CONCERN (design smell, complessità eccessiva, test mancanti su 
   path critici)
3. NIT (stile, naming, refactor minori — usa prefisso "nit:")
4. POSITIVE (cosa è fatto bene — 1-2 punti)

Vincoli: ogni item con riferimento a file:linea. Se un item è "secondo me" 
e non oggettivo, prefissa con "opinion:". Niente commenti vaghi del tipo 
"considera di migliorare X" — sii specifico.

Diff:
[INCOLLA DIFF]

Template 3 — System design discussion:

Ruolo: senior system architect con esperienza su sistemi 10K-100K 
utenti. Pragmatico, non over-engineer.

Contesto: stiamo progettando [DESCRIVI FEATURE]. 
Stack attuale: [STACK]. 
Vincoli operativi: [TEAM SIZE, BUDGET, TIMELINE]. 
Constraint non negoziabili: [GDPR, latenza, etc].

Task:
1. Proponi 2 architetture alternative (semplice vs scalabile)
2. Per ciascuna: pro, contro, costi mensili stimati, complessità 
   operativa
3. Raccomandazione finale con rationale di 3-5 righe
4. Lista esplicita di cosa rimandiamo a "fase 2" (premature 
   optimization)

Vincoli: se la feature non è abbastanza definita per scegliere 
un'architettura, fai le 3 domande chiarificatrici più importanti 
prima di proporre.

Questi tre template coprono circa il 70% dei miei prompt non-trivial. La cosa importante non è copiarli identici, è capire la struttura: ruolo, contesto, task in output strutturato, vincoli espliciti incluso un fallback per ambiguità.

Per dev italiani che vogliono andare oltre il prompt engineering classico, Claude Code vs Cursor confronto reale 2026 confronta i due strumenti su task identici e mostra come gli stessi prompt rendano diversamente. E se stai costruendo prodotti AI completi, l'angolo sviluppo web AI di Datazen mostra come integriamo prompt engineering, retrieval e fine-tuning sul lato applicativo.

Risorse esterne che vale la pena seguire: il GitHub repo Awesome ChatGPT Prompts per ispirazione cross-dominio, il corso gratuito DeepLearning.AI ChatGPT Prompt Engineering for Developers e la Anthropic Prompt Library con esempi production-grade per task tecnici. Se vuoi vedere come iterare su un prompt fino al risultato giusto la mia guida su come raffinare un prompt descrive il loop iterativo che applico in pratica.

Limiti del prompt engineering quando non basta

Il prompt engineering ha limiti precisi. Se ignori questi limiti perdi tempo cercando di ottimizzare prompt dove il problema è altrove.

Limite 1 — Knowledge cutoff e dominio specializzato. Su librerie/framework rilasciati dopo il knowledge cutoff del modello, nessun prompt magico ti salva. Il modello inventa API che non esistono. Soluzione: passare la documentazione nel context, usare modelli con web search, oppure fine-tuning su corpus aggiornato.

Limite 2 — Codebase troppo grandi per il context window. Su monorepo con 500K+ righe di codice, anche un context da 200K token non basta. Il modello vede frammenti, non la struttura. Servono pattern come retrieval-augmented generation, indici semantici sulla codebase, o tool come Claude Code che gestiscono il context dinamicamente leggendo file on-demand.

Limite 3 — Decisioni architetturali multi-stakeholder. Un prompt eccellente non sostituisce conversazione con product, security, ops. L'AI può proporre 3 architetture; chi sceglie quale ha senso politico-organizzativo sei tu. Non delegare decision-making strategico ai prompt.

Limite 4 — Quando serve fine-tuning, non prompt engineering. Se stai eseguendo lo stesso task 100K volte al giorno con format proprietario complesso, il fine-tuning batte il prompt engineering per costo, latenza e accuracy. Soglia indicativa: oltre 10K esecuzioni/giorno con prompt sopra i 2K token, calcola il break-even del fine-tuning.

Limite 5 — Codice critico per la sicurezza. Su codice che gestisce autenticazione, pagamenti, dati medici, il prompt engineering ti dà velocità ma non ti dà la garanzia che serve. Lo standard 2026 è: AI scrive il draft, security review umano obbligatorio, test di penetration, audit trail. Mai shippare codice security-critical sulla fiducia del prompt.

Il prompt engineering è uno strumento potente ma non onnipotente. Funziona magnificamente nel range 60-80% dei task tecnici comuni. Oltre, servono altre tecniche: RAG, fine-tuning, multi-agent systems, human-in-the-loop strutturato.

Domande frequenti