Second Brain Aziendale per lo Sviluppo: Documentazione, Skill e Agenti AI

Due team, due contesti diversi, lo stesso problema: la conoscenza che serve per lavorare vive nelle teste delle persone e nelle chat. Racconto come ho costruito per entrambi un "second brain" fatto di documentazione a livelli, skill e agenti AI, cosa ha funzionato, cosa no, e con quali numeri.

Ogni team di sviluppo ha un momento in cui si accorge di dipendere da poche persone. Il server che solo uno sa riavviare nel modo giusto. La procedura di messa in produzione che "è scritta da qualche parte". L'incidente di sei mesi fa che si ripete identico perché la lezione è rimasta in una chat. Il fornitore che se ne va e lascia una call di passaggio di consegne e qualche PDF.

Gli agenti AI per lo sviluppo hanno reso questo problema più urgente, non meno. Un agente che non sa com'è fatta la tua infrastruttura fa le stesse ipotesi sbagliate di un collega appena arrivato, solo più in fretta e con più sicurezza. Ma hanno anche reso la soluzione più conveniente: la documentazione scritta bene non serve più solo alle persone, la legge anche l'agente, ogni volta, senza stancarsi.

In pratica è una knowledge base aziendale pensata per gli agenti AI: documenti, regole e procedure scritti in modo che li possa usare sia un collega sia un agente. Questo articolo è un caso studio, non una teoria. I due progetti sono reali e anonimizzati.

Per chi è: CTO, responsabili tecnici e sviluppatori senior di agenzie e team interni che usano o vogliono usare agenti AI (Claude Code o simili) sul lavoro vero: manutenzione, incidenti, ticket, rilasci.

Cosa non è: un tutorial su Notion o Obsidian per gli appunti personali. Qui il "second brain" è del team, e il suo lettore principale è anche un agente.

Indice

I due contesti

Un'agenzia e-commerce. Circa 17 siti Magento in produzione su un cluster condiviso, 29 repository di siti, una cinquantina di moduli interni distribuiti come pacchetti Composer. Il lavoro tipico è operativo: un sito rallenta, un bot satura la cache, una patch di sicurezza va portata su tutti i siti, un nuovo cliente va messo online senza dimenticare nessun passaggio.

Il portale di un'università. Un backend, un'app mobile, un CRM, un sistema di prenotazione e una manciata di librerie ereditate, presi in carico da un fornitore uscente. Il lavoro tipico è diverso: capire un sistema che non hai scritto, rispondere a centinaia di ticket degli utenti, correggere senza poter rilasciare codice per mesi a causa del calendario accademico.

Contesti opposti, ma la struttura che ha funzionato è la stessa: tre livelli che si appoggiano l'uno sull'altro.

Livello 1: la documentazione a strati

Il primo errore che si fa è scrivere un unico file di istruzioni enorme per l'agente. Funziona per una settimana, poi diventa un muro di regole che nessuno rilegge e che l'agente applica male perché tutto ha la stessa importanza.

Quello che ha funzionato è una gerarchia, dal generale al particolare:

LivelloCosa contieneEsempio
Globale (persona)Regole che valgono in ogni progetto"Il codice si modifica solo in locale, mai sul server"; "prima di giudicare un branch, fai fetch"
WorkspaceSolo ciò che vale in ogni sessione su quel clienteLe quattro difese anti-bot da non confondere tra loro
DominioUn'area con le sue convenzioniSicurezza e monitoraggio: dove stanno i log, come si chiamano i report
Progetto o moduloComandi, architettura, trappole di build"Il bundle frontend va committato, la CI controlla che sia in sincronia"

Il file di workspace dell'agenzia dichiara esplicitamente il suo scopo nella prima riga: contiene solo le regole che valgono in ogni sessione. Tutto il resto è un indice che rimanda a file che l'agente apre quando servono. È lo stesso principio di una buona documentazione per persone: non si legge tutto, si sa dove guardare.

Altri quattro accorgimenti che si sono rivelati decisivi:

  • La documentazione del codice sta accanto al codice. Nel progetto universitario i capitoli sul backend sono stati spostati nel repository del backend. Al loro posto è rimasto un segnaposto di venti righe ("Spostato: vedi qui") per non rompere i link, e la numerazione dei capitoli è rimasta unica tra i due repository.
  • Un file "punto di ripartenza". Dove eravamo rimasti, cosa è stato deciso, cosa è aperto. Lo legge chi riprende il lavoro dopo una settimana, persona o agente che sia.
  • La documentazione dichiara di poter essere sbagliata. Sembra un dettaglio, è il contrario: la regola "la fonte di verità è la macchina, la doc può essere stantia, verifica" evita che un agente applichi con sicurezza una procedura vecchia di tre mesi.
  • Le lacune si dichiarano. Nella checklist di messa in produzione ci sono punti marcati come "non documentato". Un buco dichiarato è un'informazione; un buco nascosto è una trappola.

Livello 2: le skill, "com'è fatto" e "cosa fare"

Una skill, nel senso degli agenti di sviluppo moderni, è un pacchetto di istruzioni che l'agente carica quando il compito lo richiede: una descrizione che dice quando usarla, e un corpo che dice come. La differenza rispetto a un documento qualsiasi è che viene attivata dal contesto, non cercata.

Nell'agenzia le skill sono due, e la divisione è la parte più utile del progetto:

  • "Com'è fatto": l'infrastruttura. Quale sito sta su quale server, quale database, quale cache. Dieci regole sempre valide. E soprattutto una tabella sintomo, prima ipotesi, file da aprire.
  • "Cosa fare": la messa in produzione di un nuovo sito. Una checklist di 14 passi e 12 vincoli di sequenza che non si possono invertire.

La tabella dei sintomi è quella che fa risparmiare più tempo. Ha questa forma (semplificata):

| Sintomo                     | Prima ipotesi                    | Dove guardare          |
|-----------------------------|----------------------------------|------------------------|
| 503 su un solo sito         | pool PHP saturo da bot           | infra/varnish.md       |
| sito lento dopo un deploy   | cache non riscaldata             | infra/cache.md         |
| scritture che falliscono    | disco pieno (df -h prima di tutto)| infra/storage.md       |

Invece di ragionare da zero, l'agente parte dall'ipotesi che un collega esperto farebbe per prima, e apre un solo file invece di dieci.

I vincoli di sequenza hanno una caratteristica precisa: ognuno porta con sé l'incidente che l'ha generato, con data e contesto. "La cache va configurata prima dell'ambiente applicativo", seguito da cosa è successo la volta che è stato fatto il contrario. Questo dettaglio serve a una cosa sola: impedire che qualcuno, persona o agente, "semplifichi" la regola perché sembra superflua.

Nel progetto universitario lo stesso principio ha preso un'altra forma: una skill per ambiente (sviluppo, staging, produzione), ognuna con le ricette di accesso in sola lettura, i comandi da lanciare come utente applicativo e la propria tabella sintomo e dove guardare.

Livello 3: agenti che leggono, persone che scrivono

Il terzo livello è dove gli agenti smettono di essere un assistente in chat e diventano una catena di lavoro. Il caso più completo è la gestione dei ticket del portale universitario: centinaia di segnalazioni di utenti, molte duplicate, molte senza le informazioni necessarie.

La pipeline è divisa in compiti con responsabilità separate:

  1. Scarico e import. I ticket vengono scaricati dal sistema del cliente e importati in un database locale, in modo ripetibile, con un registro delle modifiche e un cruscotto.
  2. Classificatore. Assegna a ogni ticket funzione, sintomo e competenza scegliendo da una tassonomia chiusa (8 funzioni, 22 sintomi, 9 competenze), costruita leggendo i ticket reali. Lavora a lotti di 25, con al massimo 4 istanze in parallelo, e usa un modello più economico perché il compito è di massa. Non cerca la causa e omette i dati personali. Un valore nuovo nella tassonomia lo approva una persona.
  3. Ricercatore. Indaga il perché, in sola lettura, in un ordine fisso: documentazione, codice sul branch remoto, log, database di produzione. Sul database ha regole strette: una query alla volta, timeout di 20 secondi, sempre un limite di righe, alcune tabelle vietate. Produce un report in otto sezioni fisse.
  4. Risolutore. Prepara la soluzione: la correzione al codice e, quando serve, un tampone SQL diviso in cinque file (verifica, scrittura senza commit, guardia e commit, controllo, annullamento). Non ne esegue nessuno. Prepara anche le bozze di risposta all'utente.

La regola che tiene insieme tutto è semplice: gli agenti leggono e propongono, le persone scrivono. Nessun agente modifica dati di produzione. È la stessa separazione che si usa per i permessi di un collega nuovo, applicata in modo sistematico.

I numeri del primo giro:

  • 228 ticket coperti da 6 ricerche in circa due ore e mezza
  • 98 screenshot allegati ai ticket trascritti da 4 agenti in parallelo
  • 292 ticket classificati in 12 lotti, con 18 duplicati individuati e 9 segnalati come "da rivedere"

E un numero che di solito negli articoli sull'AI non si trova: il classificatore è misurato. Il risolutore, quando arriva alla causa vera, registra se la competenza assegnata all'inizio era giusta. Risultato: confermata in 79 casi su 205, il 39%.

Il 39% non è un fallimento, è il motivo per cui il sistema è progettato così. La classificazione iniziale serve a smistare e a raggruppare, non a decidere. Se fosse stata usata per assegnare il lavoro direttamente, sei ticket su dieci sarebbero finiti alla persona sbagliata. Separare la classificazione dall'analisi, e misurare la prima con la seconda, è l'unico modo per saperlo.

Il ciclo che fa crescere il sistema: ogni incidente diventa una regola

Un second brain che non impara è un archivio. La parte che ha reso il sistema dell'agenzia davvero utile nel tempo è un ciclo molto semplice:

incidente
   ↓
post-mortem (modello fisso: cosa è successo, interventi, lezioni, cosa resta aperto)
   ↓
la lezione diventa una regola nella skill, o una memoria
   ↓
il prossimo incidente simile parte già dall'ipotesi giusta

In pochi mesi l'agenzia ha accumulato 47 post-mortem e 77 memorie. Le memorie sono di tre tipi: feedback (regole apprese dalle correzioni, del tipo "non lanciare mai la CLI applicativa come root"), progetto (casi diagnosticati, con sintomo, causa e correzione) e riferimento (dove trovare cosa).

Lo stesso metodo ha portato a risultati che non c'entrano con l'AI ma che senza una documentazione così non sarebbero emersi: ricostruendo lo stato delle pipeline di deploy dei siti sono venute fuori 34 versioni divergenti dello stesso workflow, in sette generazioni diverse. Oggi ce n'è una sola.

Nel progetto universitario il ciclo parte prima ancora degli incidenti: dal passaggio di consegne. La call con il fornitore uscente è stata trascritta, strutturata, e poi confrontata con il codice, con un documento dedicato alle discrepanze tra quello che è stato detto e quello che c'è nel codice, ciascuna con il riferimento a file e riga. È il documento più utile di tutto il progetto.

Il flusso dal cliente alla produzione: cosa è coperto

L'obiettivo di partenza era coprire tutto il percorso: dal primo contatto con il cliente alla feature, ai test, alla produzione. Ecco dove siamo, senza abbellimenti:

FaseAgenzia e-commercePortale universitario
Richiesta del cliente e requisiti🔴 assente🟡 parziale: ticket, bozze di mail con le decisioni richieste, presentazioni
Analisi e diagnosi🟢 forte🟢 forte
Riproduzione del problema🟡 manuale🟢 ambiente locale che impersona l'utente su un dump ridotto
Sviluppo🟢 skill di sviluppo e revisione, branch e PR🟢 worktree per ogni correzione, PR
Test🔴 quasi assenti🟡 test case di collaudo scritti per il cliente, nessun test automatico
Messa in produzione🟢 checklist con vincoli🟢 runbook con rollback e registro delle migrazioni
Ritorno dell'esperienza🟢 molto forte🟢 forte

Il centro del flusso è solido. I due estremi no: la raccolta dei requisiti e i test sono le fasi dove oggi il second brain non aiuta. Non è un caso. Sono le fasi più legate alle persone (il cliente da un lato, il giudizio su "funziona" dall'altro), ed è dove sto lavorando adesso.

Cosa non ha funzionato

Un caso studio senza questa sezione è una brochure. Ecco i problemi reali.

Le regole scritte non bastano. Il ricercatore aveva la regola esplicita "sola lettura, nessun file sul server". Due volte, un agente ha comunque scritto un file temporaneo sulla macchina di produzione per comodità. Nessun danno, ma la lezione è chiara: un guardrail che vive solo nel testo del prompt è un consiglio. Quelli importanti vanno resi obbligatori con permessi e hook che bloccano il comando prima che venga eseguito.

La revisione automatica della documentazione fa rumore. La skill che cerca sezioni duplicate o in conflitto, al primo giro manuale, ha prodotto 99 candidati: circa 6 erano azioni vere, circa 90 rumore. La soluzione è stata un agente "giudice" per ogni coppia di file, obbligato a citare file e riga, con l'istruzione esplicita che "nessun problema" è un esito corretto. E una regola netta: le duplicazioni si correggono, i conflitti no, mai, perché l'informazione per scegliere quale versione è giusta non sta nella documentazione ma sul server.

Le skill devono viaggiare con il codice. In un progetto la cartella delle skill era esclusa dal repository. Risultato: chi apriva la sessione da un'altra cartella, o un collega su un'altra macchina, non le aveva. Se le skill sono conoscenza del team, vanno versionate come il resto.

I segreti tendono a finire nei documenti. Quando la documentazione diventa il posto dove si scrive tutto, ci finiscono anche credenziali e token "per comodità". Vanno tenuti fuori dai documenti fin dal primo giorno, e citati con un segnaposto.

Il tempo risparmiato non l'ho misurato. Ho i numeri dei ticket e degli incidenti, non un confronto rigoroso tra prima e dopo. È il prossimo numero che voglio avere.

Come iniziare nel tuo team

Se dovessi ripartire da zero domani, farei queste cose, in quest'ordine:

  1. Un file di istruzioni corto per workspace, con solo le regole che valgono sempre e un indice di dove sta il resto.
  2. Una tabella sintomo, prima ipotesi, dove guardare per il sistema che vi dà più problemi. È il pezzo con il ritorno più alto.
  3. Un modello fisso per i post-mortem, e l'abitudine di portare ogni lezione in una regola, con il caso che l'ha generata.
  4. Separare il "com'è fatto" dal "cosa fare" appena la documentazione supera qualche pagina.
  5. Agenti in sola lettura per diagnosi e analisi, con le scritture sempre preparate e mai eseguite.
  6. Guardrail obbligatori, non solo scritti, per tutto ciò che tocca la produzione.
  7. Misurare almeno una cosa che fanno gli agenti. Il 39% mi ha insegnato più di qualsiasi demo.

Il second brain non è uno strumento che si installa. È un'abitudine del team, scrivere quello che si impara nel posto dove servirà, che gli agenti AI hanno reso finalmente conveniente.

Articoli correlati

Vuoi un second brain per il tuo team di sviluppo?

Aiuto agenzie e team tecnici a costruire documentazione, skill e agenti AI sul loro lavoro reale: incidenti, ticket, rilasci. Partendo da quello che c'è già, senza riscrivere tutto.

Parliamone