Progressive Disclosure: l'Architettura a Strati che Rivoluziona l'Efficienza di Claude Code con i file MD

Oggi utilizzare i file .md per impartire istruzioni specifche agli Agents Code (come Claude Code) è necessario per ottenere subito buoni risultati senza deteriorare la finestra di contesto.

Nel panorama dell'intelligenza artificiale applicata allo sviluppo software, una delle sfide più rilevanti riguarda la gestione ottimale della context window. Quando lavoriamo con sistemi come Claude Code, ogni token conta e l'efficienza nell'utilizzo del contesto disponibile determina non solo la qualità delle risposte, ma anche la sostenibilità economica e prestazionale dell'intero sistema. È in questo scenario che emerge il concetto di progressive disclosure, un'architettura intelligente che sta ridefinendo il modo in cui gli agenti AI accedono e processano le informazioni.

Il Problema della Context Window: un Collo di Bottiglia da Superare

Prima di addentrarci nell'architettura a progressive disclosure, è fondamentale comprendere la natura del problema che questa metodologia risolve. La context window rappresenta la quantità massima di informazioni che un modello linguistico può elaborare in un singolo momento. Per quanto avanzati siano i modelli come Claude, questa finestra rimane limitata e preziosa.

Immaginate di dover consultare un'intera enciclopedia per rispondere a una semplice domanda: carichereste tutti i volumi contemporaneamente o cerchereste prima nell'indice generale? La risposta è ovvia, ma tradizionalmente molti sistemi AI hanno seguito proprio l'approccio "enciclopedico", caricando nella context window enormi quantità di documentazione, skill e reference, indipendentemente dalla loro effettiva rilevanza per il task specifico.

Questa inefficienza si traduce in tre problematiche concrete:

1. Saturazione prematura della context window con informazioni irrilevanti
2. Aumento dei costi computazionali e dei tempi di risposta
3. Potenziale degradazione della qualità delle risposte per "rumore informativo"

Progressive Disclosure: un Indice a Strati per l'Intelligenza Artificiale

L'architettura a progressive disclosure rappresenta un cambio di paradigma radicale. Anziché caricare tutto il contenuto disponibile, il sistema opera attraverso livelli progressivi di dettaglio, rivelando informazioni solo quando effettivamente necessarie.

Il Primo Strato: Frontmatter e Metadata

Quando Claude Code riceve un nuovo task, la prima operazione non consiste nel caricare intere skill o documentazioni, bensì nell'analizzare esclusivamente il frontmatter dei file .md disponibili. Questo frontmatter contiene metadati essenziali:

---
name: "Form Validation"
description: "Gestione avanzata della validazione form con React Hook Form e Zod"
category: "frontend"
tags: ["forms", "validation", "react"]
---

Questa operazione costa pochissimi token, tipicamente tra 10 e 30 per skill, permettendo a Claude di scansionare rapidamente decine di skill diverse senza impattare significativamente sulla context window. È l'equivalente di sfogliare l'indice di un libro prima di decidere quale capitolo leggere.

Il Secondo Strato: SKILL.md e Quadro Generale

Una volta identificate le skill potenzialmente rilevanti attraverso il frontmatter, Claude procede al caricamento del file SKILL.md principale. Questo documento fornisce:

# Form Validation Skill

## Obiettivo
Implementare sistemi di validazione form robusti e user-friendly

## Principi Guida
- Validazione client-side e server-side
- Feedback immediato all'utente
- Schema-based validation con Zod

## Struttura
- forms.md: Pattern e componenti form
- validation.md: Logiche di validazione avanzate
- error-handling.md: Gestione errori UX

Il file SKILL.md agisce come una mappa concettuale, offrendo il quadro generale senza entrare nei dettagli implementativi. Permette a Claude di comprendere l'architettura complessiva della skill, le regole base e i principi fondamentali, consentendogli di prendere decisioni informate su quali approfondimenti specifici potrebbero essere necessari.

Il Terzo Strato: Reference Specifici On-Demand

Solo a questo punto, se il task lo richiede esplicitamente, Claude carica i file di reference specifici. Se il compito riguarda la creazione di un form di registrazione, verrà caricato forms.md. Se invece si tratta di implementare logiche di validazione complesse, sarà validation.md a essere consultato.

Questo approccio garantisce che la context window contenga esclusivamente informazioni direttamente applicabili al task corrente, massimizzando l'efficienza e la pertinenza delle risposte generate.

I Vantaggi Concreti dell'Architettura a Strati

Efficienza della Context Window

Il beneficio più immediato riguarda l'utilizzo ottimale dello spazio contestuale disponibile. In uno scenario tradizionale, caricare 10 skill complete potrebbe consumare 50.000-100.000 token. Con progressive disclosure, la stessa operazione di discovery richiede appena 200-500 token per il frontmatter scanning, più 2.000-5.000 token per i SKILL.md rilevanti, lasciando ampio spazio per il contenuto effettivamente necessario.

Scalabilità del Sistema

Man mano che la knowledge base di un agente AI cresce, l'architettura tradizionale diventa rapidamente insostenibile. Con 50 o 100 skill disponibili, caricare tutto preventivamente sarebbe impossibile. La progressive disclosure permette invece di scalare quasi linearmente, poiché il costo del discovery rimane contenuto indipendentemente dal numero totale di skill disponibili.

Riduzione dei Costi Operativi

Considerando che i modelli AI avanzati hanno costi proporzionali ai token processati, l'ottimizzazione della context window si traduce direttamente in risparmi economici significativi, specialmente su volumi elevati di richieste.

Miglioramento della Qualità delle Risposte

Contro-intuitivamente, meno informazioni possono generare risposte migliori. Eliminando il "rumore" rappresentato da documentazione irrilevante, Claude può concentrarsi esclusivamente sugli elementi pertinenti al task, producendo output più focalizzati e precisi.

Implementazione Pratica: Organizzazione dei File

L'efficacia della progressive disclosure dipende fortemente dalla struttura organizzativa dei file. Ecco un esempio di architettura ottimale:

skills/
├── frontend/
│   ├── forms/
│   │   ├── SKILL.md          # Quadro generale
│   │   ├── forms.md          # Pattern form
│   │   ├── validation.md     # Validazione
│   │   └── error-handling.md # Gestione errori
│   ├── state-management/
│   │   ├── SKILL.md
│   │   └── ...
├── backend/
│   ├── api-design/
│   │   ├── SKILL.md
│   │   └── ...

Ogni directory rappresenta una skill autonoma, con il file SKILL.md come entry point e i file di reference come approfondimenti modulari.

Best Practices per Frontmatter Efficaci

La qualità del frontmatter determina l'efficacia dell'intero sistema. Ecco le caratteristiche di un frontmatter ottimale:

---
name: "API Authentication & Authorization"
description: "Implementazione sistemi auth JWT, OAuth2, gestione permessi RBAC"
category: "backend"
tags: ["auth", "security", "jwt", "oauth"]
complexity: "intermediate"
related: ["api-design", "security-best-practices"]
---

Elementi chiave:

1. Name conciso ma descrittivo: deve immediatamente comunicare l'ambito della skill
2. Description ricca di keyword: facilita il matching semantico con i task
3. Tag specifici: permettono filtraggio rapido per tecnologie o pattern
4. Metadata strutturati: complexity e related aiutano Claude a contestualizzare

Il Flusso di Esecuzione: un Esempio Concreto

Vediamo come opera Claude Code con progressive disclosure in uno scenario reale:

Task ricevuto: "Crea un form di login con validazione email e password, gestione errori user-friendly"

Fase 1: Frontmatter Scanning

Claude analizza i frontmatter di tutte le skill disponibili (costo: ~300 token per 30 skill). Identifica come rilevanti:

# forms/SKILL.md frontmatter
name: "Form Validation"
description: "Gestione form con validazione"

# auth/SKILL.md frontmatter
name: "Authentication Patterns"
description: "Pattern login, registrazione, recupero password"

Fase 2: Caricamento SKILL.md

Carica i file SKILL.md delle due skill identificate (costo: ~3.000 token). Comprende che:

• Per il form serve consultare forms/forms.md e forms/validation.md
• Per il contesto auth serve auth/login-patterns.md

Fase 3: Reference Specifici

Carica solo i tre file di reference identificati (costo: ~6.000 token). A questo punto ha tutto il necessario per generare la soluzione, avendo consumato circa 9.300 token invece dei 50.000+ che sarebbero stati necessari caricando tutto preventivamente.

Considerazioni Architetturali Avanzate

Caching Intelligente

Una volta caricato un file di reference, questo potrebbe rimanere in cache per task successivi correlati, ottimizzando ulteriormente l'efficienza. Claude Code può implementare strategie di caching basate sulla probabilità che un reference rimanga rilevante per le prossime operazioni.

Dependency Resolution

Alcune skill dipendono concettualmente da altre. Il file SKILL.md può dichiarare queste dipendenze attraverso il campo related, permettendo a Claude di caricare preventivamente reference che saranno quasi certamente necessari.

---
name: "Advanced Form Patterns"
related: ["form-validation", "state-management"]
requires: ["form-validation"]  # Dipendenza obbligatoria
---

Adaptive Loading

Sistemi più sofisticati potrebbero implementare strategie di caricamento adattivo, dove Claude impara dall'esperienza quali reference tendono a essere necessari insieme, ottimizzando proattivamente il caricamento.

Limitazioni e Criticità da Considerare

Come ogni architettura, anche la progressive disclosure presenta alcune sfide:

Latency Aggiuntiva

Il caricamento progressivo introduce potenzialmente latenze aggiuntive, poiché il contenuto viene recuperato in più fasi. In contesti dove la velocità è critica, potrebbe essere necessario bilanciare disclosure progressiva con pre-loading strategico.

Complessità di Manutenzione

Mantenere frontmatter accurati e descrizioni sempre aggiornate richiede disciplina. Un frontmatter obsoleto può portare Claude a ignorare skill rilevanti o caricare quelle sbagliate.

Over-Segmentazione

Esiste il rischio di frammentare eccessivamente la conoscenza, creando troppi file piccoli che complicano la gestione complessiva. Trovare il giusto livello di granularità è un'arte.

Un Cambio di Paradigma Necessario

L'architettura a progressive disclosure non è semplicemente un'ottimizzazione tecnica, ma rappresenta un cambio fondamentale nel modo in cui concepiamo la relazione tra agenti AI e knowledge base. Proprio come gli esseri umani non memorizzano intere enciclopedie ma sviluppano strategie per accedere efficacemente alle informazioni quando necessario, così i sistemi AI devono evolversi verso approcci più intelligenti e selettivi.

Per chi sviluppa con Claude Code o altri agent-based systems, adottare questa architettura significa non solo risparmiare token e costi, ma costruire sistemi intrinsecamente più scalabili, manutenibili e performanti. È un investimento in un'infrastruttura che cresce in modo sostenibile con l'espansione della knowledge base.

La progressive disclosure ci insegna una lezione fondamentale: nell'intelligenza artificiale come nella vita, non sempre più informazione equivale a migliore comprensione. A volte, la vera intelligenza sta nel sapere cosa ignorare e quando cercare di più.