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.
| Esempio | Testo esatto | cl100k_base | o200k_base |
|---|---|---|---|
| Istruzione originale | Per 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. | 69 | 58 |
| Istruzione rivista | Riassumi il testo seguente in tre punti elenco. Usa soltanto le informazioni presenti nel testo. | 29 | 21 |
| Accenti, numeri ed emoji | Caffè, città e sostenibilità: l’AI legge anche accenti, numeri 123 ed emoji 🌱. | 30 | 26 |
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: .