Un secondo cervello in Claude Code: come crearne la struttura in un’ora

Documentazione di riferimento di Ailoot: ailoot.ai/docs/.

Perché Claude Code ha bisogno di un secondo cervello e cosa è essenziale?#

Martedì apri Claude Code. Spieghi: questo è il progetto, questo è il pubblico, questo non farlo. Lavorate insieme. Giovedì c’è una nuova chat e devi spiegare tutto da capo.

Se hai un CLAUDE.md, hai risolto il primo livello di frustrazione. Le regole di base e la descrizione del progetto sono raccolte in un unico file che viene caricato a ogni sessione. Ho spiegato come funziona questo file nella mia guida a CLAUDE.md: puoi leggerla prima per gettare le basi.

Ma CLAUDE.md è un manuale di istruzioni per un nuovo dipendente. Come vestirsi, quale tono usare con i clienti, quali comandi usare per pubblicare. Non basta per prendere buone decisioni sul progetto. Per decidere servono conoscenze: cos’è il prodotto, chi è il pubblico, come funziona l’economia, cosa hai provato e cosa non ha funzionato.

Nell’esperienza dell’autore descritta qui, quelle conoscenze vivevano in quattro posti: nella sua testa, nelle chat di Telegram, nei documenti Google e nella testa dei dipendenti. Un mese dopo una decisione, nessuno ricordava perché fosse stata presa. Una persona appena arrivata passava un’ora a fare domande al team per aggiornarsi. Claude era del tutto escluso da quel contesto.

Prima di creare il secondo cervello, nell’esperienza descritta dall’autore ogni sessione significava spiegare di nuovo chi fosse il cliente, come fosse strutturata l’offerta e quale fornitore gestisse i pagamenti. Con business/, apro una chat e dico: «aggiorna l’offerta per il nuovo piano tariffario»: Claude va da solo in business/company/legal.md, legge i requisiti, poi passa a business/products/pricing.md, vede il nuovo piano tariffario e propone una modifica in un solo passaggio. Non serve più ripartire da zero: il contesto si carica automaticamente.

Nel suo blog di ingegneria, Anthropic chiama questo problema «degrado del contesto»:

In altre parole, più informazioni inserisci nella finestra, peggiore diventa la capacità dell’agente di lavorare sui dettagli. La soluzione è mantenere una struttura di file esterni che Claude possa consultare autonomamente in risposta a una richiesta specifica. Questo è un secondo cervello.

Cos’è un secondo cervello e come si applica a Claude?#

In genere, un secondo cervello riguarda la produttività: si crea un vault di Obsidian e vi si aggiungono estratti di libri, appunti delle chiamate e idee per i progetti.

Quando l’autore ha applicato questa idea al lavoro con Claude Code, ha smesso di essere una questione di produttività ed è diventata una questione di architettura degli agenti.

Nel secondo cervello classico, il secondo cervello è tuo e vi accedi manualmente. Quando lavori con Claude Code, il secondo cervello diventa bidirezionale: vi accedono sia tu sia l’agente. Questo cambia i requisiti del formato.

Dato che l’agente vi accede autonomamente, i file devono essere in un formato che possa comprendere senza un’integrazione separata. Markdown è ideale: testo, gerarchia di titoli e collegamenti tra file. Notion e Google Docs non sono adatti. Puoi collegarli tramite MCP, ma questo aggiunge un altro livello, un altro token a ogni richiesta e un altro possibile punto di errore.

Poiché i file si trovano nel file system accanto al progetto, rientrano automaticamente nella portata di Claude Code. Non serve configurare nulla. Avvia l’agente nella cartella del progetto e potrà vedere tutti i file al suo interno. È gratuito e funziona subito.

Quale gerarchia della memoria ha Claude Code già integrata?#

Prima di aggiungere qualcosa di tuo, vediamo cosa Claude può ricordare senza il tuo aiuto. Anthropic descrive due meccanismi nella sua documentazione ufficiale: CLAUDE.md (regole che scrivi tu) e la memoria automatica (lezioni che Claude scrive da sé). Entrambi vengono caricati all’inizio di ogni sessione.

CLAUDE.md viene cercato contemporaneamente in quattro posizioni:

Tutti e quattro i file vengono caricati nel contesto. Più specifico è il livello, maggiore è la sua priorità. Il file locale viene letto per ultimo, quindi le sue regole prevalgono su tutte le altre.

Un file CLAUDE.md può trovarsi anche in qualsiasi cartella interna al progetto. Quando Claude legge un file da una sottocartella, carica su richiesta il CLAUDE.md di quella sottocartella. È utile in un monorepo: le regole del frontend si trovano in frontend/CLAUDE.md, quelle del backend in backend/CLAUDE.md e vengono caricate solo quando l’agente lavora sulla parte corrispondente.

La memoria automatica è stata introdotta in Claude Code 2.1.59. Si tratta di file che Claude scrive su di te:

~/.claude/projects/<project-name>/memory/
├── MEMORY.md          # Indice, caricato a ogni sessione (200 righe o 25KB)
├── debugging.md       # Note dettagliate (caricate su richiesta)
├── api-conventions.md
└── ...

Anthropic la descrive così nella documentazione ufficiale:

La memoria automatica si attiva con il flag autoMemoryEnabled in ~/.claude/settings.json. Claude decide cosa scriverci. Puoi leggere MEMORY.md e modificarlo manualmente: è un normale file Markdown.

CLAUDE.md o secondo cervello: dove tracciare il confine?#

Ecco l’analogia che uso nei miei interventi: immagina di aver assunto un nuovo dipendente. Cosa gli dai il primo giorno?

Un manuale di istruzioni: come vestirsi, quando arrivare, quale tono usare con i clienti, quale sistema usare per pubblicare. È un documento breve. Non spiega cosa fai né perché. Dice semplicemente come comportarsi.

E, separatamente, l’accesso alla wiki aziendale. Spiega cos’è il prodotto, a chi si rivolge, chi è il pubblico, qual è il prezzo e perché, chi sono i concorrenti e quali errori hai commesso. È un archivio esteso. Nessuno lo legge tutto: ci vai per trovare una risposta specifica.

CLAUDE.md = manuale di istruzioni. Secondo cervello = wiki. Servono entrambi.

La distinzione è semplice. Metti in CLAUDE.md tutto ciò che è pertinente a ogni attività:

• Chi è l’agente in questo progetto (collaboratore, responsabile, assistente)
• In quale lingua rispondere
• Stack di strumenti
• Comandi di pubblicazione
• Divieti (non usare i trattini lunghi, non eseguire git push --force)
• Instradamento: dove cercare il contesto aziendale e dove trovare i principi

Metti nel secondo cervello tutto ciò che è necessario solo su richiesta:

• Il prodotto, il pubblico, l’economia e gli obiettivi
• Concorrenti e mercato
• Decisioni passate e relative motivazioni
• Esempi e recensioni dei clienti
• Principi e metodologia

Anthropic traccia la stessa distinzione nella documentazione:

Le skills sono un modo per archiviare conoscenze episodiche. Un’altra possibilità è una cartella business/ accanto al progetto. Io uso entrambe e le spiegherò più in dettaglio qui sotto.

Da cosa è composto il cervello del progetto: 5 parti più una macchina del tempo#

Un esempio di architettura tratto dall’esperienza descritta dall’autore:

Il punto metodologico fondamentale è separare ai-clone/ da business/.

business/ risponde alla domanda «di cosa ci occupiamo?». Prodotto, pubblico, prezzi, concorrenti. Riguarda il progetto. Se domani affidi il progetto a un partner, questa cartella va con il progetto.

ai-clone/ risponde alla domanda «come prendo le decisioni?». I miei principi, il mio tono, il mio mestiere e le parole da evitare. Riguarda me. Se domani inizio un nuovo progetto, questa cartella viene con me.

Vuoi non solo configurare una seconda cartella, ma anche creare un sistema che renda Claude coerente? Non basta da solo. Senza ai-clone/, l’agente risponde per tutti, non per te. Senza ingegneria del contesto, vaga per tutta la cartella e consuma token. È utile collegare tutte e tre le cose: secondo cervello + clone IA + ingegneria del contesto. Sono i tre pilastri senza i quali l’IA ha allucinazioni.

Cosa va messo in business/ e cosa no?#

La struttura di primo livello di business/ nel progetto descritto dall’autore:

business/
├── INDEX.md              ← mappa della cartella, da leggere per prima
├── company/              ← missione, persona giuridica, valori, politiche legali
├── products/             ← prodotti, programmi, prezzi
├── audience/              ← profilo cliente, segmenti, obiezioni
├── goals/                ← obiettivi annuali, trimestrali e mensili, metriche
├── economics/            ← unit economics, entrate, uscite, previsioni
├── marketing/             ← canali, funnel, materiali, concorrenti
├── execution/            ← pianificazione settimanale, backlog
└── assets/               ← sistema di design, recensioni, archivio di testi

È un esempio tratto dal progetto descritto dall’autore, non un dogma. Creo cartelle quando servono. Ho iniziato con tre (products/, audience/, goals/); le altre sono state aggiunte dopo 2-3 mesi, quando non era più chiaro dove mettere le nuove cose.

Il file principale della cartella è INDEX.md. È una mappa. Contiene una tabella «domanda → file» che Claude usa per capire dove andare. Senza, l’agente spreca token leggendo tutti i file in sequenza.

Un estratto di esempio da INDEX.md:

### Dove trovare le informazioni

| Cosa ti serve | Dove cercare |
|---|---|
| Chi è il nostro cliente e quali problemi affronta | `business/audience/avatar.md` |
| Prodotti, piani e prezzi | `business/products/` |
| Obiettivi e metriche | `business/goals/` |
| Economia (entrate, uscite, unit economics) | `business/economics/` |
| Canali e materiali promozionali | `business/marketing/` |

È sufficiente aggiungere una riga in CLAUDE.md: «Per le domande aziendali, leggi business/INDEX.md e segui la mappa». L’agente non carica l’intera cartella nel contesto. Carica la mappa, seleziona il file giusto e legge solo quello.

Lista di controllo di cosa non mettere in business/:

• Corrispondenza grezza delle chat senza elaborazione. Se c’è un’intuizione, elaborala e annotala. Se no, lasciala fuori.
• Informazioni già presenti nel codice. Non serve scrivere «I pagamenti passano da CloudPayments»: l’agente può vederlo nel codice.
• Screenshot e immagini. Aumentano le dimensioni della cartella e un modello testuale non li analizza senza un passaggio aggiuntivo.
• Numeri dinamici. «Oggi ci sono 423 pagamenti per il prodotto» sarà obsoleto tra una settimana. Usa il marcatore LIVE e un collegamento a una query del database.
• Informazioni sensibili o discutibili. Se domani il repository venisse mostrato su YouTube davanti a 100 mila sconosciuti, conserva solo ciò che saresti disposto a mostrare. I dipendenti, gli agenti e talvolta i collaboratori esterni leggono la cartella.

Perché tenere una cartella ai-clone separata e perché non mescolarla a business?#

L’idea è semplice: l’azienda sa di cosa ci occupiamo. Il clone sa come prendo le decisioni.

La struttura di ai-clone/ nel progetto descritto dall’autore:

ai-clone/
├── INDEX.md           ← mappa della cartella
├── role.md            ← chi sono, il mio background, cosa conta
├── identity/          ← valori, visione, missione
├── thinking/          ← modelli mentali tratti dagli interventi
├── voice/             ← tono, vocabolario, stile
├── principles/        ← convinzioni su prodotto, codice, azienda
├── feedback/          ← regole imparate dagli errori ← cartella principale
├── style/             ← parole da evitare, formato Telegram
└── reference/         ← strumenti, ambiente

La cartella più utile è feedback/. Contiene regole specifiche che ho imparato dagli errori degli agenti. Ogni regola va in un file separato, in questo formato:

---
name: short-name
description: one line - what’s in the file and when to apply it
type: feedback
---

Una regola breve, espressa in una frase.

**Perché:** perché esiste questa regola. Contesto, incidente, osservazione.

**Come applicarla:** condizioni specifiche che indicano quando si applica la regola.

Senza «Perché», la regola è morta: l’agente non la trasferirà a una situazione simile. Senza «Come applicarla», non è chiaro quando usare la regola.

Un esempio dalla mia cartella: la regola «trattino, non trattino lungo». È nata perché il trattino lungo — è un importante segno visivo del testo generato. Si applica a qualsiasi testo destinato al pubblico. Il file si trova in ai-clone/feedback/no-em-dashes.md.

Io faccio in modo un po’ diverso: scrivo le regole in ai-clone/feedback/, non in CLAUDE.md. CLAUDE.md è un file del progetto, ma le regole su tono e stile sono personali. Mi seguono nel progetto successivo. CLAUDE.md resta con il progetto.

Cosa sono le metriche Live e perché non inserire i numeri direttamente nei file?#

Uno dei principali rischi quando si crea un secondo cervello è riempirlo di numeri obsoleti. Scrivi «abbiamo 320 clienti» e due settimane dopo sono già 410. Scrivi «il fatturato mensile è 4.7 milioni» e un mese dopo il numero perde il contesto: è un obiettivo, un dato effettivo o una previsione?

Nell’esempio dell’autore funziona così. Nel file business/products/practicum.md c’è un marcatore al posto del numero:

## Coorti

> **LIVE** - esegui le query in `live-metrics.md`, sezione «Vendite»,
> per vedere i pagamenti aggiornati per coorte.

| Coorte | Date | Paganti |
|-------|------|------------|
| 1 | March 10-12, 2026 | LIVE |
| 2 | March 24-26, 2026 | LIVE |

Un file separato live-metrics.md contiene query SQL pronte all’uso e descrizioni di ciò che restituiscono:

## Vendite (pagamenti per coorte)

```sql
SELECT c.name, COUNT(p.id) AS paid, SUM(p.amount) AS revenue
FROM purchases p
JOIN cohorts c ON c.id = p.cohort_id
WHERE p.status = 'paid'
GROUP BY c.name
ORDER BY c.starts_at DESC;
```

Quando chiedo all’agente «quanti pagamenti abbiamo per la seconda coorte?», l’agente:

1. Legge business/products/practicum.md
2. Vede il marcatore LIVE accanto al numero
3. Apre live-metrics.md
4. Trova la sezione «Vendite»
5. Esegue la query sul database di produzione
6. Risponde usando dati aggiornati

Così risolvi due problemi insieme. I numeri non diventano obsoleti. E le decisioni si basano sul quadro attuale, non su quello dell’anno scorso.

Come si orienta l’IA nel secondo cervello per una singola richiesta?#

Una richiesta specifica, per esempio: «scrivi un’e-mail ai partecipanti sulla nuova coorte».

1. Claude parte con una finestra vuota. Carica CLAUDE.md (regole, stack, instradamento).
2. Dall’instradamento in CLAUDE.md vede: «ai-clone/INDEX.md - da leggere sempre all’inizio di una sessione». Apre il file e scopre chi sono, qual è il mio tono e quali parole evito.
3. Nell’instradamento vede: «modelli per le e-mail - src/lib/email/layout.ts». Apre il file e capisce il formato.
4. Vede: «contesto del prodotto - business/products/practicum.md». Apre il file e legge le informazioni sul prodotto.
5. Nel file vede il marcatore LIVE e un riferimento a live-metrics.md. Apre il file e individua la query SQL pronta all’uso. Se gli serve un numero aggiornato, esegue la query. Altrimenti annota «recuperare questo numero al momento dell’invio».
6. Consulta le regole sul tono in ai-clone/style/telegram-format.md, il divieto dei trattini lunghi in ai-clone/feedback/no-em-dashes.md e i tassi di conversione del funnel in business/marketing/funnel.md.

Scrive l’e-mail con il mio tono, numeri aggiornati e senza trattini lunghi né marcatori di testo generato dall’IA.

Nel suo blog di ingegneria, Anthropic chiama questo approccio contesto just-in-time:

In altre parole, Claude porta con sé i riferimenti ai dati, non i dati stessi. È molto più efficiente nell’uso dei token e molto più accurato, perché nel contesto finisce solo ciò che è pertinente. La finestra resta libera per ragionare.

5 anti-pattern del secondo cervello: cosa evitare?#

Anti-pattern 1. Un CLAUDE.md troppo esteso. 500 righe di istruzioni «invece di mettere tutto in un unico posto». Anthropic è chiara:

La lunghezza obiettivo è 80-120 righe. Sposta tutto il resto in file separati e rimanda a essi.

Anti-pattern 2. Una cartella generica. Metti tutto nel secondo cervello: corrispondenza grezza delle chat, screenshot inutili, report che nessuno leggerà. Un mese dopo la cartella è cresciuta a dismisura, l’agente spreca token leggendo materiale inutile e tu non ricordi più dove si trova niente. La regola: ogni file del secondo cervello deve rispondere a una domanda specifica. Se nessuno lo apre da sei mesi, cancellalo o spostalo nell’archivio.

Anti-pattern 3. Duplicazione. «I pagamenti passano da CloudPayments, in src/lib/payment/cloudpayments.ts; il fornitore è configurato in .env». L’agente può vedere tutto questo nel codice. Non duplicarlo in business/. Le copie diventano obsolete: il codice cambia, business/ non viene aggiornato e l’agente lavora su informazioni superate.

Anti-pattern 4. Numeri inseriti direttamente. «Abbiamo 1,247 clienti, con un tasso di conversione del 6.3%»: immagina che siano numeri di una generica startup fintech. Saranno obsoleti entro una settimana. Usa il marcatore LIVE e live-metrics.md. La sezione dedicata si trova sopra.

Anti-pattern 5. Contesto senza un percorso accessibile. Se il secondo cervello è altrove e l’agente non ha permessi né rimandi, partire dalla cartella del codice non basta. Per note condivisibili non sensibili, business/ e ai-clone/ nel repository sono una disposizione comoda. Per il contesto privato usa una posizione controllata separatamente e configura esplicitamente accesso consentito e instradamento. La comodità delle cartelle non prevale sulla riservatezza.

Come creare un secondo cervello in un’ora: ricetta passo dopo passo#

1. Crea due cartelle principali

   Nella radice del progetto, accanto a src/:

   mkdir -p business/{products,audience,goals,economics,marketing}
   mkdir -p ai-clone/{identity,voice,principles,feedback,style}
   

2. Crea un INDEX.md come mappa della cartella

   business/INDEX.md è una tabella «domanda → file». Inizia con almeno 5 righe e aggiungine altre man mano. Fai lo stesso in ai-clone/INDEX.md.

3. Aggiungi brevi descrizioni del prodotto e del cliente

   business/products/main.md: cos’è il prodotto, a chi si rivolge, quanto costa e cosa lo rende diverso. 30-50 righe. business/audience/avatar.md: chi è il cliente, quali problemi affronta e cosa compra. 30-50 righe. Non descrivere un cliente ideale: descrivine uno reale. Se non sai qualcosa, segnalo come «da chiarire» e vai avanti.

4. Descriviti in ai-clone/role.md

   Chi sei, cosa fai e cosa conta per te. 20-30 righe. È sufficiente per iniziare. Aggiungi tono, principi e parole da evitare quando noti che l’agente scrive con uno stile che non ti appartiene.

5. Aggiungi l’instradamento a CLAUDE.md

   Apri CLAUDE.md e aggiungi una sezione:

   ## Mappa del progetto
   
   - Contesto aziendale → `business/INDEX.md`
   - Contesto su di me → `ai-clone/INDEX.md`
   - Piani tecnici → `plans/YYYY-MM-DD-*.md`
   - Riflessioni sulle sessioni passate → `retrospectives/`
   
   Leggi sempre `ai-clone/INDEX.md` e `business/INDEX.md` all’inizio di una sessione.
   

6. Avvia Claude Code e controlla

   Apri l’agente. Chiedigli: «parlami del mio prodotto e del mio pubblico». Se risponde basandosi sul contesto della cartella, funziona. Se inventa cose, controlla che le cartelle siano accanto al progetto, che i file abbiano i nomi corretti e che l’instradamento in CLAUDE.md sia formulato con precisione.

Dopodiché, il secondo cervello cresce secondo due principi.

Primo: ogni volta che l’agente commette un errore, aggiungi una regola. Dopo 3-4 settimane, ai-clone/feedback/ conterrà 15-20 file di regole e l’agente smetterà di ripetere la maggior parte degli errori comuni.

Secondo: ogni volta che prendi una decisione aziendale, registrala in business/. Se aumenti un prezzo, aggiungi una nota a business/products/pricing.md con la data e il motivo. Se cambi posizionamento, aggiungi una nota a business/company/about.md. Sei mesi dopo avrai un archivio che ricorda «perché».

Abbiamo lavorato parecchio insieme questa settimana.

Analizza tutte le modifiche al codice di questa settimana, tutti i commit che abbiamo fatto.
Quali informazioni utili ricavate da questo lavoro dovrebbero stare in business/? Scrivile nei file appropriati,
aggiungendo wiki link ai file vicini, affinché il contesto non vada perso.

Se nel codice ci sono decisioni che non ho spiegato, chiedimi il motivo
e registra la motivazione nel file appropriato, annotando la data.

Non duplicare ciò che è già evidente dal codice. Includi solo ciò che l’agente
non saprebbe nella sessione successiva senza business/.

Cosa fare dopo: Skills, Subagents e ingegneria del contesto#

Una volta creato il secondo cervello, ci sono altri tre strumenti che Anthropic descrive come tre diversi livelli di ottimizzazione del contesto.

Le Skills sono conoscenze procedurali. Se hai un flusso di lavoro che ripeti (scrivere una guida didattica, preparare un post Telegram, controllare un sito web), puoi codificarlo in un file SKILL.md con una descrizione dell’attività. All’inizio di una sessione, Claude esamina i nomi e le descrizioni delle skills e carica solo quelle adatte all’attività in corso. Questo fa risparmiare token e mantiene la concentrazione.

I Subagents sono istanze isolate di Claude con finestre di contesto proprie. Avvia un subagent per un’attività impegnativa (leggere 30 file e prepararne un riepilogo): lavorerà nella propria finestra e restituirà solo il risultato. La finestra principale resta libera. Anthropic scrive:

L’ingegneria del contesto consiste nel gestire ciò che entra nella finestra. Anthropic l’ha definita nel 2025 una competenza fondamentale per lavorare con gli agenti, un livello sopra il prompt engineering. Il prompt engineering consiste nello scegliere le parole. L’ingegneria del contesto consiste nello scegliere file, percorsi, skills e subagents.

Un secondo cervello è il primo elemento costitutivo dell’ingegneria del contesto. Senza, le Skills leggono uno spazio vuoto, i Subagents non hanno dove andare e la finestra dell’agente si riempie di informazioni casuali. Con un secondo cervello, tutti e tre gli strumenti iniziano a funzionare.

Passo successivo. Crea due cartelle accanto al progetto: business/ e ai-clone/. Aggiungi a ciascuna un INDEX.md di 5 righe che funga da mappa. Aggiungi quattro righe di instradamento a CLAUDE.md. In un’ora avrai una struttura funzionante per il secondo cervello. Poi sviluppala seguendo la regola «dopo ogni errore dell’agente, aggiungi una riga a ai-clone/feedback/». Nel manuale Come configurare correttamente CLAUDE.md spiego il modello completo di CLAUDE.md da usare per indirizzare al secondo cervello.

Continua a esplorare Ailoot su ailoot.ai.