Contesto: cosa esiste, cosa serve sapere, cosa non inventare

Il contesto è la parte del prompt che riduce le assunzioni. Dice al modello qual è la situazione reale: stack, file coinvolti, vincoli del progetto, stato del lavoro, decisioni già prese e informazioni mancanti.

Perché questa lezione conta

Quando un modello non riceve contesto, colma i vuoti con pattern generici. Questo può produrre codice plausibile ma incompatibile con il progetto. Quando riceve troppo contesto, può perdere il punto, sprecare token o seguire dettagli irrilevanti.

Il contesto efficace è selettivo: abbastanza per evitare invenzioni, non così tanto da sommergere il task.

Tre tipi di contesto

Contesto tecnico

Include stack, runtime, framework, versioni rilevanti, comandi di build/test, struttura dei file e vincoli di deploy.

Esempio:

Stack:
- Astro static output;
- contenuti in Markdown via content collection;
- deploy su server LiteSpeed;
- non introdurre routing server-side.

Questo tipo di contesto impedisce soluzioni incompatibili, come introdurre API runtime in un sito statico.

Contesto di progetto

Include convenzioni locali: naming, pattern, moduli, componenti, scelte architetturali, limiti già decisi.

Convenzione locale:
- i corsi laboratorio usano data file in src/data;
- le lezioni vivono in src/content/lezioni/<corso>;
- gli slug sono generati dal titolo;
- non cambiare slug esistenti.

Questa informazione non è deducibile dal mondo esterno. Va fornita o resa leggibile all’agente.

Contesto di task

Include stato corrente e obiettivo immediato:

• cosa è già stato fatto;
• cosa non funziona;
• quali file sono probabilmente coinvolti;
• cosa non deve essere toccato;
• quale risultato chiude il task.

Cosa non inventare

Una buona sezione contesto contiene anche divieti epistemici: dice al modello di non fingere conoscenza.

Esempi:

Se non trovi una funzione nel codice fornito, non assumerne l'esistenza.

Se mancano dettagli sulla policy privacy, fermati e chiedi chiarimento.

Non proporre dipendenze nuove senza spiegare perché quelle esistenti non bastano.

Queste istruzioni non garantiscono perfezione, ma rendono più visibile l’errore.

Esempio operativo

Prompt fragile:

Il login non funziona. Trova il problema.

Prompt con contesto:

Ruolo: debugger backend web.

Contesto:
- login con cookie httpOnly;
- backend Express;
- frontend Astro;
- il problema avviene solo in produzione, non in locale;
- deploy dietro LiteSpeed;
- non usiamo OAuth.

File probabilmente rilevanti:
- src/server/auth.ts
- src/server/session.ts
- src/pages/login.astro

Prima di proporre patch:
1. elenca quali informazioni mancano;
2. formula massimo 3 ipotesi;
3. indica come falsificarle con log, header o test manuale.

Laboratorio guidato

Scegli un task che hai chiesto o potresti chiedere a un LLM. Scrivi due versioni:

1. prompt senza contesto;
2. prompt con contesto strutturato.

Usa questa griglia:

Sezione	Contenuto
Stack	linguaggio, framework, runtime, deploy
Stato attuale	cosa funziona, cosa non funziona
File rilevanti	file o moduli da leggere
Convenzioni	pattern e limiti locali
Cose vietate	cosa non deve inventare o toccare
Informazioni mancanti	cosa deve chiedere prima di procedere

Output atteso

Un modello di blocco “contesto” compilabile in meno di un minuto per task ricorrenti.

Il blocco deve essere breve, ma non generico. Se puoi incollarlo in qualunque progetto senza modificarlo, è troppo vago.

Checklist di verifica

• il contesto distingue stack, progetto e task;
• i file rilevanti sono indicati o il modello sa come trovarli;
• le assunzioni vietate sono esplicite;
• il prompt chiede chiarimenti quando mancano dati;
• il contesto non include materiale irrilevante.

Errori comuni

Scrivere contesto narrativo. Il modello lavora meglio con contesto strutturato: liste, tabelle, file, vincoli.

Incollare codice senza spiegare perché. Un file lungo senza orientamento può aumentare rumore.

Dimenticare lo stato corrente. Dire solo come dovrebbe funzionare non basta: serve cosa accade ora.

Collegamenti

• Modulo: Anatomia del prompt operativo — lezione 7 del corso.
• Lezione precedente: Ruolo: lente operativa, non costume.
• Prossima lezione: Obiettivo: una cosa, verbo-oggetto-criterio.