> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Scrivere istruzioni efficaci

Le **Istruzioni** sono il campo da cui dipende tutto il resto. Un agente con
buoni documenti e istruzioni vaghe dà risposte generiche; lo stesso agente con
istruzioni precise diventa affidabile.

Non sono una descrizione dell'agente, sono un **mandato**: dicono cosa deve fare
quando arriva una richiesta, e soprattutto cosa deve fare quando la richiesta non
è quella che ti aspettavi.

![Il campo Istruzioni di un agente: dice chi è, con che tono risponde, cosa fare a ogni richiesta passo per passo e cosa non deve inventare. In basso a sinistra il pulsante Ottimizza](/_fern-img/551c8f53912d14c3c5a9911ccdadf32371cce61e503984ba168c967b2b3b9821.webp)

## Quattro blocchi, in quest'ordine

**Chi è.** Il ruolo e con chi parla. Cambia tutto: la stessa informazione si
scrive in modo diverso per un legale e per un commerciale.

> *«Sei l'assistente dell'ufficio gare. Rispondi a colleghi commerciali che non
> hanno competenze legali.»*

**Cosa deve fare.** Il compito, e da dove prende le informazioni.

> *«Rispondi a domande sui capitolati caricati. Se la risposta sta in un
> documento, citalo indicando articolo e pagina.»*

**Cosa non deve fare.** È la parte che quasi tutti dimenticano, ed è quella che
evita i guai. Includi sempre cosa fare quando non sa.

> *«Non dedurre requisiti che non sono scritti. Non dare valutazioni
> sull'opportunità di partecipare a una gara. Se l'informazione non è nei
> documenti, rispondi "Non è nei capitolati che ho" e fermati.»*

**Come deve rispondere.** Lunghezza, struttura, tono, lingua.

> *«Massimo dieci righe. Prima la risposta, poi il riferimento. Tono formale,
> niente elenchi puntati se non ci sono più di tre voci.»*

## Buone e cattive, affiancate

| Invece di                                 | Scrivi                                                                                                                                                |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| «Sei un assistente utile e professionale» | «Sei l'assistente dell'ufficio gare, rispondi a commerciali senza competenze legali»                                                                  |
| «Rispondi in modo accurato»               | «Se la risposta è in un documento, citalo. Se non c'è, dillo e fermati»                                                                               |
| «Non dire cose sbagliate»                 | «Non dedurre requisiti non scritti. Non stimare importi che non trovi»                                                                                |
| «Sii breve»                               | «Massimo dieci righe, poi il riferimento al documento»                                                                                                |
| «Aiuta con le domande sui clienti»        | «Rispondi su stato ordini e condizioni di pagamento. Per reclami e rimborsi, di' di scrivere a [assistenza@esempio.it](mailto:assistenza@esempio.it)» |

La differenza è sempre la stessa: la colonna di sinistra è un aggettivo, quella
di destra è una regola che si può verificare. Se leggendo una riga non sai dire
se l'agente l'ha rispettata o no, quella riga non serve.

## La riga di ripiego

Un agente che non sa una cosa ha due modi di comportarsi: dirlo, o riempire il
vuoto. Sceglie il primo solo se glielo scrivi, possibilmente con la frase esatta
che vuoi leggere.

> *«Se l'informazione non è nei documenti allegati, rispondi esattamente: "Questo
> non è coperto dai documenti che ho. Chiedi a \[ufficio]." Non proporre
> alternative e non cercare sul web.»*

Vale anche al contrario. Se l'agente deve poter uscire dal perimetro in certi
casi, dillo: *«Se la domanda riguarda una normativa aggiornata dopo la data dei
documenti, cerca sul web e segnala che la fonte non è interna.»*

## Si correggono per aggiunte, non per riscritture

Quando l'agente sbaglia, la reazione istintiva è riscrivere le istruzioni da capo.
È quasi sempre la mossa peggiore: perdi le regole che funzionavano e ricominci a
tarare da zero.

Il metodo che funziona è un altro. Osservi **un** comportamento sbagliato,
aggiungi **una** riga che lo vieta con parole precise, riprovi lo stesso caso.

| Cosa hai visto             | Cosa aggiungi                                                           |
| -------------------------- | ----------------------------------------------------------------------- |
| Ha inventato una scadenza  | «Non riportare date che non compaiono nel documento»                    |
| Ha risposto con tre pagine | «Massimo dieci righe, salvo richiesta esplicita di approfondire»        |
| Ha dato un parere fiscale  | «Non dare pareri fiscali o legali: rimanda all'ufficio competente»      |
| Ha risposto in inglese     | «Rispondi sempre in italiano, anche se la domanda è in un'altra lingua» |

> **Note**
>
> Tieni le aggiunte in fondo, una per riga, senza rimescolare quello che c'era
> prima. Dopo qualche settimana le istruzioni diventano il verbale di tutti gli
> errori che l'agente non fa più: è esattamente il documento che serve a chi
> erediterà l'agente dopo di te.

## Quanto lunghe

Cinque righe sono poche, cinque pagine sono troppe. La misura giusta è: tutto
quello che diresti a una persona nuova nel suo primo giorno, niente di più.

Se le istruzioni cominciano a contenere elenchi di prodotti, listini o procedure
dettagliate, quel materiale non va lì: va nella
[conoscenza dell'agente](/conoscenza-agente). Le istruzioni dicono *come
comportarsi*, i documenti dicono *cosa è vero*. Contenuti che cambiano nel tempo
scritti dentro le istruzioni invecchiano senza che nessuno se ne accorga.

Il pulsante **Ottimizza** riscrive quello che hai buttato giù in una forma più
ordinata. Usalo come punto di partenza, non come ultima parola: rileggi sempre
il blocco su cosa l'agente non deve fare, perché è quello che conosci solo tu.

> **Info**
>
> Alcune regole valgono per tutti gli agenti dell'azienda: riservatezza, lingua,
> argomenti vietati. Quelle non si ripetono in ogni agente: le imposta chi
> amministra l'area di lavoro nelle [Regole per l'AI](/regole), e valgono in
> automatico.