Prompt Engineering per Claude Code: la guida tecnica definitiva
Nel mondo dei Large Language Models (LLM), la qualità dell’output è direttamente proporzionale alla qualità dell’input. Non si tratta di “chiedere”, ma di progettare l’interazione.
Questa guida analizza i principi fondamentali per architettare prompt efficaci con Claude, basati sui principi di Collaborative Prompting e sulle capacità native del modello.
📑 Indice dei moduli
- Il tono della collaborazione
- Il principio dell’esplicitezza
- Definire i confini (Scope)
- La bozza esplorativa
- Specificare i dettagli (Structured Output)
- Spiegare il “perché” (Context)
- Calibrare la profondità
- Fornire un’impalcatura (Scaffolding)
- Strategie di prompt strutturato
- La strategia “Divide & Conquer”
- Gestione del context window
- Sfruttare le capacità native di Claude
- Quando semplificare
- Caso di studio: dall’input vago all’architected brief
- FAQ: errori comuni e soluzioni
🛠️ Moduli operativi
1. Il tono della collaborazione
Golden Rule: Usa un tono chiaro, diretto e collaborativo.
Analisi: Claude è progettato per interazioni naturali. L’aggressività attiva risposte eccessivamente caute, mentre l’eccessiva cortesia aggiunge rumore senza valore. Pensa a me come a un collega esperto, non come a un software da comandare.
Best Practice:
- ✅ Good: “Rivedi questo testo per errori grammaticali. L’obiettivo è renderlo professionale e autorevole.”
- ❌ Bad: “Correggi questo schifo di codice ORA!!!”
- ❌ Bad: “Se gentilmente potessi per favore aiutarmi quando hai tempo…”
Pro-tip: Puoi essere diretto senza essere rude. “Analizza X e dimmi Y” è perfetto.
2. Il principio dell’esplicitezza
Golden Rule: Formula la richiesta come un comando chiaro con verbo d’azione + target + constraint.
Analisi: Le richieste passive o ambigue generano risultati generici. La struttura ideale è:
[VERBO] + [COSA] + [COME/QUANTO] + [PER CHI/PERCHÉ]
Esempi:
- ❌ Bad: “Mi servono idee per il blog.”
- ✅ Good: “Genera 10 titoli per un post sul remote working destinato a sviluppatori senior italiani. Focus su produttività e work-life balance.”
Verbi potenti: Genera, Analizza, Riassumi, Confronta, Trasforma, Estrai, Valuta, Critica, Ottimizza.
3. Definire i confini
Golden Rule: Vincola il campo d’azione per stimolare precisione e creatività.
Analisi: I constraint non limitano la creatività, la focalizzano. Un campo infinito (“Scrivi una storia”) porta a cliché o paralisi decisionale.
Best Practice – Usa vincoli multipli:
- Quantitativi: lunghezza (parole/caratteri), numero di elementi
- Negativi: cosa NON includere
- Stilistici: tono, formato, pubblico
- Temporali: periodo storico, deadline
Esempio:
Scrivi una storia noir ambientata su Marte nel 2157.
- Massimo 500 parole
- Protagonista: detective androide
- NON usare: cyber, matrix, blade runner (evita cliché)
- Tono: Raymond Chandler incontra Isaac Asimov
4. La bozza esplorativa
Golden Rule: Per task complessi, genera prima un outline o struttura, poi itera.
Analisi: Claude lavora meglio in modo incrementale. Non chiedere il prodotto finito in un solo prompt per compiti articolati.
Workflow ottimale:
- Draft: “Proponi una struttura per un report su [topic]”
- Feedback: “Perfetto, ma espandi la sezione 3 e rimuovi la 5”
- Execution: “Ora scrivi il report completo seguendo questa struttura”
Pro-tip Claude-specifico: Questo approccio è nativo per me. Posso generare outline, tu li modifichi, poi eseguo. È il modo più efficiente di collaborare su documenti lunghi.
5. Specificare i dettagli (Structured Output)
Golden Rule: Richiedi formati strutturati quando devi processare l’output.
Analisi: Il testo libero è ottimo per leggibilità umana, ma difficile da integrare in workflow tecnici. Claude supporta nativamente: Markdown, JSON, XML, CSV, tabelle, codice.
Esempi di richieste strutturate:
Tabella Markdown:
Confronta React, Vue e Svelte in una tabella con colonne:
[Framework | Performance | Curva Apprendimento | Ecosistema | Use Case Ideale]
JSON:
Estrai i dati chiave da questo testo e restituiscili come JSON con schema:
{
"title": "",
"author": "",
"date": "YYYY-MM-DD",
"keywords": [],
"summary": ""
}
6. Spiegare il “perché” (Context)
Golden Rule: Fornisci sempre il contesto e l’obiettivo finale.
Analisi: Senza contesto, Claude deve inferire l’intento (e può sbagliare). Il “perché” cambia radicalmente il “come”.
Esempio comparativo:
Senza contesto:
“Dammi 5 slogan per un brand di caffè”
Con contesto:
“Dammi 5 slogan per un brand di caffè premium. Contesto: Target millennial 25-35, attenti a sostenibilità ed etica. Chicchi da fattorie indipendenti colombiane, packaging compostabile. Obiettivo: Differenziarci da Starbucks puntando su autenticità e impatto sociale.”
Il secondo genera output infinitamente più rilevanti.
7. Calibrare la profondità
Golden Rule: Specifica esplicitamente il livello di dettaglio e il target audience.
Analisi: Claude tende naturalmente alla concisione per query semplici e al dettaglio per task complessi. Ma puoi calibrare esplicitamente.
Strategie di calibrazione:
Per pubblico:
- “Spiega [topic] a un: bambino di 5 anni / studente universitario / esperto del settore”
- “Livello tecnico: beginner / intermediate / advanced”
Per lunghezza:
- “Riassumi in: 1 tweet / 1 paragrafo / 500 parole / formato long-form”
- “Dammi: solo i punti chiave / analisi approfondita con esempi”
Esempio:
Spiega il teorema di Bayes.
- Target: developer che conosce programmazione ma non statistica
- Includi: un esempio pratico con codice Python
- Lunghezza: 300-400 parole
8. Fornire un’impalcatura (Scaffolding)
Golden Rule: Fornisci template, esempi o formati da seguire.
Analisi: Il Few-Shot Prompting (mostrare esempi) è uno dei metodi più potenti per fissare stile e formato. “Show, don’t tell.”
Best Practice:
Template esplicito:
Riassumi ogni articolo usando ESATTAMENTE questo formato:
**📌 Titolo:** [titolo]
**🎯 Tesi Principale:** [1 frase]
**🔑 Punti Chiave:**
- [punto 1]
- [punto 2]
- [punto 3]
**💡 Takeaway:** [1 frase actionable]
Few-shot example:
Classifica questi feedback per sentiment. Esempi:
Input: "Il prodotto è arrivato rotto"
Output: NEGATIVO | Categoria: Logistica | Urgenza: Alta
Input: "Ottimo servizio clienti!"
Output: POSITIVO | Categoria: Supporto | Urgenza: Bassa
Ora classifica questi 10 feedback: [...]
9. Strategie di prompt strutturato
Golden Rule: Usa tecniche specifiche per attivare comportamenti desiderati.
Analisi: Alcune strategie di prompt hanno dimostrato efficacia empirica. Non sono “magic words”, ma pattern che guidano il ragionamento.
Tecniche comprovate:
Chain of Thought (CoT):
"Ragiona step-by-step prima di dare la risposta finale"
"Mostra il tuo processo di ragionamento"
✅ Utile per: problemi matematici, logica, debugging
Self-Critique:
"Genera la risposta, poi criticala e migliorala"
"Identifica 3 potenziali problemi nella tua soluzione"
✅ Utile per: revisione codice, fact-checking, analisi
Role-Playing:
"Agisci come un esperto di [dominio] con 20 anni di esperienza"
"Adotta la prospettiva di un [ruolo specifico]"
✅ Utile per: attivare vocabolario tecnico, cambiare tono
Constraint-Based:
"Risposta in massimo 3 frasi"
"Usa solo parole da 1000 parole più comuni in italiano"
✅ Utile per: controllare output, semplificare linguaggio
10. La strategia “Divide & Conquer”
Golden Rule: Spezza task complessi in subtask sequenziali gestibili.
Analisi: Claude mantiene coerenza meglio su task focalizzati. Per progetti grandi, agisci da orchestratore: gestisci i pezzi, poi chiedi la sintesi.
Esempio – Report complesso:
❌ Approccio monolitico:
"Scrivi un report completo di 10 pagine su strategie SEO 2025
con analisi competitor, keyword research, piano editoriale e KPI"
Risultato: Coerenza calante, sezioni superficiali
✅ Approccio modulare:
Step 1: "Analizza i top 5 competitor e identifica i loro punti di forza SEO"[ricevi output, valuti]
Step 2: “Basandoti su questa analisi, proponi 20 keyword long-tail con volume search e difficulty”
[ricevi output]
Step 3: “Crea un piano editoriale mensile usando queste keyword”
[ricevi output]
Step 4: “Ora sintetizza tutto in un executive summary di 2 pagine”
11. Gestione del context window
Golden Rule: Claude ha 200K token (~150K parole) di context, ma va gestito strategicamente.
Analisi: Il context window include tutto: la conversazione corrente, file caricati, system prompt. Più è pieno, più rischi degradazione della qualità.
Best Practices:
Usa file esterni invece di paste giganti:
- ❌ “Ecco 50 pagine di documentazione [paste]”
- ✅ Carica il PDF e: “Analizza questo documento”
Riassumi conversazioni lunghe:
"Riassumi la nostra conversazione degli ultimi 20 messaggi
focalizzandoti sulle decisioni prese e i prossimi step"
Poi continua con il riassunto come riferimento.
Riferimenti esterni:
"Basandoti sul documento che ti ho caricato prima (report-Q4.pdf),
genera un piano d'azione"
Quando ricominciare:
- Dopo 50+ messaggi su topic diversi
- Quando noti risposte che perdono coerenza
- Prima di task completamente nuovo
12. Sfruttare le capacità native di Claude
Golden Rule: Claude non è solo testo. Ha tool integrati – usali.
Capacità native (claude.ai e API):
🌐 Web search
"Cerca le ultime notizie su [topic]"
"Qual è il prezzo corrente di Bitcoin?"
"Trova informazioni aggiornate sul nuovo regolamento GDPR"
Claude cerca automaticamente quando serve dati post-training (gennaio 2025).
🎨 Artifacts
Per contenuto riutilizzabile, Claude crea automaticamente artifact:
- HTML/React/SVG per UI interattive
- Documenti Markdown standalone
- Script Python/JavaScript
- Diagrammi Mermaid
Esempio:
"Crea un dashboard HTML interattivo con Chart.js
che visualizzi questi dati di vendita"
💻 Computer use (in Beta)
Claude può:
- Creare e modificare file (docx, xlsx, pptx, pdf)
- Eseguire codice Python/bash
- Installare pacchetti e dependencies
Esempio:
"Crea un file Excel con 3 sheet: Vendite, Costi, Profitti.
Applica formule e conditional formatting"
📄 Analisi multimodale
Carica direttamente:
- PDF: documenti, presentazioni
- Immagini: screenshot, mockup, grafici
- CSV/Excel: dati strutturati
Esempio:
[Carica screenshot]
"Analizza questo design e suggerisci 3 miglioramenti UX
specifici per mobile"
13. Quando semplificare
Golden Rule: Non tutti i task richiedono engineering complesso.
Analisi: Usa il framework completo per task complessi, ma sii pragmatico per query semplici.
Quando basta un prompt semplice:
- ✅ Traduzioni dirette
- ✅ Correzioni grammaticali
- ✅ Domande fattuali semplici
- ✅ Generazione creativa breve
Quando serve engineering:
- ⚠️ Report strutturati multi-sezione
- ⚠️ Analisi con più fonti/criteri
- ⚠️ Generazione codice production-ready
- ⚠️ Strategie di business
- ⚠️ Contenuto che deve matchare brand guidelines specifiche
Euristica: Se il task richiede più di 30 secondi a un umano esperto, vale la pena progettare il prompt.
🎓 Caso di studio: dall’input vago all’architected brief
Obiettivo: Ottenere materiale didattico sullo Stoicismo per una lezione universitaria.
❌ Richiesta vaga
“Parlami dello Stoicismo.”
Risultato tipico:
Lo Stoicismo è una scuola filosofica fondata ad Atene
da Zenone di Cizio nel III secolo a.C. I principali esponenti
furono Seneca, Epitteto e Marco Aurelio. Insegna che...[continua con testo enciclopedico generico]
Problemi:
- Non strutturato
- Nessun focus specifico
- Non utilizzabile direttamente
- Manca contesto pedagogico
✅ Brief architettato
Applichiamo i principi appresi:
**[Context + Why]**
Sto preparando una lezione introduttiva di 90 minuti sullo
Stoicismo per studenti universitari di Filosofia (secondo anno)
senza conoscenze pregresse sulla filosofia ellenistica.
**[Explicit Goal]**
Obiettivo: fornire una comprensione solida dei concetti chiave
e della rilevanza contemporanea, preparandoli per una discussione
in classe.
**[Divide & Conquer - Step 1]**
Per prima cosa, crea una scaletta della lezione divisa in 3
sezioni principali (30 min ciascuna).
**[Constrain Scope]**
Struttura: Introduzione (contesto storico) → Corpo (concetti core)
→ Conclusione (applicazioni moderne)
**[Scaffolding]**
Per ogni sezione includi:
- **Concetto chiave:** nome + definizione in 1 frase
- **Figura storica:** 1 filosofo stoico + citazione rappresentativa
- **Esempio pratico:** scenario contemporaneo che illustra il concetto
- **Domanda per discussione:** per stimolare il dibattito in classe
**[Structured Output]**
Formatta come Markdown con headers H2 per sezioni e bullet lists
per i sotto-punti.
**[Tone]**
Tono: accademico ma accessibile, evita gergo eccessivo.
Gli studenti devono sentirsi coinvolti, non intimiditi.
📤 Output di Claude
# Lezione: introduzione allo Stoicismo
**Durata:** 90 minuti | **Livello:** Introduttivo
---
## Sezione 1: nascita e contesto storico (30 min)
### Concetto chiave: la Scuola della Stoà
**Definizione:** Movimento filosofico fondato ad Atene (~300 a.C.)
che poneva la virtù come unico vero bene e l'imperturbabilità
(ataraxia) come obiettivo esistenziale.
### Figura storica: Zenone di Cizio (334-262 a.C.)
**Citazione:** "Il bene non risiede nei beni esterni, ma nella
nostra anima."
**Contesto:** Dopo la morte di Alessandro Magno, il mondo greco
era frammentato e insicuro. Lo Stoicismo offriva stabilità
interiore in tempi caotici.
### Esempio pratico
**Scenario moderno:** Durante una crisi economica (es. 2008),
chi ha interiorizzato principi stoici si concentra su ciò che
può controllare (competenze, rete sociale) invece di angosciarsi
per il crollo del mercato.
### Domanda per discussione
*"Come cambierebbe il vostro approccio allo stress da esami se
adottaste la prospettiva stoica?"*
---
## Sezione 2: i pilastri del pensiero stoico (30 min)
### Concetto chiave 1: la Dicotomia del Controllo
**Definizione:** Distinzione radicale tra ciò che dipende da noi
(giudizi, intenzioni) e ciò che non dipende da noi (corpo,
reputazione, morte).
### Figura storica: Epitteto (50-135 d.C.)
**Citazione:** "Non sono le cose a turbarci, ma i giudizi che
diamo su di esse."
### Esempio pratico
**Scenario:** Durante un colloquio di lavoro, puoi controllare
la preparazione e l'atteggiamento, NON la decisione del
recruiter. L'ansia dovrebbe focalizzarsi solo sul primo.
### Domanda per discussione
*"Identificate 3 fonti di ansia nella vostra vita: quale
dipende realmente da voi?"*
---
### Concetto chiave 2: vivere secondo natura
**Definizione:** Allineare le proprie azioni alla razionalità
(logos), l'essenza dell'essere umano e dell'ordine cosmico.
### Figura storica: Marco Aurelio (121-180 d.C.)
**Citazione (Meditazioni):** "Conforme a natura è ciò che la
natura richiede. E quella dell'uomo razionale richiede la
virtù."
### Esempio pratico
**Scenario:** Nella cultura della produttività ossessiva, lo
Stoicismo suggerisce di chiedersi: "Sto lavorando per
necessità razionale o per inseguire status?"
---
## Sezione 3: lo Stoicismo oggi (30 min)
### Rilevanza contemporanea
**1. Stoicismo e psicologia moderna**
- **Connessione:** La Terapia Cognitivo-Comportamentale (CBT)
deriva direttamente dai principi stoici.
- **Esempio:** "Cognitive reframing" = reinterpretazione
razionale degli eventi (puro Epitteto).
**2. Stoicismo nel business e leadership**
- **Praticanti celebri:** Tim Ferriss, Ryan Holiday
- **Applicazione:** Decision-making razionale sotto pressione,
resilienza emotiva
**3. Stoicismo e minimalismo**
- **Connessione:** Entrambi enfatizzano la distinzione tra
bisogni e desideri
- **Pratica:** "Negative visualization" (premeditatio malorum)
per apprezzare ciò che si ha
### Esercizio pratico di chiusura
**"Morning Pages" Stoiche:**
Ogni mattina per una settimana, scrivete:
1. Una cosa fuori dal vostro controllo che vi preoccupa
2. Una cosa nel vostro controllo su cui potete agire oggi
3. Come applichereste la "dicotomia" per ridurre l'ansia
### Domanda finale per discussione
*"Lo Stoicismo è ancora rilevante in un'epoca di attivismo
sociale, o rischia di promuovere passività?"*
---
## Materiali di approfondimento
- **Testo primario:** Epitteto, *Enchiridion* (cap. 1-5)
- **Lettura moderna:** Massimo Pigliucci, "How to Be a Stoic"
- **Podcast:** "The Daily Stoic" by Ryan Holiday
---
**Note per il docente:**
- Preparare slide con citazioni visive per ogni filosofo
- Portare esempi di "Stoic journals" contemporanei
- Riservare 15 min a fine lezione per Q&A aperto
Confronto dei risultati:
- ❌ Vago: 200 parole di Wikipedia
- ✅ Architettato: Piano lezione completo di 800 parole, strutturato, applicabile immediatamente
❓ FAQ: errori comuni e soluzioni
1. “Perché Claude si rifiuta di aiutarmi?”
Cause comuni:
- Richiesta che potrebbe violare policy (malware, contenuti per minori, ecc.)
- Ambiguità che Claude interpreta come potenzialmente dannosa
- Richiesta di contenuti copyrighted
Soluzioni:
- Riformula chiarendo l’intento legittimo: “Sto studiando X per motivi di sicurezza” vs “Dammi codice per X”
- Fornisci contesto: “È per un progetto universitario su…”
- Se rifiuto persiste: usa il feedback button per segnalare falso positivo
2. “Come ottenere codice production-ready?”
Problema: Il codice generato funziona in demo ma manca error handling, edge cases, best practices.
Soluzione – Approccio iterativo:
Step 1: "Genera un prototipo funzionante di [feature]"
Step 2: "Ora aggiungi: error handling, input validation, logging"
Step 3: "Refactoring per seguire [standard/pattern specifico]"
Step 4: "Genera unit tests con coverage >80%"
Step 5: "Code review: identifica potenziali issues di sicurezza/performance"
3. “Le risposte sono troppo lunghe/corte”
Soluzione: Calibra esplicitamente:
- Troppo lunghe: “Rispondi in massimo 3 paragrafi” o “Solo i key points”
- Troppo corte: “Spiega in dettaglio con esempi concreti” o “Analisi approfondita richiesta”
4. “Claude dimentica il contesto dopo tanti messaggi”
Spiegazione: Dopo 50+ messaggi su topic diversi, il context si frammenta.
Soluzioni:
- Chiedi riassunti periodici: “Sintetizza le decisioni chiave finora”
- Usa il riassunto come “reset point”
- Inizia nuova chat per topic completamente nuovo
- Usa file esterni per conservare informazioni permanenti
5. “Come faccio a far generare immagini?”
Risposta: Claude non genera immagini (Diffusion models), ma può:
- ✅ Analizzare immagini che gli carichi
- ✅ Creare diagrammi SVG/Mermaid
- ✅ Generare HTML/CSS per UI visive
- ✅ Scrivere prompt dettagliati per Midjourney/DALL-E
6. “Posso fidarmi dei fatti che Claude fornisce?”
Risposta onesta:
- ✅ Sì per conoscenze generali pre-2025
- ⚠️ Con cautela per:
- Eventi post-gennaio 2025 (usa web search)
- Statistiche precise (chiedi fonti)
- Consigli medici/legali (sempre verificare con professionista)
- Citazioni (potrebbero essere parafrasi, non letterali)
Best practice: Per fatti critici, chiedi: “Cerca su web informazioni aggiornate su [topic]”
🎯 Checklist finale: prompt engineering mastery
Prima di inviare un prompt complesso, verifica:
- [ ] Chiarezza: Il verbo d’azione è esplicito?
- [ ] Contesto: Ho spiegato il “perché”?
- [ ] Constraint: Ho definito limiti (lunghezza, tono, scope)?
- [ ] Formato: Ho specificato output strutturato se necessario?
- [ ] Esempi: Ho fornito template/scaffold dove utile?
- [ ] Granularità: Per task grandi, l’ho scomposto in step?
- [ ] Target: Ho indicato il pubblico/livello tecnico?
Se hai 5+ check, il tuo prompt è well-engineered. ✅
📚 Risorse di approfondimento
Documentazione ufficiale
- Anthropic Prompt Engineering Guide: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering
- Claude API Documentation: https://docs.anthropic.com
- Support & Best Practices: https://support.anthropic.com
Tools & playground
- Claude.ai: Chat interface con Artifacts e tool access
- Claude Code: CLI per agentic coding (https://docs.anthropic.com/en/docs/claude-code)
- API Console: Test prompt con parametri personalizzati
Community & learning
- Anthropic Blog: Aggiornamenti su nuove capabilities
- Prompt Library: Esempi curati per use case comuni
- Discord/Forum: Community di developer e power users
🚀 Conclusione
Il prompt engineering non è magia, è design dell’interazione. Come ogni skill:
- Inizia semplice: Applica 2-3 principi per volta
- Itera: Nessun prompt è perfetto al primo colpo
- Testa patterns: Trova cosa funziona per il tuo dominio
- Documenta: Salva prompt efficaci come template riutilizzabili
Claude è uno strumento collaborativo, non un oracolo. I risultati migliori arrivano da conversazioni iterative dove tu guidi la direzione e io fornisco l’execution.