Come costruire un company brain: context engineering per un'intera azienda

Un CLAUDE.md risolve il contesto di un progetto. Quando gli stessi fatti servono a quattro repository, a due agenti di automazione e a un collega nuovo, il problema cambia di natura: diventa context engineering a scala di azienda.

Il company brain è la risposta che uso da mesi: una fonte unica di conoscenza, versionata, con un contratto di routing che dichiara cosa entra in contesto e quando, e dei validatori che rendono eseguibili le regole di scrittura. Il perché sta nell'articolo precedente. Qui c'è l'implementazione.

Da oggi il punto di partenza è diverso: lo scheletro è pubblico su GitHub con licenza MIT. Si chiama company-brain-template, sono file markdown più due script Node senza dipendenze, e contiene struttura, MANIFEST.yaml e validatori senza un solo dato nostro dentro.

Cosa serve prima di cominciare

Poco, ed è la buona notizia.

• git e Node 18 o superiore. I validatori sono due script .mjs senza dipendenze: niente package.json, niente toolchain da installare.
• Un agente con accesso al filesystem o al repository: io uso Claude Code, ma va bene qualunque cosa legga file da una cartella.
• Tre artefatti che hai già: la migliore proposta che hai vinto, il tuo contratto tipo, e le ultime dieci mail con cui hai risposto a un cliente in trattativa.

Il terzo punto è quello che conta. Se stai pensando di fermarti tre settimane a documentare l'azienda, hai già sbagliato: la conoscenza esiste, sta dentro le cose che hai prodotto, e il lavoro non è scriverla ma estrarla.

Passo 1: prendere lo scheletro

Sul repository c'è il bottone Use this template. Ti crea un repository nuovo, con la struttura dentro e senza la nostra storia di commit attaccata, che è quello che vuoi: un brain deve partire dal tuo primo commit.

Crealo privato. Conterrà prezzi, marginalità e informazioni sui clienti. Su questo torno alla fine, perché è il punto su cui si sbaglia più facilmente.

Se preferisci non passare da GitHub:

git clone https://github.com/Castaldo-Solutions/company-brain-template.git brain
cd brain && rm -rf .git && git init

Quello che ti ritrovi è questo:

CORE.md            il solo file sempre in contesto
MANIFEST.yaml      quale file si carica, e quando
company/           fatti: cosa vendi, a chi, a quali condizioni
decisions/         decisioni: perché avete scelto così, mai riscritte
playbooks/         modelli: come si fa una cosa
examples/          artefatti reali che hanno funzionato
validators/        le regole di scrittura, rese eseguibili

Passo 2: scrivere il file che sta sempre in contesto

Il CORE.md è l'anello 0: l'unico file che viene caricato in ogni sessione di ogni agente. Ogni riga costa a tutti, quindi si difende.

Ci vanno quattro cose e basta:

1. Chi siete, in dieci righe. Cosa fate, a chi vendete, cosa promettete, con quale metodo. Scritto come lo direbbe un cliente, non come lo scriveresti in una brochure.
2. Le regole non negoziabili. Quelle vere, verificabili. "Scrivi bene" non è una regola. "Mai il trattino lungo" lo è.
3. La mappa, cioè dove sta il resto. Massimo quindici righe: per aggiungerne una, se ne toglie una.
4. Cosa è riservato e chi decide sui prezzi.

La disciplina qui è tutta nel non aggiungere. Il nostro CORE.md sta in 85 righe dopo mesi di uso, ed è rimasto corto perché ogni volta che qualcuno voleva aggiungere una riga doveva dire quale toglieva.

L'errore da evitare: riversare tutto nel file principale perché "così l'agente sa tutto". Un file sovraccarico non risolve il degrado delle sessioni lunghe, lo anticipa. È lo stesso errore che si fa con il CLAUDE.md di un progetto, e la soluzione è la stessa: un indice corto, e il dettaglio che si carica quando serve.

Passo 3: estrarre i primi fatti invece di scriverli

Adesso apri i tre artefatti e riempi tre file in company/.

Il campo che nessuno scrive e che vale più di tutti è in icp.md: chi rifiutiamo, e perché. Ogni voce lì dentro è un progetto che non brucerà tre mesi.

Ogni file di fatti porta un frontmatter con la data di verifica:

---
owner: gaetano
verified_on: 2026-08-06
review_every: 90d
status: current
ring: 1
confidential: false
---

Serve a una cosa precisa: scaduta quella data, il contenuto torna a essere un'ipotesi da verificare, non una verità su cui costruire una proposta.

Una accortezza che ci ha salvato: marca come da confermare tutto quello che hai dedotto dallo storico e che nessuno ha dichiarato. Un fatto derivato da tre proposte simili è una probabilità, non una regola aziendale.

Passo 4: dichiarare cosa si carica e quando

Qui c'è il vincolo tecnico che dà forma a tutto il resto, e ha un nome: context rot. Le prestazioni di un modello calano al crescere della lunghezza dell'input anche su compiti semplici, e il calo comincia molto prima della finestra dichiarata: lo studio di Chroma del 14 luglio 2025 lo misura su 18 modelli, tra cui Claude 4, GPT-4.1 e Gemini 2.5 (Context Rot: How Increasing Input Tokens Impacts LLM Performance).

Tradotto in pratica: caricare tutta la conoscenza a ogni sessione non è solo impossibile per il budget di token, peggiora attivamente le risposte.

La soluzione sono gli anelli, dichiarati nel MANIFEST.yaml:

  - path: company/pricing.md
    ring: 1
    confidential: true
    never_in: [contenuti pubblici, output a terzi]
    load_when: [proposta, preventivo, sconto, trattativa, budget]

• Anello 0: sempre in contesto. Ce ne sta uno, forse due.
• Anello 1: si carica su richiesta, in base al tipo di lavoro. I prezzi quando fai una proposta, la strategia editoriale quando scrivi un articolo. Mai insieme.
• Anello 2: non entra mai, si cerca quando serve.

La regola pratica per decidere: un file entra in anello 1 solo se serve più di una volta al mese.

Il campo load_when non è decorativo: è quello che permette a un agente di decidere cosa leggere consultando un contratto, invece di frugare nelle cartelle.

Passo 5: agganciarlo all'assistente

Il brain vive nel suo repository, e i progetti se lo agganciano come submodule:

cd <repo-di-lavoro>
git submodule add <url-del-brain> brain
git commit -m "chore: aggancia il company brain"

Poi basta una riga nel file di istruzioni del progetto:

# CLAUDE.md

## Company Brain
@brain/CORE.md

## Architettura del progetto
[quello che vale solo per questo codice]

Da quel momento ogni sessione parte conoscendo l'azienda.

Il criterio che tiene separate le due cose è uno solo: se serve a un solo progetto resta nel CLAUDE.md, se serve all'azienda va nel brain. È esattamente la regola che impedisce il problema da cui è nato tutto: la stessa conoscenza copiata in quattro posti che divergono.

Ricordati di escludere brain/ dai deploy. È conoscenza, non codice da pubblicare.

Passo 6: impedire che marcisca

Questa è la parte che separa un brain vivo da una cartella di documenti morti, ed è anche quella che quasi tutti saltano.

Due comandi:

node validators/brand-lint.mjs company/identity.md   # come si scrive
node validators/freshness.mjs                        # cosa è scaduto

E soprattutto, il linter attaccato al commit, così le violazioni non entrano proprio:

# .git/hooks/pre-commit
#!/bin/sh
git diff --cached -U0 | node validators/brand-lint.mjs --diff

La modalità --diff legge un unified diff da stdin e guarda solo le righe aggiunte, ricostruendo file e numero di riga dagli header +++ e @@. È il dettaglio che rende il linter adottabile su un repository che ha già migliaia di righe dentro: il pregresso non viene mai imputato a chi tocca il file oggi.

Entrambi gli script escono con codice 1 quando trovano qualcosa di bloccante, quindi si mettono in CI senza adattamenti. Su freshness conviene però un job schedulato e non uno a ogni push: un fatto che scade non è un buon motivo per far fallire una build, è un buon motivo per mandare un promemoria a qualcuno.

Le regole stanno in un file separato, validators/rules.mjs, e vanno riscritte con le tue. Quelle nel template sono un punto di partenza, non uno standard. La via d'uscita per le righe che contengono per forza un termine vietato è il pragma brand-lint:ignore, e i blocchi di codice recintati sono saltati in automatico.

La regola culturale conta più degli strumenti: ogni correzione che fai a un output di un agente è un fatto che manca nel brain, e si registra subito, non "dopo". Se correggi tre volte la stessa cosa, il problema non è l'agente.

Perché non un RAG con un vector database?

È la prima obiezione che mi fanno, ed è giusta: se il problema è dare conoscenza a un modello, il RAG esiste da anni e funziona.

La risposta breve: a questa scala il collo di bottiglia non è il recupero, è il determinismo. Un brain aziendale sono decine di file curati, non decine di migliaia di documenti. Il problema non è trovare il pezzo giusto in un corpus enorme, è garantire che le regole non negoziabili entrino in contesto sempre, e che i prezzi entrino solo quando si fa una proposta. Una ricerca semantica ti dà il documento probabilmente giusto. Un contratto di routing ti dà quello dichiarato.

Il punto che conta più di tutti sta nella riga della revisione: un fatto sbagliato in un file markdown lo vedi in un diff e lo correggi in una pull request. Un fatto sbagliato dentro un embedding non lo vede nessuno.

Le due cose non si escludono. Il giorno che devi interrogare dieci anni di documentazione tecnica o l'archivio dei ticket, il RAG è la risposta giusta e il brain non c'entra. Ma per la conoscenza che decide come si scrive una proposta, un file che si legge, si diffa e si approva vince su un indice che va ricostruito.

Cosa non mettere mai dentro

Tre cose, e la terza è quella che sorprende.

Le credenziali. Mai, nemmeno temporaneamente. Il brain descrive dove stanno i segreti, non cosa sono.

I documenti sorgente dei clienti. Non ci va il PDF della proposta: ci va la conoscenza derivata da quella proposta. La differenza è tra un archivio che cresce all'infinito e una memoria che resta utilizzabile.

Quello che non hai verificato. Un brain pieno di ipotesi presentate come fatti è peggio di un brain vuoto, perché nessuno pensa a metterle in discussione.

E il punto di sicurezza che vale più di tutti: il repository sta privato. Un brain è il documento più sensibile che ha un'azienda, e a differenza del codice si legge senza competenze tecniche. Chiunque lo apra capisce in dieci minuti a chi vendi, a quanto e con che margine.

Quanto tempo serve davvero

Le prime venti righe utili: mezza giornata, se hai i tre artefatti aperti davanti.

Il resto non si fa in una sessione, e non deve. Si aggiunge un fatto alla volta, quando emerge da un lavoro vero. Il nostro è arrivato a 88 file e quasi 70.000 parole in una settimana, ma solo perché è stato estratto da 22 proposte e 63 articoli che esistevano già: non è stato scritto, è stato raccolto.

Come capisci che sta funzionando

C'è un test solo, e dura due minuti.

Apri una sessione nuova e chiedi all'assistente di scrivere qualcosa che richiede di conoscere la tua azienda: una mail di follow-up a un cliente tipo, la bozza di una sezione di proposta. Senza dargli nessuna istruzione aggiuntiva.

Se l'output è utilizzabile al primo tentativo, funziona. Se devi correggerlo, quella correzione è il prossimo fatto da registrare. In entrambi i casi hai imparato qualcosa, ed è per questo che il test si rifà ogni tanto.

Domande frequenti

Serve saper programmare? Per scriverlo no, è markdown in una cartella. Serve competenza tecnica per agganciarlo agli agenti e per collegare i validatori al commit, che sono due comandi. La parte che conta davvero, decidere cosa è vero e chi lo conferma, è lavoro di chi guida l'azienda.

Perché non usare direttamente un RAG? Perché a questa scala il problema non è il recupero, è il determinismo: un contratto di routing garantisce che certe regole entrino sempre in contesto e che i prezzi entrino solo quando servono. E un fatto sbagliato in un markdown si vede in un diff, dentro un embedding no. Sui corpus grossi e sulla ricerca aperta il RAG resta la risposta giusta, e le due cose convivono.

Posso usarlo con un assistente diverso da Claude? Sì. Il brain è markdown in una cartella, quindi qualunque cosa sappia leggere file lo può consumare. Cambia solo il modo di agganciarlo: dove Claude Code importa il CORE.md dal file di istruzioni, altrove punti l'assistente alla cartella e gli dici di leggere prima il CORE.md e poi il MANIFEST.yaml.

Quanto costa mantenerlo? Poco, se l'aggiornamento sta dentro il lavoro invece che accanto al lavoro. Il costo vero non è il tempo, è la disciplina di registrare una correzione nel momento in cui la fai.

E se l'azienda è piccola? È il caso in cui rende di più, perché la conoscenza sta quasi tutta in una testa sola. Il brain è il modo per farla uscire senza fermarsi a scrivere un manuale.

Da dove parti oggi

Apri il template, premi Use this template, crea il repository privato e scrivi le prime venti righe del CORE.md. Trenta minuti, e già da lì la qualità di quello che ti produce un assistente cambia.

Se lo provi, aprire una issue sul repository e dire cosa hai tenuto, cosa hai buttato e dove si è rotto è la cosa più utile che puoi fare: quel template nasce dalla pratica di una azienda sola, e ogni resoconto da un contesto diverso è l'unico modo perché smetta di esserlo.

La tua azienda sta usando l'AI e i risultati restano generici? Vuoi che il brain lo costruiamo insieme sui tuoi artefatti veri?

È esattamente quello che facciamo nel pre-assessment gratuito: guardiamo dove vive oggi la conoscenza della tua azienda, quali documenti valgono come materia prima, e usciamo con il primo anello già scritto.