[AI] - AGENTS.md: la costituzione operativa di un’intelligenza artificiale

Al momento sto utilizzando come strumento Codex con una AI 5.6-Sol, all'interno di Codex esiste un file globale AGENTS.md nel quale occorre inserire le istruzioni personali che regolano il modo in cui l’AI deve lavorare con i vari progetti su cui e' coinvolta.

La versione attuale, che ho creato, è composta da circa 720 righe, organizzate in 11 sezioni. 

Non aumenta l’intelligenza del modello e non gli assegna nuove capacità tecniche: stabilisce invece 
"come devono essere utilizzate le capacità disponibili".

In pratica, il file trasforma un’AI genericamente collaborativa in un assistente con un metodo di lavoro preciso, limiti operativi, procedure di memoria, comandi riconoscibili e regole per l’utilizzo di eventuali strumenti operativi.

• Che effetto produce un AGENTS.md su un’AI

Un modello linguistico tende naturalmente a generare la risposta che considera più plausibile rispetto alla richiesta ricevuta. Senza indicazioni operative dettagliate potrebbe:

• interpretare liberamente il perimetro dell’incarico;
• formulare ipotesi non verificate;
• proporre rapidamente una modifica plausibile;
• procedere per tentativi successivi;
• dimenticare lo stato delle sessioni precedenti;
• modificare più elementi contemporaneamente;
• confondere ciò che può leggere con ciò che è autorizzato a modificare.

Il file AGENTS.md interviene proprio su questi punti. 

Introduce un percorso decisionale simile al seguente:

Richiesta → classificazione → riallineamento → evidenze → causa → autorizzazione → modifica minima → verifica → memoria

Questa è la caratteristica più importante del file: 

• non contiene soltanto divieti, ma definisce un vero processo operativo.

1. Fonte globale e ambito

La prima sezione stabilisce quale sia il file globale di riferimento e chiarisce la differenza tra:

• regole globali personali;
• regole locali dei singoli progetti;
• file presenti nelle cache di Codex o dei plugin, che non devono essere modificati.

Stabilisce inoltre che le mie richieste siano considerate normalmente lavorative. 

L’AI deve quindi presumere che una domanda sia collegata al progetto in cui sta lavorando, salvo quando è chiaramente personale o generale.

Per esempio:

• una domanda su Oracle, APEX, un file o un errore viene considerata lavorativa;
• una domanda sui semi di ciliegio viene riconosciuta come estranea al progetto e non provoca il riallineamento del workspace;
• se il workspace contiene più progetti e non è possibile identificare quello giusto, l’AI deve chiedere quale utilizzare.

• Effetto sull’AI

Questa sezione riduce due rischi opposti:

• ignorare il contesto progettuale quando serve;
• perdere tempo leggendo un progetto durante una conversazione personale.

Valutazione

È una regola ben calibrata rispetto al fatto che circa il 99% delle richieste è lavorativo. Rimane un piccolo margine di ambiguità per domande tecniche generali che potrebbero o meno riguardare il progetto.

2. Regole prioritarie non negoziabili

Questa è la parte più importante del nuovo file. Raccoglie all’inizio i principi che prima erano distribuiti in punti differenti.

Le regole principali impongono all’AI di:

• identificare il progetto corretto;
• distinguere lettura e modifica;
• chiedere conferma prima delle operazioni invasive;
• procedere soltanto sulla base di evidenze;
• applicare una modifica minima per volta;
• dichiarare rischi e possibilità di ripristino;
• fermarsi quando le informazioni sono insufficienti;
• non mescolare progetti indipendenti;
• rispettare esattamente il perimetro delle autorizzazioni.

• Effetto sull’AI

Questa sezione funziona come una gerarchia interna. Se una procedura secondaria è ambigua, l’AI deve tornare a questi principi.

La collocazione all’inizio aumenta la probabilità che vengano applicati durante tutto il lavoro.

Valutazione

È una sezione molto forte perché contiene istruzioni verificabili. Non dice genericamente “lavora bene”, ma indica comportamenti osservabili.

3. Diagnosi obbligatoria basata sulle evidenze

La regola centrale è:

Evidenza → causa → modifica → verifica

Prima di intervenire, l’AI deve:

1. descrivere il problema;
2. distinguere comportamento atteso ed effettivo;
3. raccogliere log, errori, configurazioni, metadati e differenze;
4. confrontare il caso difettoso con uno funzionante;
5. collegare l’ipotesi alle evidenze;
6. indicare la modifica minima e la verifica prevista.

Sono espressamente vietate:

• modifiche basate su supposizioni;
• correzioni “a occhio”;
• approssimazioni successive;
• modifiche multiple senza isolamento della causa;
• presentazione di un’ipotesi come fatto accertato.

Un esperimento diagnostico rimane possibile, ma deve essere controllato, reversibile e modificare una sola variabile.

• Confronto con il caso funzionante

La sezione contiene una regola specifica per i casi in cui una pagina, uno script o una configurazione funzionino correttamente in un punto del progetto.

In quella situazione l’AI deve confrontare oggettivamente:

• file;
• metadati;
• CSS e JavaScript;
• SQL;
• configurazioni;
• componenti APEX;
• template, regioni, item, pulsanti e processi.

L’obiettivo è replicare il blocco funzionante con i soli adattamenti indispensabili.

• Effetto sull’AI

Questa parte limita il comportamento più costoso di un assistente tecnico: proporre una sequenza di correzioni plausibili senza aver prima individuato la causa.

Obbliga inoltre l’AI a rendere visibile il proprio percorso operativo. Prima della modifica devono comparire:

• evidenza;
• causa o ipotesi;
• modifica proposta;
• risultato atteso;
• verifica;
• rischi e ripristino.

Valutazione

È probabilmente la regola più potente dell’intero file. 

Non può eliminare matematicamente ogni errore, ma rende immediatamente riconoscibile una modifica non sufficientemente giustificata.

4. Letture, scritture e autorizzazioni

Questa sezione distingue nettamente tra verifiche e operazioni invasive.

L’AI può eseguire autonomamente:

• letture di file;
• ricerche testuali;
• consultazione di log;
• interrogazioni SQL in sola lettura;
• verifiche di stato;
• consultazione delle sessioni Codex.

Deve invece chiedere conferma prima di:

• modificare o creare file;
• cancellare contenuti;
• effettuare deploy;
• modificare il database;
• cambiare lo stato di sistemi o applicazioni;
• eseguire operazioni rischiose.

Viene anche definito il significato delle risposte:

• “sì” autorizza una sola operazione specifica;
• “no” blocca l’operazione;
• “sì e non chiedere altre conferme” vale soltanto per il perimetro dichiarato.

• Effetto sull’AI

Questa regola riduce il rischio che una richiesta venga interpretata in maniera più ampia del necessario.

Una diagnosi non diventa automaticamente un’autorizzazione alla correzione. 

Una richiesta di controllo non autorizza un deploy. Un consenso per un file non autorizza modifiche ad altri file.

Valutazione

È molto efficace perché delimita sia le azioni sia il significato dell’autorizzazione.

5. Riallineamento della memoria

Questa sezione stabilisce come ricostruire il contesto di un progetto all’inizio di una sessione lavorativa.

L’AI deve cercare:

• MEMORIA_LAVORO*.md;
• STATO_PROGETTO.md;
• eventuali AGENTS.md locali;
• README, documentazione e manifest;
• sessioni Codex recenti associate al progetto.

Deve concentrarsi sulle sessioni più recenti, in particolare quelle di oggi, ieri e degli ultimi dieci giorni, fermandosi quando dispone di un quadro operativo sufficiente.

Non deve riportare intere conversazioni, ma estrarre:

• richieste;
• decisioni;
• file modificati;
• backup;
• test;
• punti chiusi;
• problemi aperti;
• prossime azioni.

Il riallineamento completo non deve essere ripetuto a ogni messaggio. Viene aggiornato solo se cambia progetto, se lo stato può essere cambiato esternamente oppure se lo richiedi.

• Effetto sull’AI

Un modello non possiede automaticamente una memoria affidabile e illimitata delle sessioni precedenti. Questa procedura sostituisce la memoria implicita con una ricostruzione documentata.

Riduce il rischio di:

• ripetere attività già concluse;
• utilizzare una versione superata;
• dimenticare problemi aperti;
• confondere due progetti;
• ignorare backup o test già effettuati.

Valutazione

È molto utile nei progetti lunghi. Il limite è il costo in tempo e contesto quando le sessioni sono numerose, ma il criterio di lettura selettiva riduce il problema.

---

6. Memoria di lavoro, stato progetto e nome della chat

Il file distingue due tipi di memoria:

• MEMORIA_LAVORO_<timestamp>.md, utilizzata come storico dettagliato;
• STATO_PROGETTO.md, utilizzato come fotografia sintetica dello stato corrente.

Definisce quando questi file possono essere creati o aggiornati e quale struttura deve avere STATO_PROGETTO.md.

Regola inoltre:

• resoconti di fine sessione;
• checkpoint intermedi;
• proposta del titolo della chat;
• convenzione dei tag;
• formato semplificato con il simbolo 📌.

• Effetto sull’AI

Questa sezione trasforma le informazioni di una conversazione in documentazione riutilizzabile. Evita che lo stato del progetto dipenda soltanto dalla memoria temporanea della chat.

Valutazione

È una buona disciplina documentale. 

La qualità finale dipende comunque dall’accuratezza con cui vengono sintetizzati i fatti.

---

7. Contesto e checkpoint

La sezione disciplina la quantità di contesto utilizzata durante una sessione.

L’AI deve:

• fornire il valore preciso, quando disponibile;
• dichiarare quando utilizza una stima;
• indicare il residuo e il rischio di saturazione;
• creare un checkpoint progettuale intorno al 70%;
• proporre ulteriori precauzioni all’85%;
• suggerire il cambio di chat intorno al 95%.

Il checkpoint automatico è consentito soltanto quando il progetto è identificato e c’è uno stato significativo da salvare. Non deve essere creato durante conversazioni personali.

• Effetto sull’AI

Questa regola riduce il rischio che una sessione molto lunga perda informazioni importanti a causa della saturazione del contesto.

• Limite reale

Il modello non dispone sempre di una misura precisa del contesto utilizzato. In quei casi la percentuale è una stima e può anticipare o ritardare il checkpoint.

Valutazione

Il principio è molto utile, ma dipende da un’informazione che non sempre è misurabile con precisione.

---

8. Comandi standard

Il file contiene 31 formule riconoscibili, comprese varianti e richiami testuali.

Questi comandi trasformano frasi naturali in procedure definite. Alcuni esempi riguardano:

• riallineamento della memoria;
• riepilogo dell’ultima sessione;
• modalità di sola verifica;
• checkpoint;
• aggiornamento dello stato progetto;
• freeze e controllo watchdog;
• piano operativo;
• percentuale di contesto;
• accensione, spegnimento, snapshot e backup della VM;
• stampa;
• aggiornamento delle regole;
• arresto e riepilogo dell’attività.

Alcuni comandi includono già un’autorizzazione limitata. 

Per esempio, un comando di checkpoint autorizza la creazione del solo file di memoria, non altre modifiche.

• Effetto sull’AI

I comandi standard riducono l’ambiguità. Una frase breve richiama un comportamento complesso già definito e ne delimita le autorizzazioni.

Valutazione

Sono molto efficaci perché associano un’espressione precisa a una procedura e a un perimetro autorizzativo. Il possibile limite è rappresentato da formulazioni molto diverse da quelle previste, anche se diverse varianti sono già contemplate.

---

9. Gestione dei blocchi

Quando un’elaborazione dura troppo o non produce avanzamento, l’AI deve fermarsi e indicare:

• attività in corso;
• lavoro completato;
• lavoro mancante;
• causa probabile del blocco;
• alternative;
• decisione richiesta all’utente.

La stessa regola si applica quando un comando rimane bloccato e il controllo ritorna successivamente.

• Effetto sull’AI

Evita che l’assistente continui indefinitamente a consumare tempo senza produrre un risultato verificabile.

Valutazione

La regola è chiara. 

Il limite è che un tool completamente bloccato potrebbe impedire all’AI di comunicare fino alla restituzione del controllo.

---

10. Utilizzo di una Infrastruttura: esempio VM Oracle condivisa

Questa sezione rimane globale perché la Virtual Machine e il suo contenuto vengono utilizzati trasversalmente da più progetti.

Contiene:

• identificazione della VM corretta;
• esclusione di vecchie VM non utilizzate;
• accensione e spegnimento ordinato;
• verifica dello stato;
• backup OVA;
• comportamento in caso di dischi o snapshot problematici;
• uso di Guest Additions;
• gestione di software interno alla VM;
• versione Java obbligatoria;
• controlli sulle porta es: 8080;
• credenziali locali necessarie.
• ecc.

Le password non devono essere riportate nei riepiloghi, se non strettamente necessario.

• Effetto sull’AI

Questa sezione fornisce una procedura operativa molto specifica. Riduce il rischio di:

• utilizzare la VM sbagliata;
• avviare software con una versione Java incompatibile;
• creare processi duplicati;
• spegnere la VM in modo scorretto;
• produrre backup incompleti;
• utilizzare percorsi obsoleti.

Valutazione operativa

È dettagliata e contiene risultati attesi e verifiche.

Valutazione di sicurezza

Le credenziali locali in chiaro aumentano l’autonomia operativa, ma entrano nel contesto di ogni sessione che carica il file globale. La scelta è comprensibile perché la VM è condivisa; rimane comunque il punto di sicurezza più delicato.

---

11. Fine dell’elaborazione

L’ultima regola impone di concludere ogni elaborazione con la frase:

• ho terminato

• Effetto sull’AI

Fornisce un segnale esplicito che distingue una risposta conclusiva da un aggiornamento intermedio.

Valutazione

È una regola semplice e facilmente verificabile, ma non influenza direttamente la qualità tecnica del lavoro.

---

Quanto è potente il file attuale?

La “potenza” di un file di istruzioni non dipende dalla quantità di testo, ma da quattro caratteristiche:

1. chiarezza;
2. priorità;
3. verificabilità;
4. delimitazione delle azioni.

Il file attuale soddisfa bene tutti e quattro i criteri.

Area	Valutazione
Diagnosi basata sulle evidenze	9,5/10
Sicurezza delle modifiche	9/10
Autorizzazioni	9/10
Comandi standard	9/10
Gestione della VM	9/10
Riallineamento della memoria	8,5/10
Gestione dei blocchi	8,5/10
Documentazione del progetto	8/10
Gestione del contesto	7,5/10
Protezione delle credenziali	6,5/10

Il file è quindi potente e molto più rigoroso di un normale insieme di istruzioni personali.

Perché non può garantire il 100%

Anche regole molto forti non possono produrre una garanzia assoluta, perché:

• un modello linguistico può interpretare male una situazione;
• due istruzioni possono entrare in conflitto;
• le istruzioni di sistema e della piattaforma hanno priorità superiore;
• alcune informazioni possono essere incomplete;
• un tool può fallire o restituire risultati ambigui;
• la percentuale del contesto può essere soltanto stimata;
• la presenza di una regola non sostituisce la verifica del risultato.

La forza reale del file sta però nella possibilità di riconoscere immediatamente una deviazione. 

Se l’AI modifica qualcosa senza mostrare evidenza, causa e verifica, il comportamento viola una regola esplicita e verificabile.

Giudizio conclusivo

L’attuale AGENTS.md non è soltanto un elenco di preferenze. 

È un sistema di governo operativo dell’AI.

I suoi punti più forti sono:

• diagnosi prima dell’intervento;
• autorizzazioni limitate;
• modifica minima;
• confronto con casi funzionanti;
• memoria documentata;
• comandi standard;
• gestione dettagliata della VM;
• arresto in caso di blocco.

I punti relativamente più deboli sono:

• credenziali locali presenti nel contesto globale;
• stima non sempre precisa della saturazione;
• dimensione ancora considerevole del file;
• inevitabile possibilità di interpretazione errata da parte del modello.

Nel complesso, il file è oggi coerente, severo e operativamente forte. 

Non rende l’AI infallibile, ma la costringe a lavorare con un metodo molto più vicino a quello di un tecnico controllato e verificabile rispetto a quello di un semplice generatore di risposte.

Qui sotto trovate un esempio del file AGENTS.md con path utilizzati come esempio, logicamente nel caso in cui qualcuno volesse utilizzarlo dovrebbe eliminare quello che per il suo progetto e' superfluo... ma non le regole.

• Al momento non posso caricare il file finale Agents.md, ma nel caso vi servisse contattatemi e vi sara' dato