Context library per agenti AI: come organizzare i file di contesto di un progetto

Chi lavora con un agente AI su un progetto finisce per scrivere file di istruzioni: convenzioni di codice, note sul design system, appunti su cosa non toccare. All'inizio sono due righe, dopo qualche mese sono una cartella che nessuno ricorda di aver scritto. Il 9 ottobre 2026 Nielsen Norman Group ha pubblicato, a firma di Tanner Kohler, "Context Libraries: How AI Power Users Manage Context Engineering", con osservazioni su come lo fanno gli utenti più esperti.

Lo studio non parla di front-end né di design. Parla di come si tiene in ordine il contesto di un agente, e per questo è applicabile a chi sviluppa o progetta con questi strumenti. Distinguo qui cosa dice l'articolo da cosa è una mia traduzione al lavoro sui repository.

Cos'è una context library

Secondo NN/g è una raccolta di conoscenza istituzionale e procedurale, contenuta in file markdown o in software esterni, che gli agenti possono leggere e modificare. Comprende anche fonti collegate tramite MCP o API, come database Notion, cronologie Slack o trascrizioni di riunioni. L'articolo distingue tre ruoli del contesto: globale, cioè le informazioni stabili valide in ogni interazione; locale, limitato a un compito o a un progetto; ambientale, cioè i flussi grezzi come email e trascrizioni da cui l'agente ricava ciò che gli serve. È la stessa distinzione dell'articolo NN/g del 18 settembre.

L'autore nota anche che i sistemi AI aiutano poco a imparare a costruire queste librerie: i partecipanti hanno imparato soprattutto da post su X e Reddit e provando.

Quattro osservazioni dallo studio

La prima riguarda la manutenzione. I file venivano scritti una volta e usati per mesi anche quando non corrispondevano più al modo di lavorare. Le automazioni programmate venivano ignorate senza che il sistema ricevesse un segnale, e i collegamenti esterni si interrompevano spesso: un partecipante ha parlato di "system decay". Una connessione Todoist, per esempio, scadeva di continuo e lasciava Claude senza accesso alla lista finché non veniva ricollegata a mano.

La seconda: quasi nessuno modificava i file a mano. Chiedere a Claude era più rapido e manteneva coerenti stile e struttura. Il rovescio è che gli utenti chiedevano modifiche ampie su molti file e raramente controllavano che cosa fosse cambiato, giudicando dalla qualità degli output successivi.

La terza riguarda la reperibilità. Molti non ritrovavano file importanti nelle proprie cartelle, e uno ha scoperto un file di contesto globale che influenzava molte azioni di Claude senza sapere che esistesse. Il livello di organizzazione variava molto, fino a un partecipante con oltre 2.700 file gerarchizzati. La raccomandazione è mettere in ogni cartella un file indice, chiamato CLAUDE.md nell'ecosistema Claude, che descriva contenuto e modo d'uso.

La quarta: dare all'agente solo il contesto che serve. Anche con finestre di contesto molto grandi, un contesto superfluo non migliora il risultato. Il sistema più elaborato osservato caricava il minimo indispensabile, perché la cartella da cui si avvia la sessione determina ciò che l'agente vede, con una regola citata dall'articolo: deve salire o scendere prima di potersi muovere di lato. Dove il contesto era troppo ampio si verificavano sconfinamenti: Claude confondeva il lavoro di due soci nelle comunicazioni ai clienti, e le linee guida di design di un podcast venivano applicate a un'altra app. La maggior parte dei partecipanti teneva i file sotto alcune centinaia di righe.

Come tradurlo in un progetto front-end

Quanto segue è una mia applicazione dei principi, non qualcosa che lo studio abbia testato. Un repository con design system e applicazione potrebbe avere questa forma:

/progetto
  CLAUDE.md            indice: cosa contiene il repository, dove trovare cosa
  /design-system
    CLAUDE.md          token, naming, regole sui componenti
  /app
    CLAUDE.md          convenzioni dell'applicazione, cosa non toccare
  /docs
    CLAUDE.md          decisioni passate e loro motivi

Il file alla radice fa da indice e rimanda agli altri. Ogni file locale parla solo della propria cartella, così le regole del design system non finiscono per condizionare il lavoro sull'app, che è lo sconfinamento descritto dallo studio. E ciascun file resta breve: se supera qualche centinaio di righe, probabilmente contiene due argomenti.

Per la manutenzione, l'articolo suggerisce di far verificare all'agente il contesto globale o locale alla luce del contesto ambientale recente, e di dare un feedback esplicito quando cambia il modo di lavorare, facendo aggiornare i file. Dopo un cambio di convenzioni, per esempio, ha senso chiedere un controllo di coerenza sui file di istruzioni. Quanto spesso farlo è una scelta tua: lo studio non indica una frequenza.

C'è poi il punto più scomodo. Se lasci che sia l'agente a riscrivere i file, ricordati che gli utenti osservati controllavano di rado le modifiche. Rivedere il diff di un file di istruzioni è un costo piccolo rispetto a scoprire tre settimane dopo che una regola è sparita.

Il tema si collega all'articolo NN/g sul "big ball of mud" nei sistemi agentici, di cui ho scritto il 5 ottobre: là il problema era la fragilità dei sistemi costruiti a pezzi, qui sono gli strumenti per tenere il contesto sotto controllo.

Cosa non dice lo studio

L'articolo non dichiara il numero dei partecipanti. I risultati sono qualitativi, basati su osservazioni e racconti, quindi non dicono quanto siano diffusi i comportamenti descritti. I partecipanti erano utenti esperti che usavano Claude ogni giorno; l'autore ritiene che anche utenti meno esperti incontreranno problemi simili, ma non lo verifica. Le tre indicazioni conclusive di Kohler (lasciare che l'agente mantenga la libreria, organizzarla con file indice, caricare solo ciò che serve) sono quindi un punto di partenza da provare sul proprio flusso, non una pratica validata.

Fonti

1. Nielsen Norman Group, Tanner Kohler, “Context Libraries: How AI Power Users Manage Context Engineering”, 9 ottobre 2026, consultata il 12 ottobre 2026
2. Nielsen Norman Group, “The New Big Ball of Mud”, 2 ottobre 2026