Un assistente basato sull’intelligenza artificiale diventa realmente utile quando smette di comportarsi in modo generico e comincia a rispettare il metodo di lavoro dell’utente.
Il primo impulso è spesso quello di inserire ogni nuova regola nello stesso file: controlli, autorizzazioni, procedure tecniche, convenzioni dei progetti, gestione della memoria e istruzioni per utilizzare strumenti specifici.
All’inizio funziona. Con il tempo, però, il file cresce fino a diventare difficile da mantenere. L’agente riceve istruzioni che non riguardano il compito corrente, aumenta il rischio di contraddizioni e una parte del contesto disponibile viene occupata da informazioni inutili in quel momento.
La soluzione non consiste nell’eliminare le regole, ma nell’organizzarle su livelli differenti.
Nel precedente articolo, AGENTS.md: la costituzione operativa dell’intelligenza artificiale, abbiamo visto come utilizzare AGENTS.md per definire principi, limiti e modalità di lavoro.
Il passo successivo è trasformarlo nel punto di ingresso di un’architettura modulare, capace di richiamare procedure specialistiche soltanto quando servono: i playbook.
AGENTS.md deve stabilire le regole, non contenere ogni procedura operativa
Possiamo considerare AGENTS.md come una costituzione operativa: definisce principi, limiti e responsabilità. I playbook svolgono invece la funzione di manuali specializzati, consultati soltanto quando l’attività lo richiede.
AGENTS.md dovrebbe stabilire regole trasversali come:
- sicurezza e protezione dei dati;
- operazioni consentite in sola lettura;
- attività che richiedono una conferma;
- gestione delle fonti;
- separazione tra fatti, ipotesi e raccomandazioni;
- metodo da applicare prima di modificare file, database o infrastrutture;
- gerarchia tra le diverse istruzioni;
- criteri generali di verifica.
Non dovrebbe invece descrivere nel dettaglio come avviare un database, verificare un’applicazione, analizzare uno schema Oracle o produrre uno specifico report.
Queste procedure appartengono a documenti specializzati: i playbook.
AGENTS.mdstabilisce i confini e indica quale procedura utilizzare. Il playbook spiega come eseguire quella particolare attività.
Un’architettura organizzata su più livelli
Una possibile organizzazione è la seguente:
Richiesta dell’utente
↓
AGENTS.md globale
Regole comuni, sicurezza e autorizzazioni
↓
AGENTS.md del progetto
Convenzioni, vincoli e riferimenti locali
↓
Selezione del playbook pertinente
↓
Procedura operativa specializzata
↓
Esecuzione e verifica
↓
Memoria del progetto
Stato, decisioni, risultati e problemi apertiOgni livello assume una responsabilità differente.
| Componente | Responsabilità |
|---|---|
| Richiesta dell’utente | Definisce l’obiettivo corrente e il risultato desiderato |
AGENTS.md globale | Stabilisce regole comuni, sicurezza, autorizzazioni e metodo |
AGENTS.md locale | Specializza le regole per un determinato progetto |
| Playbook | Descrive una procedura operativa specifica |
| Memoria | Registra ciò che è stato fatto e lo stato raggiunto |
| Skill | Rende una procedura riutilizzabile e può includere istruzioni, risorse e script |
La documentazione di Codex indica che i file AGENTS.md vengono individuati a partire dalla configurazione globale e proseguendo dalla radice del repository fino alla directory di lavoro corrente. Le istruzioni vengono applicate in ordine, permettendo ai livelli più vicini al progetto di specializzare quelli generali.
Questa separazione impedisce che regole, procedure e informazioni storiche vengano confuse tra loro.
Che cos’è un playbook
Nel nostro metodo di lavoro, un playbook è un documento operativo consultato soltanto quando la richiesta appartiene al suo campo di applicazione.
Può contenere:
- scopo e perimetro;
- condizioni che ne determinano l’utilizzo;
- prerequisiti;
- controlli preliminari;
- fonti da consultare;
- sequenza delle operazioni;
- comandi e strumenti ammessi;
- risultati attesi;
- verifiche finali;
- rischi conosciuti;
- modalità di ripristino;
- condizioni che impongono di fermarsi;
- informazioni da registrare nella memoria.
Il termine “playbook” descrive quindi una scelta organizzativa. Non indica necessariamente una funzione nativa dell’agente.
Quando una procedura diventa strutturata, riutilizzabile e corredata da script, modelli o altre risorse, può essere formalizzata come una skill.
Una skill è infatti un insieme modulare di istruzioni organizzato attorno a un file SKILL.md. Può includere materiali di riferimento, script ripetibili, modelli e altre risorse necessarie per eseguire un determinato processo.
Un esempio reale: avviare una VM Oracle e verificare ORDS
Consideriamo una richiesta utilizzata realmente nel nostro ambiente di lavoro:
“Avvia la VM Oracle e verifica che ORDS sia disponibile.”
Per svolgere correttamente questa attività occorre conoscere diversi elementi:
- come individuare la macchina virtuale;
- come controllare se è già attiva;
- quanto attendere per il completamento dell’avvio;
- come verificare il sistema operativo;
- come controllare il listener Oracle;
- come verificare il database e il pluggable database;
- come rilevare lo stato di ORDS;
- quale indirizzo utilizzare per il controllo finale;
- cosa fare quando un componente non risponde;
- quali operazioni richiedono una nuova autorizzazione.
Potremmo inserire tutto nel file AGENTS.md globale. In questo modo, però, la procedura verrebbe caricata anche durante attività completamente diverse, come l’analisi di un documento o la preparazione di un foglio elettronico.
Abbiamo quindi adottato una separazione più semplice.
Nell’AGENTS.md rimane soltanto una regola di instradamento:
Prima di operare sulla VM Oracle, su ORDS o sull’ambiente
Oracle locale, consulta e applica il playbook dedicato.Il playbook contiene invece la procedura specializzata:
1. Verificare lo stato corrente della VM.
2. Non eseguire un secondo avvio se la VM è già attiva.
3. Attendere il completamento del sistema operativo.
4. Controllare listener, database e pluggable database.
5. Verificare lo stato di ORDS.
6. Avviare soltanto i componenti necessari e autorizzati.
7. Controllare l’indirizzo finale.
8. Riportare separatamente fatti, anomalie e azioni eseguite.L’agente non deve ricevere ogni volta l’intera procedura. Deve sapere dove trovarla e quando utilizzarla.
Dal comando alla verifica finale
Il flusso operativo diventa:
Richiesta dell’utente
↓
Riconoscimento dell’ambito VM/ORDS
↓
Consultazione del playbook specializzato
↓
Verifica dello stato reale dell’ambiente
↓
Esecuzione delle sole azioni autorizzate
↓
Controllo del risultato finale
↓
Registrazione delle informazioni rilevantiQuesto permette di mantenere separati tre momenti:
- la decisione su cosa deve essere fatto;
- la procedura che stabilisce come farlo;
- la verifica che dimostra cosa è realmente accaduto.
Il playbook non concede nuove autorizzazioni
Questo è uno dei principi più importanti.
Il playbook spiega come eseguire un’attività, ma non può autorizzare automaticamente qualsiasi operazione collegata.
Nel caso della VM:
- controllare lo stato può essere un’operazione di sola lettura;
- l’avvio può essere consentito da un comando esplicito;
- uno spegnimento forzato richiede un’autorizzazione specifica;
- creare uno snapshot costituisce un’operazione distinta;
- modificare la configurazione della VM richiede una decisione separata;
- eliminare una macchina virtuale non può essere considerato una conseguenza implicita del playbook.
La procedura specializza il metodo, ma non amplia il perimetro autorizzato.
Una frase inserita in un manuale operativo non dovrebbe mai trasformarsi in un’autorizzazione nascosta.
Playbook e memoria non sono la stessa cosa
La distinzione è fondamentale:
Il playbook indica come lavorare. La memoria indica dove siamo arrivati.
Nel playbook dell’ambiente Oracle troviamo la procedura da seguire per verificare e avviare VM, database e ORDS.
Nella memoria del progetto registriamo invece:
- stato rilevato dei componenti;
- operazioni effettivamente eseguite;
- risultati delle verifiche;
- anomalie riscontrate;
- decisioni prese;
- attività ancora da completare.
Il playbook deve rimanere una procedura stabile e riutilizzabile. La memoria cambia nel tempo perché rappresenta lo stato conosciuto dell’ambiente.
Mescolare queste informazioni produrrebbe un documento composto contemporaneamente da regole, istruzioni, cronologia e stato operativo. Dopo pochi aggiornamenti sarebbe difficile capire quali indicazioni siano ancora valide.
Perché non conviene caricare sempre tutto
Le istruzioni hanno un costo operativo, anche quando non producono direttamente un costo economico facilmente misurabile.
Ogni documento letto:
- occupa una parte del contesto disponibile;
- richiede tempo di elaborazione;
- può introdurre regole non pertinenti;
- può entrare in conflitto con altre istruzioni;
- aumenta la quantità di informazioni che l’agente deve interpretare.
OpenAI suggerisce un principio chiamato progressive disclosure: fornire inizialmente soltanto le indicazioni necessarie per individuare la procedura corretta e caricare i dettagli quando diventano realmente pertinenti.
In pratica, il documento principale dovrebbe funzionare come un indice intelligente, non come un’enciclopedia da leggere integralmente prima di ogni attività.
OpenAI raccomanda inoltre di mantenere brevi e precise le descrizioni delle skill e di evitare di obbligare l’agente a leggere intere raccolte di documenti prima di ogni modifica.
Come scrivere un buon richiamo al playbook
Un riferimento troppo generico rischia di attivare il playbook nel momento sbagliato.
Una formulazione come questa:
Consulta il playbook del database per tutte le attività tecniche.lascia troppo spazio all’interpretazione.
È preferibile specificare:
Consulta il playbook dell’ambiente Oracle prima di avviare
o arrestare la VM, verificare database e listener, operare
su ORDS o modificare la configurazione dell’ambiente locale.Un buon richiamo dovrebbe indicare almeno:
- quando si applica;
- a quali attività si riferisce;
- dove si trova il playbook;
- quali operazioni non autorizza;
- quale regola prevale in caso di conflitto.
Il percorso deve essere chiaro, ma il contenuto del playbook non deve essere duplicato nell’AGENTS.md.
Cosa dovrebbe contenere un buon playbook
Un playbook efficace dovrebbe rispondere ad alcune domande precise.
Quando deve essere utilizzato?
Il campo di applicazione deve essere riconoscibile senza ambiguità.
Quali informazioni servono?
Devono essere indicati prerequisiti, configurazioni, documenti e fonti necessarie.
Quali controlli precedono l’azione?
Prima di modificare qualcosa occorre verificare lo stato corrente ed evitare operazioni duplicate o incompatibili.
Cosa può essere eseguito automaticamente?
Le attività di sola lettura devono essere distinte dalle operazioni che modificano lo stato.
Quando bisogna chiedere conferma?
Le autorizzazioni devono essere visibili e non dedotte da indicazioni generiche.
Come viene verificato il risultato?
Un comando eseguito senza errori non dimostra necessariamente che l’obiettivo sia stato raggiunto.
Quando bisogna fermarsi?
Errori, evidenze contraddittorie, assenza di prerequisiti e rischio di danni devono determinare condizioni di arresto esplicite.
Cosa deve essere memorizzato?
Devono essere registrati soltanto risultati, decisioni e informazioni utili alle attività successive.
I vantaggi dell’architettura modulare
La combinazione tra AGENTS.md e playbook produce diversi vantaggi.
Minore occupazione del contesto
L’agente consulta soltanto le istruzioni pertinenti alla richiesta corrente.
Maggiore precisione
Ogni playbook può contenere controlli specifici per una tecnologia o un processo.
Manutenzione più semplice
Una procedura può essere aggiornata senza modificare tutte le regole globali.
Riduzione dei conflitti
Separare gli ambiti limita la possibilità che istruzioni relative ad attività differenti interferiscano tra loro.
Riutilizzo
Lo stesso playbook può essere richiamato da più progetti che condividono una procedura.
Tracciabilità
Diventa più semplice ricostruire quale regola o procedura abbia determinato una decisione dell’agente.
Evoluzione progressiva
Una procedura può nascere come semplice documento, diventare un playbook consolidato e successivamente essere formalizzata come una skill dotata di script e risorse.
I rischi da evitare
Anche una struttura modulare può essere progettata male.
I problemi più comuni sono:
- duplicare la stessa regola in più documenti;
- creare richiami troppo generici;
- mantenere playbook non aggiornati;
- nascondere autorizzazioni operative nelle procedure;
- costruire catene troppo lunghe di documenti collegati;
- conservare password o credenziali nei file di istruzioni;
- confondere regole, procedure e memoria;
- caricare tutti i playbook per sicurezza, annullando il vantaggio della modularità;
- permettere a una regola locale di indebolire un vincolo globale.
Ogni playbook dovrebbe avere un ambito riconoscibile e una responsabilità precisa.
Se due documenti descrivono la stessa procedura, probabilmente la separazione deve essere rivista.
Una checklist per collocare una nuova istruzione
Prima di aggiungere una regola possiamo porci alcune domande.
La regola vale per qualsiasi progetto?
Probabilmente appartiene all’AGENTS.md globale.
Vale soltanto per un determinato progetto?
Può essere inserita nell’AGENTS.md locale.
Descrive una procedura composta da più passaggi?
È una buona candidata per un playbook.
Serve insieme a script, modelli o risorse riutilizzabili?
Potrebbe essere formalizzata come una skill.
Descrive una decisione presa o lo stato raggiunto?
Appartiene alla memoria del progetto.
Autorizza un’azione esterna o potenzialmente rischiosa?
Non dovrebbe essere nascosta in un playbook: occorre una regola esplicita e, quando necessario, la conferma dell’utente.
Non servono più istruzioni, ma istruzioni meglio organizzate
La specializzazione di un agente non dipende soltanto dalla quantità di informazioni che gli forniamo.
Dipende dalla capacità di stabilire:
- quali regole devono essere sempre disponibili;
- quali valgono soltanto per un progetto;
- quali procedure devono essere caricate su richiesta;
- quali informazioni descrivono lo stato corrente;
- quali decisioni devono rimanere sotto il controllo dell’utente.
AGENTS.md diventa così il punto di governo del sistema. I playbook ne ampliano le capacità senza trasformarlo in un documento monolitico.
Specializzare un agente non significa riempirlo di istruzioni. Significa insegnargli a individuare e applicare la procedura giusta nel momento giusto.
Fonti consultate
- OpenAI, “Model guidance – Using agents.md”, consultato il 24 settembre 2026: documentazione ufficiale.
- OpenAI, “Skills”, consultato il 24 settembre 2026: documentazione ufficiale.
- Eric Provencher, “Rethinking skills and prompts for GPT-6 Astra”, OpenAI Developers, 11 settembre 2026, consultato il 24 settembre 2026: articolo ufficiale.
- ELCARO, “AGENTS.md: la costituzione operativa dell’intelligenza artificiale”, consultato il 24 settembre 2026: articolo precedente.
Nessun commento:
Posta un commento