Come scrivere un documento di scope per un agente AI

Pubblicato ad agosto 2026.

TL;DR: Un documento di scope è ciò che trasforma “voglio un agente IA per la mia azienda” in un numero che puoi preventivare e che un cliente può firmare. Servono sei parti: il trigger, gli input, gli output, gli strumenti coinvolti, ciò che è esplicitamente escluso e un elenco scritto di test di accettazione. Scrivilo prima di preventivare una fee di costruzione, non dopo. Io lo fisso a un prezzo fisso di $500–$1.000 come deliverable di audit, separato dalla build.

[Prospettiva dell’operatore] Gestisco più di 30 agenti in produzione tra un brand di consulenza e Pickleland, una struttura di pickleball a Pflugerville, TX, e ho fissato l’ambito di build di agenti per clienti basandomi su questa esperienza. Il motivo più comune per cui un incarico su un agente va storto non è il codice — è che nessuno ha scritto cosa significasse “finito” prima che uscisse la fattura. Un documento di scope risolve questo problema in una sola sessione. È il deliverable meno affascinante che produco e quello che evita più discussioni.

Indice

Perché un documento di scope, non un’email di proposta

Un’email di proposta descrive cosa farai. Un documento di scope definisce come appare “finito” — con abbastanza precisione che tu e il cliente possiate entrambi confrontarlo con l’agente completato e concordare, senza bisogno di parlarne, se ha superato la prova.

Questa distinzione conta perché i prezzi degli agenti IA funzionano solo se la fee di costruzione è ancorata a qualcosa di fisso. Fai un preventivo fisso su un ambito indefinito e hai preventivato un numero contro cui non puoi effettivamente consegnare — il modello mentale del cliente di “un agente IA per la mia azienda” continua a espandersi gratuitamente finché non ti opponi, e opporsi dopo l’acconto è una conversazione peggiore che definire il confine prima.

Ne scrivo uno per ogni build, anche per quelle piccole. Un agente a flusso singolo riceve una versione di mezza pagina. Un sistema multi-agente riceve il documento completo. Il formato non cambia — cambia solo la lunghezza.

Le sei cose di cui un documento di scope ha bisogno

1. Il trigger. Cosa fa partire l’agente — l’invio di un modulo, un orario programmato, un’email in entrata, un webhook da un altro strumento. Nomina il trigger esatto, non una categoria di trigger. “Parte quando viene inviato un modulo lead” è scope. “Gestisce i lead in entrata” non lo è.

2. Gli input. Quali dati riceve l’agente e da dove provengono. Elenca i campi, non solo la fonte — “nome, email, dimensione dell’azienda e il campo di testo libero del modulo Typeform”, non “i dati del modulo”.

3. Gli output. Cosa produce l’agente e dove va. Stessa regola: nomina la destinazione e il formato. “Pubblica una bozza di risposta nel canale Slack #leads per l’approvazione umana” è scope. “Risponde ai lead” non lo è.

4. Gli strumenti e le integrazioni coinvolti. Ogni API, database o piattaforma che l’agente chiama. È anche qui che scrivi tutto ciò che non stai esplicitamente integrando — un cliente che dà per scontato che il suo CRM sia incluso perché l’ha menzionato una volta nella call di discovery è la fonte più comune di scope creep che ho visto.

5. Cosa è escluso. Un elenco breve ed esplicito di cose che l’agente non farà, anche se sembrano adiacenti. Se stai costruendo un agente di classificazione dei lead, scrivi “non invia messaggi in uscita” anche se sembra ovvio — ovvio per te non è ovvio per un cliente che non ha mai definito l’ambito di un software prima.

6. L’elenco dei test di accettazione. L’elenco effettivo dei casi che l’agente completato deve superare prima che sia dovuto il pagamento finale. Non “funziona bene” — casi specifici e verificabili: “classifica correttamente 9 lead campione su 10 dal dataset fornito”, “pubblica con successo sul canale Slack collegato senza intervento manuale”, “gestisce un invio malformato (campo email mancante) senza andare in crash”. Questa è la sezione più importante del documento, perché è quella a cui entrambe le parti possono fare riferimento in seguito senza rimettere in discussione cosa si intendesse.

Il template

Questa è la struttura effettiva che uso. Copiala, compila le sei sezioni e avrai un documento a cui puoi affiancare un prezzo.

AGENT SCOPE DOCUMENT — [Client name] / [Project name]
Date: [date]

1. TRIGGER
   [What starts this agent running]

2. INPUTS
   [Exact data fields and their source]

3. OUTPUTS
   [What the agent produces, in what format, sent where]

4. TOOLS & INTEGRATIONS
   Included: [every API/platform/database touched]
   Explicitly excluded: [anything adjacent that is NOT built]

5. EXCLUSIONS
   [What this agent will not do, even if related]

6. ACCEPTANCE TESTS
   [ ] [Specific, checkable test case]
   [ ] [Specific, checkable test case]
   [ ] [Specific, checkable test case]
   ...

BUILD FEE: $[amount], due [payment terms]
MAINTENANCE RETAINER: $[amount]/month, starting [date]
CHANGE REQUESTS: priced separately, quoted before work starts

Signed: _______________  Date: _______

Le righe della fee di costruzione e del canone esistono perché il prezzo sia ancorato direttamente allo scope sopra — vedi come dimensiono entrambi i numeri se non hai mai preventivato una build prima. Un cliente che firma questo documento sta firmando lo scope e il prezzo nello stesso gesto, ed è proprio questo il punto.

Come conduco la call che produce questo documento

Fisso il prezzo della sessione di scoping stessa come un audit a prezzo fisso di $500–$1.000, separato dalla fee di costruzione — mai inglobato in essa, anche quando il cliente procede. Due motivi: impedisce che la fase di scoping diventi lavoro di vendita non pagato, e fa sì che il cliente prenda sul serio la call invece di trattarla come una consulenza gratuita.

La call in sé dura 30–45 minuti, strutturata attorno alle sei sezioni sopra, in ordine. Non lascio che la conversazione vada alla deriva verso “cosa potrebbe fare in teoria un agente IA per la tua azienda” — quella è una conversazione diversa, più costosa, ed è quella che produce documenti che nessuno può preventivare. Chiedo il trigger per primo, perché un cliente che non riesce a nominare cosa avvia il processo di solito non ha un flusso di lavoro abbastanza stabile da automatizzare ancora — cosa che vale la pena far emergere prima che entrambi vi impegniate in una build.

Spedisci il prompt, non la pagina bianca

Non scrivo a mano la prima bozza del documento. Prendo i miei appunti della call — spesso solo un paragrafo disordinato di punti elenco — e li incollo in Claude:

Here are my raw notes from a scoping call for an AI agent build. Turn them
into a scope document with exactly these six sections: Trigger, Inputs,
Outputs, Tools & Integrations, Exclusions, Acceptance Tests. For each
section, flag anything the notes don't specify clearly enough to build
against, rather than guessing or filling the gap yourself. The acceptance
tests need to be specific and checkable — reject vague criteria like
"works correctly" and either sharpen them into a concrete test case or
flag them for me to clarify with the client.

[paste raw notes]

Quell’ultima istruzione — segnala le lacune invece di colmarle — è la parte che conta. Un modello inventerà volentieri un test di accettazione dall’aspetto plausibile per completare il documento, e un test dall’aspetto plausibile che non corrisponde a ciò che il cliente intendeva davvero è peggio di uno spazio vuoto su cui devi andare a chiedere.

Errori comuni che vedo ancora fare

Scrivere la sezione delle esclusioni per ultima, o saltarla del tutto. La sezione delle esclusioni è quella che la maggior parte delle persone tratta come opzionale. È quella che previene più dispute. Scrivila prima dei test di accettazione, non dopo.

Test di accettazione che descrivono comportamenti invece di risultati. “L’agente dovrebbe capire il tono del cliente” è un comportamento. “La bozza di risposta dell’agente viene approvata senza modifiche in 7 casi campione su 10” è un risultato. Solo i risultati sono verificabili.

Definire l’ambito partendo da una singola conversazione senza appunti scritti. Se il documento di scope è il primo artefatto scritto dell’incarico, stai ricostruendo la call a memoria giorni dopo. Prendi appunti durante la call, nell’ordine delle sei sezioni, e il documento si scrive quasi da solo.

Lasciare che sia il cliente a scrivere lo scope. Un cliente che descrive cosa vuole con le sue parole è un input per il documento, non il documento stesso. Il suo linguaggio è di solito modellato sulle funzionalità (“voglio che gestisca i miei lead”), non sui test. Tradurlo in criteri di accettazione verificabili è il vero valore della sessione di scoping — è per questo che è un deliverable a pagamento e non un modulo che compilano da soli.

Gli strumenti che uso per gestire tutto questo

Claude redige il documento a partire dagli appunti grezzi della call usando il prompt sopra, e segnala le lacune invece di indovinarle.

Notion è dove vive il documento di scope finito, condiviso con il cliente prima che venga raccolto qualsiasi acconto — lo stesso posto in cui tengo il resto della documentazione dell’incarico.

Airtable traccia quali incarichi sono in fase di scoping rispetto a firmati o in costruzione, una riga per cliente, così che un documento di scope non resti mai non firmato per settimane senza che nessuno se ne accorga.

FAQ

Quanto dovrebbe essere lungo un documento di scope?

Lungo quanto serve per rendere verificabile ogni test di accettazione, e non di più. Un agente a flusso singolo può stare in mezza pagina. Un sistema multi-agente con diverse integrazioni può occupare due o tre pagine. La lunghezza non è l’obiettivo — l’obiettivo è che un cliente e uno sviluppatore, leggendo i test di accettazione in modo indipendente, concordino su se sono stati superati.

E se il cliente vuole cambiare lo scope dopo aver firmato?

Quella è una richiesta di modifica, preventivata separatamente e quotata prima che il lavoro inizi — scrivi questa clausola nel documento stesso, come nel template sopra. Un documento di scope che può essere espanso silenziosamente dopo la firma non è davvero un documento di scope.

Mi serve un documento di scope anche per automazioni molto piccole?

Sì, solo una versione breve. Il valore non è la lunghezza — è avere un elenco scritto di test di accettazione prima di iniziare a costruire, così che “finito” sia una checklist invece di una sensazione. Ho visto lavori piccoli e definiti in modo informale durare più a lungo di lavori grandi e definiti correttamente, esattamente per questo motivo.

A chi appartiene il documento di scope stesso — fa parte del deliverable?

Lo tratto come proprietà del cliente, a prescindere che proceda o meno con una build, dato che ha pagato per l’audit che lo ha prodotto. Ciò che trattengo è il template sottostante e il prompt, allo stesso modo in cui trattengo l’impalcatura riutilizzabile tra gli incarichi — la struttura del documento è mia, il contenuto compilato sulla loro specifica attività è loro.

Prossimi passi: Il mio corso AI Agents for Beginners copre la costruzione degli agenti che un documento di scope come questo descrive. Il programma cowork è per gli operatori che vogliono un ambiente strutturato per esercitarsi a definire l’ambito e a costruire questo tipo di lavoro. Se preferisci farti scrivere il documento di scope, prenota una sessione di 30 minuti.