Agentic coding: perché AGENTS.md va tenuto snello

Se state usando agentic coding seriamente, una delle prime cose da fare non è scrivere più istruzioni possibili dentro AGENTS.md o CLAUDE.md.

È fare esattamente il contrario: tenere quei file il più possibile snelli.

Lo vedo spesso: repository dove dentro finisce di tutto. Policy, convenzioni, workflow, dettagli di dominio, istruzioni operative, note ovvie, struttura del database, eccezioni, naming, checklist.

Il problema non è la buona volontà. Il problema è l'effetto sul modello.

Saturare la context window non aiuta

Quando metti tutto in un unico file guida, non stai aiutando l'agente. Gli stai saturando la context window.

Lo costringi a processare continuamente informazioni che magari non servono per quel task specifico. Aumenti rumore, consumo di token e, spesso, peggiori anche la qualità delle decisioni.

L'agente non distingue automaticamente cosa è fondamentale e cosa è rumore di fondo. Legge quello che gli passi. Se gli passi tutto, ogni volta, il segnale si diluisce.

Nel coding agentico la qualità non dipende solo dal modello che usi. Dipende da quanto bene progetti il contesto in cui quel modello lavora.

E spesso meno contesto fisso significa più precisione, perché ha meno rumore da filtrare.

Indice operativo, non manuale completo

AGENTS.md e CLAUDE.md vanno trattati più come un indice operativo che come un manuale completo.

Le regole fondamentali restano lì: scopo del progetto, tono, vincoli non negoziabili, dove trovare il resto.

Tutto il resto va distribuito.

Non perché le altre informazioni non contano. Perché devono comparire quando servono, non sempre.

Rules: vincoli e principi

Le rules (nel senso di Cursor, o equivalenti nel tuo stack) servono a definire vincoli e principi stabili.

Esempi tipici:

• come si modella il database
• convenzioni API
• naming e struttura delle cartelle
• sicurezza e segreti
• migrazioni
• governance documentale

Sono regole che vuoi rispettate in modo coerente, spesso trasversali a più task. Ma anche qui vale la regola del minimo necessario: una rule per concetto, non un romanzo.

Skills: procedure operative riutilizzabili

Le skills diventano procedure operative riutilizzabili, attivabili quando il task lo richiede.

Ad esempio:

• come creare un endpoint
• come fare una migration in modo AI-safe
• come aggiornare un workflow esistente
• come aprire una PR seguendo il processo del team

Qui l'LLM non deve leggere tutto sempre. Deve capire cosa gli serve, quando gli serve, e recuperare solo il contesto utile.

È una differenza enorme rispetto al mega-file unico.

Cosa cambia nella pratica

Quando progetti bene il contesto:

1. Task mirati — l'agente parte con poche regole globali e carica skill o documenti solo se il lavoro lo richiede.
2. Meno allucinazioni da overload — meno contraddizioni tra sezioni scritte in momenti diversi nello stesso file mastodontico.
3. Manutenzione più semplice — aggiorni la skill sulla migration senza toccare venti paragrafi sparsi in AGENTS.md.
4. Onboarding umano migliore — anche per chi non usa l'agente, la struttura resta leggibile.

Il rischio opposto è l'under-documentation: file snelli ma vuoti, senza puntatori. L'indice deve dire dove andare, non pretendere di essere l'unica fonte.

Un esempio concreto

In un progetto web potresti lasciare in AGENTS.md:

• scopo del sito e tono
• stack in una riga
• comandi build/lint
• link mentali: rules per DB/API, skill per deploy o per aggiungere un post blog

Fuori da lì: la checklist pre-PR, lo schema del database, la procedura per una migration, le convenzioni di copy bilingue.

L'agente che aggiunge un campo al DB non ha bisogno della policy sul tono del footer. Quello che scrive copy sì, ma non ha bisogno dello schema completo delle migrazioni.

Separare non è pedanteria. È rispetto per la finestra di contesto.

In chiusura

Agentic coding non è avere il modello più grande o il file di istruzioni più lungo.

È progettare un sistema in cui il modello riceve poco, pertinente e al momento giusto.

Snellire AGENTS.md non significa fare meno disciplina. Significa smettere di usare un unico file come contenitore di tutto e iniziare a trattare il contesto come una risorsa da comporre.

Più indice, meno enciclopedia. Più precisione, meno rumore.