Italiano
La scorsa settimana ho letto di un'intelligenza artificiale che ha progettato un vaccino in grado di combattere coronavirus che non abbiamo ancora incontrato (ScienceDaily). Cambridge ha condotto il primo trial umano e 39 volontari hanno ricevuto l'antigene.
È pazzesco pensare che un algoritmo abbia analizzato l'intera famiglia genetica di un virus e abbia progettato una protezione contro ceppi che circolano ancora negli animali e aspettano di fare il salto. Ma quando chiedo al mio agente di recuperare il mio ultimo brief da un elenco di documenti, impiega quasi due minuti ad aprire i file sbagliati nel mio vault solo per mostrarmi un brief di tre mesi fa.
E so che Cambridge usa un'IA addestrata su misura, ma quello che voglio mostrarti è che il divario tra ciò che l'IA può fare e ciò che una configurazione le permette di fare è ciò che determina il successo o il fallimento del tuo flusso di lavoro e della tua produttività.
Non ho mai costruito un'impalcatura di proposito, fino a poco tempo fa. Si è accumulata intorno all'agente per caso, cartella dopo cartella, finché l'agente ha perso la strada in un caos che avevo creato per me stesso.
Così ho passato un giorno a cronometrare ogni fallimento, ed è emerso uno schema. In questo numero ti mostro perché il tuo agente continua a inciampare sulle cose facili mentre il mondo lo considera un genio, e la soluzione che lo rimette dalla tua parte.
In questo articolo:
- La struttura delle cartelle ha fatto fallire il mio agente perché le mie cartelle erano organizzate per come penso io, non per come naviga un agente
- Un singolo file indice alla radice di ogni cartella principale ha trasformato ricerche lente in letture di trenta secondi
- L'impalcatura invisibile intorno al tuo agente è più importante della capacità dell'agente stesso, ed ecco come costruirla
- Un test diagnostico che puoi eseguire in cinque minuti per vedere se la struttura delle tue cartelle è il vero problema
La Struttura Che Il Tuo Agente Non Vede
Ho organizzato il mio vault come fanno la maggior parte delle persone. Articoli, ricerche, risorse, documenti strategici, ognuno aveva la sua cartella. Quella struttura sembrava pulita perché io penso per tipi di contenuto. Le cartelle rispecchiano le mie categorie e non penso mai a dove guardare. Le bozze sono articoli, gli appunti sono ricerche, il sistema di archiviazione funziona in automatico.
Ma un agente non pensa per categorie. Quando chiedo a Hermes di pianificare il lancio di un prodotto, l'attività attinge da appunti strategici, linee guida del brand e lanci precedenti sparsi in cartelle diverse.
Quei pezzi di contesto vivono in posti diversi nella mia struttura per tipi di contenuto. Il mio agente deve cercare ovunque ogni volta, senza sapere quale bozza è corrente e quale è archiviata, o quale nota di ricerca è di questo mese rispetto a sei mesi fa.
L'organizzazione per tipi di contenuto funziona perfettamente per gli umani. Hai passato tutta la vita a archiviare cose sotto categorie, e il tuo cervello fa i collegamenti incrociati automaticamente. È naturale aspettarsi che l'IA funzioni allo stesso modo, quando in realtà un agente deve fare quei collegamenti manualmente, ed è lì che la struttura si rompe.
La struttura intorno al tuo agente fa più lavoro della capacità dell'agente stesso.
Una volta visto lo schema, la causa era ovvia: avevo costruito il mio vault per un cervello umano che ricorda dove stanno le cose, poi l'ho passato a un agente che deve cercare da capo ogni volta, e questo ha esposto il vero problema sotto il caos delle cartelle.
Un cercatore ha bisogno di una mappa, perché senza di essa l'agente cammina nel buio e tratta ogni file come se potesse essere la risposta.
Cosa Spreca La Capacità
Hermes continuava ad aprire un mucchio di file prima di atterrare su quello giusto, o a prendere una versione archiviata quando il file corrente era da un'altra parte. Peggio ancora, chiedeva quale file usare quando la risposta sarebbe dovuta essere ovvia dal contesto. Questo è successo con ogni modello che ho usato, incluso Opus, GPT 5.5, Qwen e GLM.
Lo schema si ripeteva continuamente, ed ero bloccato a guardare le stesse lente ricerche svolgersi compito dopo compito.
Anche se il mio agente era abbastanza capace da trovare le cose, la struttura delle cartelle era diventata il principale collo di bottiglia prima ancora che arrivasse al lavoro vero.
Ho raggiunto il punto di rottura il giorno in cui ho cronometrato i fallimenti. Ho tracciato quanti file Hermes apriva prima di raggiungere quello giusto e quanto tempo ci metteva per arrivarci. Cinque attività comuni si presentavano così prima che cambiassi qualcosa.
Prima che cambiassi qualcosa:
- Trovare il brief dell'articolo corrente: 7 file aperti, 2:00 per il file corretto;
- Trovare le definizioni dei colori del brand: 5 file aperti, ci sono voluti 1:12;
- Cercare la coda degli articoli per la pianificazione: 4 file aperti, ci sono voluti 0:48;
- Trovare articoli precedenti sullo stesso argomento: 6 file aperti, ci sono voluti 1:36;
- Estrarre la strategia di promozione per un lancio: 3 file aperti, ci sono voluti 0:34.
Esperimento approssimativo, quindi prendi i numeri esatti come indicativi.
Ogni attività attraversava più cartelle. La maggior parte apriva versioni archiviate prima di trovare quelle attive. Il mio agente stava bruciando capacità nella navigazione invece di fare il suo lavoro. Un piano di lancio necessitava di tre file che vivevano in tre cartelle diverse, e l'ho visto fare tre tentativi sbagliati prima di atterrare su quelli giusti.
Un agente che scrive articoli, programma e pianifica non dovrebbe passare la maggior parte del tempo a cercare cose.
La Gabbia Più Piccola Che Funziona
Una cartella per area di competenza, numerata per ordine, con un INDEX.md alla radice che mappa tutto. Questa è l'intera soluzione, e i dettagli vivono in tre regole che funzionano insieme.
INDEX.md alla radice di ogni cartella principale è una mappa. Elenca ogni sottocartella e file canonico, più da dove dovrebbe iniziare il mio agente. Il mio agente legge questo prima e sa cosa c'è dentro prima di toccare qualsiasi altra cosa. Pensalo come un cancello di approvazione morbido in cui all'agente non è permesso iniziare a lavorare finché non sa con cosa sta lavorando.
La struttura della mia cartella brand appare così dopo la riorganizzazione.
105.Brand/2├── INDEX.md3├── 01.Brand System/4├── 02.Editorial Strategy/5├── 03.Promotion/6├── 04.Public Deliverables/7├── 05.Operating Plan/8└── 06.Archived/
Questa struttura organizza per area di competenza invece che per tipo di contenuto. Ogni area di competenza ha la sua cartella, quindi il lavoro del brand rimane con il lavoro del brand e la strategia rimane con la strategia. Il mio agente non attraversa i confini cercando qualcosa che non appartiene lì.
I numeri sulle cartelle rendono l'ordine di lettura esplicito invece di affidarsi all'ordinamento alfabetico. 01. Brand System viene letto prima di 02. Editorial Strategy. Il mio agente non indovina. I numeri dentro le cartelle fanno lo stesso per i file, quindi il mio agente sa che 01. Articles è il punto di partenza prima di 02. Previous Articles.
Antepongo i nomi delle cartelle con un numero perché è più facile da ricordare anche per me.
Ecco come il mio stack Hermes completo da $30 riesce a muoversi facilmente attraverso dozzine di cartelle senza che il mio agente si perda mai.
Le cose archiviate vivono in 06.Archived, dove vanno ad aspettare vecchi brief e piani ritirati. Il mio agente sa di non guardare lì a meno che non gli chieda specificamente un contesto storico. Quella separazione è ciò che mantiene pulite le cartelle attive e veloci le ricerche.
Una volta che al mio agente è stato detto di non attraversare quel confine per impostazione predefinita, ogni attività all'interno delle cartelle attive è diventata più veloce.
Il mio INDEX.md si presenta così.
1# Brand Index23Questa cartella contiene il sistema brand corrente.45## Mappa Cartelle67| Cartella | Scopo | Aggiornato |8|---|---|---:|9| `01.Brand System/` | Identità visiva, ambito tematico, tono di voce | 2026-06-11 |10| `02.Editorial Strategy/` | Direzione articoli, regole titoli, coda | 2026-06-11 |11| `03.Promotion/` | Strategia di lancio, distribuzione, strumenti | 2026-06-11 |1213## File Canonici1415| File | Scopo |16|---|---|17| `01.Brand System/01. Brand System.md` | Identità visiva, colori, tipografia |18| `02.Editorial Strategy/01. Articles.md` | Coda articoli, regole titoli |1920## Dove Andare2122- Inizia con `01.Brand System/04. Direction.md` per la missione23- Usa `02.Editorial Strategy/01. Articles.md` per la selezione degli articoli
INDEX.md ha attraversato tre versioni. La mia prima versione elencava ogni singolo file dentro la cartella brand e arrivava a quaranta righe. Era tecnicamente completo ma il mio agente doveva analizzarlo ogni volta e la lunghezza era un sovraccarico. La mia seconda versione era troppo corta, circa quindici righe, e il mio agente faceva ancora domande a cui non avevo risposto. Questa terza versione elenca solo le sottocartelle e i file canonici, con una breve sezione "Dove Andare" che dice al mio agente i suoi punti di partenza.
Quando chiedo al mio agente di estrarre la strategia di promozione per un lancio, legge 05.Brand/INDEX.md, apre 03.Promotion/01. Promotion Strategy.md e si mette al lavoro. I tempi dopo la riorganizzazione sono questi.
Dopo la riorganizzazione:
- Trovare il brief dell'articolo corrente: 1 file aperto, 0:10
- Trovare le definizioni dei colori del brand: 3 file aperti, 0:22
- Cercare la coda degli articoli per la pianificazione: 1 file aperto, 0:10
- Trovare articoli precedenti sullo stesso argomento: 2 file aperti, 0:18
- Estrarre la strategia di promozione per un lancio: 1 file aperto, 0:12
L'attività più lenta è passata da 2 minuti a 26 secondi, e le esecuzioni più veloci si attestavano intorno ai 10 secondi. Il mio agente apre l'INDEX.md, segue il punto di partenza di cui ha bisogno e si mette al lavoro senza vagare. Nessuna capacità è cambiata dal lato del mio agente. La struttura delle cartelle ha smesso di sprecarne la maggior parte prima ancora che l'attività iniziasse.
La struttura delle cartelle è una gabbia che ho costruito e che vincola come si muove il mio agente senza vincolare ciò che il mio agente può fare. Dentro la gabbia, il mio agente si muove liberamente. Senza, Hermes tende ad allontanarsi e io devo sprecare tempo a indicargli il file giusto.
Passare a Hermes mi ha permesso di costruire quel tipo di sistema attraverso file, provider e memoria tutto in una volta, e il pattern INDEX.md è il pezzo più piccolo che ha fatto la differenza più grande giorno per giorno.
Ogni Gabbia Ha Una Serratura
Il mio primo errore è stato aggiungere INDEX.md a ogni sottocartella. Troppe mappe significano che il mio agente passa il tempo a leggere indici invece di fare lavoro. Tengo INDEX.md solo alla radice delle cartelle principali come Brand e Editorial Strategy, dove ci sono abbastanza sottocartelle per aver bisogno di una mappa. Dentro una piccola sottocartella con quattro o cinque file, Hermes naviga direttamente senza alcuna mappa.
Tieni presente che la numerazione diventa noiosa quando aggiungi nuove cartelle. Devo decidere dove si inserisce una nuova cartella nella sequenza, e a volte la aggiungo alla fine invece di rinumerare tutto. Va bene. I numeri non devono essere perfetti finché sono indicativi. Le cartelle perfettamente ordinate non sono l'obiettivo, e trattarle come tali trasforma una soluzione pratica in un progetto estetico.
Un errore più grande è costruire una struttura prima che il tuo agente mostri alcuna confusione. La maggior parte delle persone progetta in modo eccessivo la configurazione del proprio agente perché pensa di aver bisogno di un'infrastruttura adeguata.
La mia regola attuale segue lo stesso principio alla base della scelta tra MCP, CLI o il proprio strumento. Usa l'interfaccia più piccola che fa il lavoro. Aggiungi struttura solo quando il tuo agente si perde, e aggiungi solo abbastanza struttura per risolvere quel problema specifico.
Un altro fallimento che ho incontrato è stato annidare la struttura dentro la struttura. Ho aggiunto sottocartelle dentro sottocartelle per categorizzare tutto perfettamente, il che ha trasformato una gerarchia a due livelli in una a cinque livelli. Il mio agente doveva quindi leggere più file INDEX e analizzare più sequenze numeriche per raggiungere un singolo file. Ho collassato quei livelli extra in sottocartelle piatte e la navigazione è tornata a essere veloce.
La profondità è nemica della ricerca rapida dei file, e la maggior parte delle riorganizzazioni aggiunge profondità pensando che sia precisione.
Misura Prima Di Riorganizzare
Prima di toccare una singola cartella, esegui questo test su tre attività reali che il tuo agente gestisce più spesso. Cronometra ciascuna e nota quanti file apre prima di trovare quello giusto. Tieni traccia di quante volte prende il file sbagliato o si ferma a chiederti quale usare.
Qualsiasi attività che richiede al tuo agente più di trenta secondi o apre tre o più file sbagliati indica una cartella dietro quell'attività che è rotta.
Scegli il fallimento che si verifica più spesso. Apri quella cartella e scrivi un INDEX.md che elenca ogni sottocartella e file importante, più da dove dovrebbe iniziare il tuo agente. Salvalo. Esegui di nuovo la stessa attività.
Se il tuo agente trova il file giusto in meno di trenta secondi, la soluzione ha funzionato e ora conosci lo schema. Applicalo alla prossima cartella rotta. Se fallisce ancora, il problema è probabilmente la numerazione o una cartella per area di competenza, e queste sono le prossime due cose da sistemare.
Inizia con la cartella che spreca più tempo, sistemala, e passa alla successiva solo quando sei pronto.
Dove Le Sbarre Ancora Cedono
Il contenuto archiviato viene ancora consultato a volte quando ho bisogno di un vecchio brief per contesto. Il mio agente deve sapere di guardare in 06.Archived invece che nelle cartelle attive, e lo menziono nell'INDEX.md in modo che sappia dove vive il materiale storico. Senza quella nota, il mio agente presume che il contenuto archiviato non esista.
Inoltre, Obsidian Sync crea problemi occasionali quando non si aggiorna correttamente tra i dispositivi. Se aggiorno un file sul mio laptop ma la versione più vecchia è ancora sul mio VPS, Hermes carica la copia del VPS e la tratta come la fonte di verità corrente. Questo è più un problema di sincronizzazione che un problema di struttura delle cartelle, ma si manifesta all'interno del sistema di cartelle perché l'agente vede solo i file che ha di fronte.
La numerazione si rompe quando hai così tante cartelle che la sequenza diventa senza significato. Oltre dieci o dodici elementi numerati a un livello, i numeri iniziano a essere arbitrari.
Cerco di mantenere le categorie principali al di sotto di quella soglia e di annidare la struttura più profonda all'interno invece di espandere il livello superiore.
Rinominare è un'altra fonte di attrito. Quando riorganizzo, a volte rinomino le cartelle per far corrispondere meglio il loro scopo, e qualsiasi riferimento INDEX.md al vecchio nome si rompe finché non lo aggiorno. Ora cerco di impostare i nomi delle cartelle una volta e lasciarli stare, perché un nome leggermente scomodo è più economico di un riferimento rotto.
Questa struttura funziona meglio per flussi di lavoro incentrati sui contenuti e su quelli di pianificazione. Le configurazioni puramente di codice o pesanti sui dati potrebbero aver bisogno di principi di organizzazione completamente diversi, e il pattern INDEX.md non risolve ogni problema di navigazione.
Tutto ciò che ho scritto in questo articolo riconduce a un unico istinto. Possiedi il livello che conta. Ho costruito il mio stack in modo che nessuna azienda controlli i miei strumenti. Ho costruito il mio vault in modo che nessun caos controlli il mio agente. Stesso principio dai provider alle cartelle a qualunque cosa verrà dopo.
La capacità è a buon mercato quando l'impalcatura intorno è rotta. Costruisci l'impalcatura, e la capacità si prende cura di sé. Un file indice e qualche numero davanti ai nomi delle tue cartelle è la differenza tra un agente che vaga e un agente che funziona.
Se questo è stato utile - segui @wandermist per altri contenuti come questo!
