Prompt e agenti

Come ottimizzare AGENTS.md

AGENTS.md deve dare all'agente le informazioni che servono davvero. Regole chiare, esempi mirati e niente documentazione duplicata aiutano sia il modello sia il consumo di token.

Un progetto di YADA Digital · Metodo e responsabilità editoriale

Scrivi ciò che serve per lavorare nel repository

AGENTS.md raccoglie istruzioni per gli agenti che lavorano nel progetto. La documentazione Codex descrive come vengono cercati e combinati i file di istruzioni lungo il percorso del repository. Non assumere che ogni agente adotti esattamente le stesse regole: controlla lo strumento effettivamente usato.

Il contenuto dovrebbe aiutare a compiere scelte concrete: comandi affidabili, organizzazione del codice, convenzioni non ovvie e limiti operativi. Un testo lungo non è automaticamente migliore. Se ripete documentazione facilmente consultabile senza aggiungere indicazioni, consuma attenzione e rende più difficile trovare le regole importanti. Inizia quindi osservando quali errori o esitazioni ricorrono davvero durante il lavoro sul progetto.

Organizza poche sezioni operative

Una struttura utile può comprendere avvio del progetto, validazione, architettura e convenzioni. Indica comandi eseguibili dalla directory corretta e specifica quando serve un ambiente virtuale. Evita istruzioni come «esegui i test nel modo consueto» se un nuovo collaboratore non può ricavarne un'azione concreta.

Per esempio, documenta il comando del controllo mirato e spiega quando è appropriato. Se una cartella usa regole diverse, valuta istruzioni locali secondo il comportamento supportato dall'agente. Mantieni al livello generale soltanto ciò che si applica davvero a tutto il progetto. Questa separazione riduce ripetizioni e aiuta a evitare che una convenzione specifica venga applicata a file per cui non ha senso.

Riduci duplicati e contraddizioni

Rileggi il file cercando regole ripetute con parole diverse. Uniscile in una formulazione chiara, conservando le eccezioni necessarie. Controlla che comandi e percorsi esistano ancora: una riga breve ma obsoleta può costare più tempo di una spiegazione corretta leggermente più lunga.

Quando rimandi a un documento, usa un riferimento preciso e indica in quale situazione leggerlo. Non sostituire ogni istruzione con una lista di link: l'agente deve comunque capire da dove iniziare. Distingui requisiti vincolanti da preferenze e rendi esplicite le condizioni. «Per una modifica al modello, verifica le migrazioni» è più utile di una richiesta indiscriminata che non distingue i tipi di intervento.

Verifica il comportamento dopo la revisione

Prima di adottare una versione più corta, conserva l'originale e confronta i token con le stesse impostazioni. Poi osserva un'attività rappresentativa: individuare una view, modificare un componente o eseguire un controllo proporzionato. Verifica che l'agente trovi i comandi e segua le regole essenziali.

Se continua a commettere un errore, aggiungi un'indicazione mirata invece di allungare tutte le sezioni. Mantieni il file vicino al codice e aggiornalo quando cambiano strumenti o struttura. Evita promesse di risparmio universali: l'effetto dipende da come l'agente carica le istruzioni e dal lavoro svolto. L'obiettivo è una guida operativa leggibile anche da una persona, che riduca dubbi e ricerche ripetute senza diventare un manuale duplicato.

Lo stesso italiano, due tokenizer

Conteggi locali del solo testo mostrato, senza messaggi di sistema, documento da riassumere o output. Non sono il conteggio ufficiale di tutti i modelli e non misurano la qualità della risposta.

Lo stesso italiano, due tokenizer
EsempioTesto esattocl100k_baseo200k_base
Istruzione originalePer favore, vorrei che tu mi aiutassi a riassumere il testo che trovi qui sotto. Ti chiedo di essere breve e conciso, di non dilungarti e di usare esattamente tre punti elenco. Non aggiungere informazioni che non sono presenti nel testo.6958
Istruzione rivistaRiassumi il testo seguente in tre punti elenco. Usa soltanto le informazioni presenti nel testo.2921
Accenti, numeri ed emojiCaffè, città e sostenibilità: l’AI legge anche accenti, numeri 123 ed emoji 🌱.3026

Misurato il 2026-10-11 con tiktoken 0.12.0 e encode_ordinary. La versione breve conserva compito e formato richiesto: verificarne l'efficacia sul documento reale resta necessario.

Per approfondire

Fonti e aggiornamenti

Questa guida si basa sulle fonti indicate. Consultale per un approfondimento!

Ultima verifica editoriale: .

Dalla teoria al tuo prompt.

Scopri quanto pesano le tue parole e sperimenta nuove idee.

Apri il contatore