Imparare lo strumento e strutturare la condivisione della conoscenza AI e tramite AI in azienda

Claude Code non è una chat. È un agente che gira un ciclo. Dato un PROMPT, Claude (1) raccoglie il contesto che gli serve, (2) agisce — modifica un file, esegue un comando — e (3) verifica i risultati: controlla se ciò che ha fatto soddisfa il prompt. Se non è completo, ripete il ciclo; quando lo è, termina. In qualsiasi momento puoi interromperlo, correggerlo o aggiungere contesto. Tutto il resto di questo documento discende da qui.

Claude Code dà il meglio dentro il repository dell'app. È pensato per quello. Nel repo ha il contesto — il codice, la struttura, le dipendenze, le convenzioni — e soprattutto ha gli strumenti per chiudere il passo di verifica del ciclo: può fare build, eseguire i test, lanciare i comandi e leggerne l'output. Fuori dal repo diventa una chat che indovina; dentro il repo diventa un agente che prova.

Si lavora in git: un branch per feature, commit piccoli e verificabili, review prima del merge. Git non è un dettaglio di processo — è la rete di sicurezza che rende accettabile lasciare agire l'agente: ogni sua azione è un diff su un branch, ispezionabile e reversibile, mai una scrittura cieca e definitiva.

Il contesto è la memoria di lavoro dell'agente: il tuo prompt, i file che legge, l'output dei comandi che esegue — tutto occupa spazio nella finestra di contesto, che è finita — ampia (circa 200.000 token, ~500 pagine di testo; fino a 1M su alcuni piani e modelli) ma non infinita. Quando si riempie, Claude Code compatta (riassume e scarta il superfluo per liberare spazio) — e la compattazione può perdere dettagli.

Il context rot è la conseguenza da conoscere: man mano che il contesto si riempie di roba irrilevante — lunghe esplorazioni, output verbosi, pezzi di feature diverse — la qualità delle risposte degrada. Non perché il modello peggiori, ma perché il segnale annega nel rumore. È il fallimento più comune, e non si cura con un prompt più elaborato: si cura tenendo il contesto pulito.

GraficoCome la qualità dell'output degrada man mano che la finestra di contesto si riempie: zona sana, zona di context rot, zona di auto-compattazione.

Un buon prompt ha tre parti. (1) Preparare il terreno: dai il contesto e lo scopo — dove siamo, cosa c'è già. (2) Descrivere il compito: cosa fare, concretamente. (3) Fornire le regole: i vincoli e il criterio di qualità con cui misurare il risultato. Le tre parti insieme fanno la differenza tra un agente che centra il bersaglio e uno che va corretto tre volte.

È il flusso di lavoro da cui parte tutto. Chi salta a «scrivimi il codice» paga dopo in correzioni. La sequenza corretta di una modifica è quattro passi:

1. Explore. In plan mode (sola lettura) Claude legge i file e capisce dove intervenire. Nessuna modifica: solo raccolta di contesto. Puoi anche usare il subagent Explore per una panoramica senza intenzione di modificare.
2. Plan. Claude produce un piano d'azione. È qui che si corregge la rotta — prima che una sola riga sia scritta, quando costa meno. Definisci i criteri di successo: cosa vuol dire «fatto bene».
3. Code. Approvato il piano, l'agente lavora la lista. È un botta-e-risposta fino al risultato. Dai a Claude una suite di test come fonte di verità: è il modo con cui verifica sé stesso (vedi §1).
4. Commit. Prima del commit, fai girare un subagent reviewer: occhi freschi, senza il bias accumulato nella sessione. Poi genera il commit nel tuo stile e fai push. Ripeti.

La configurazione di Claude Code vive nella directory .claude del progetto: settings, skill, subagent, hook. I comandi (gli slash-command scriptati) sono deprecati a favore delle skill; al più si conserva una skill con l'invocazione automatica disattivata (model-invocation=false) per i pochi casi che devono restare a scatenamento esplicito.

6.1 Cosa è una skill

Una skill non è un comando da terminale — non è git merge. È un comportamento atteso. La sua description dichiara quando va usata, e Claude la richiama da solo quando la situazione combacia. Esempio: Claude sta per scrivere nuovo codice → scatta la skill «come scrivere i commenti del codice». Non la invochi tu a mano: la descrivi bene e lei si attiva al momento giusto.

---
name: commenti-codice
description: Come scrivere i commenti del codice in questo progetto.
             Usare QUANDO Claude sta per scrivere o modificare codice sorgente.   // <- il "quando" è la parte che conta
---
  ... corpo della skill: le istruzioni vere e proprie ...

6.2 Skills sbagliate — cosa NON sono

Se pensi a una skill come a un comando — «quando invoco /deploy esegue il deploy» — c'è un problema alla base. Una skill non incapsula comandi deterministici. Se una procedura è sempre uguale — build, copia, incolla — scrivi uno script bash o Python, o ancora meglio una GitHub Action. Non serve una skill: è un'azione meccanica che si risolve con uno script, non un comportamento che Claude deve interpretare.

Allo stesso modo, una skill che «analizza tutto il repo, cerca i metodi definiti e vede se sono chiamati da qualche parte» non ha senso. Non serve una skill per questo: scrivi mezza riga di prompt — «builda ed elimina tutti i warning di codice morto» — e se vuoi rigore, usa un linter, che esiste da quarant'anni. La skill non è un contenitore per rimediare alla mancanza di tooling: è un comportamento atteso per situazioni che richiedono giudizio, non automazione lineare.

6.3 Come si invoca una skill — l'interfaccia è il linguaggio naturale

Conseguenza diretta: una skill non si invoca per nome. Non esiste un comando /analyze-log da ricordare. Se la skill è scritta bene — con una description che descrive quando scatta — basta scrivere «analizza i log e cerca il problema X» e il modello sceglie da solo la skill giusta. L'interfaccia con l'utente è il linguaggio naturale, non un vocabolario di comandi da imparare. Non serve sapere il nome esatto della skill né i suoi parametri: è il modello che decide se attivarla, in base alla descrizione e al contesto.

Tradotto: se qualcuno chiede «come si chiama la skill per analizzare i log?» la domanda è già sbagliata. La risposta giusta è «descrivi cosa vuoi fare e la skill scatterà da sola».

6.4 Regole delle skill

• Self-contained. Tutto ciò che serve sta dentro la cartella della skill — niente dipendenze implicite dall'esterno.
• Nascono in un progetto. Se lavoro alla commessa 141414, la skill nasce lì. La condivisione è un passo successivo ed esplicito (§9), non automatica.
• Si creano con una skill. Per scriverle bene si usa la skill skill-creator. Esempio di skill fatta bene: karpathy-guidelines.
• Prima di scriverne una, cerca. Esistono skill universalmente note e riusabili — ponytail, caveman (sito · github), openspec (sito · github), graphify (sito · github). Non reinventare ciò che esiste già.

«Le memorie di Claude» come le si immagina non esistono. Ciò che esiste è CLAUDE.md: la memoria del progetto. Viene letto e appeso al prompt a ogni sessione. Deve chiamarsi esattamente CLAUDE.md — è quel file a essere caricato nel contesto, non un AGENTS.md o un QUALSIASI.md. Il suo contenuto descrive il progetto: «questo è la commessa X di ACME S.p.A., fa Y; stack; comandi di build e test».

Qui sta la distinzione che governa tutto — cosa viene caricato nel contesto e quando:

• CLAUDE.md → caricato per intero, sempre. Ogni sua riga è contesto pagato a ogni sessione. Quindi va tenuto compatto: solo ciò che serve sempre.
• Skill → caricata solo la description. Il corpo entra nel contesto solo quando la skill scatta (progressive disclosure). Puoi averne cento senza appesantire il contesto.
• Rules → caricate per path. Con paths nel frontmatter una rule entra nel contesto solo quando editi un file che combacia col glob; senza paths si carica all'avvio come CLAUDE.md (§7.3).

7.1 Le direttive vanno nelle skill, non in CLAUDE.md

Regola forte: le direttive — «fai così, non cosà» — non vanno in CLAUDE.md, né in AGENTS.md, né in un qualunque *.md. Vanno in una skill/<nome-skill>/SKILL.md. CLAUDE.md descrive il progetto; le skill portano i comportamenti, e si caricano solo quando servono.

# Progetto
Commessa 141414 — sistema HMI per ACME S.p.A.  Stack: .NET / WPF.
# Comandi
build: msbuild ...   ·   test: dotnet test
// le regole di stile / "fai così" → NON qui, ma in skill/<nome>/SKILL.md

7.2 Le specifiche redatte da Claude vivono nel repo — ma non sono memoria

Lavorando a progetti di sviluppo si possono tenere specifiche redatte da Claude in file .md — «perché ho creato questa classe», «come funziona questo modulo» — committate nel repo: tutti gli sviluppatori le vedono. Ma attenzione: non sono una memoria di Claude. Se lavoro alla feature A, a Claude non serve la feature B — precaricarla sarebbe solo inquinamento del contesto (il context rot del §3). Le spec stanno nel repo per gli umani e vengono lette da Claude on-demand, quando servono, non appese al contesto di ogni sessione.

7.3 Le rules: convenzioni di scrittura del codice, attivate per path

Esiste una terza modalità di caricamento, tra CLAUDE.md (sempre, per intero) e le skill (solo la description): le rules. Vivono in .claude/rules/ — un file .md per regola — e portano le convenzioni di scrittura del codice: «i nomi delle classi in PascalCase», «commento XML su ogni membro pubblico». Sono l'eccezione mirata alla regola del §7.1: direttive in un .md sì, ma solo perché caricate chirurgicamente, non a ogni sessione.

La chiave è il campo paths nel frontmatter: un pattern glob sui file — una «regex» sullo scopo interessato — che decide quando la regola entra nel contesto.

• Con paths. La regola si carica solo quando Claude tocca un file che combacia col pattern. Le convenzioni del backend .NET pesano sul contesto solo mentre si edita un *.cs — non quando si tocca un CSS.
• Senza paths. La regola si carica all'avvio, per tutti i file — come una riga di CLAUDE.md. Da usare con parsimonia, per lo stesso motivo del §7.2.

// .claude/rules/dotnet-convenzioni.md
---
paths:
  - "**/*.cs"          // <- il glob: attiva la regola SOLO sui file .cs
  - "src/backend/**"
---
# Convenzioni C#
- Nomi delle classi in PascalCase.
- Commento XML su ogni membro pubblico.
  ... le regole vere e proprie ...

Rispetto alla skill del §6.1 — che scatta sul comportamento («sto per scrivere codice») — la rule scatta sul path («sto toccando questi file»). Sono complementari: la skill per il comportamento, la rule per la convenzione legata a un tipo di file. Attenzione alla sintassi: è un glob (**/*.cs), non una regex PCRE — stesso spirito, notazione diversa.

Esempi di rules reali (C#/.NET), distillate dalla codebase della commessa 5309 FAEL: github.com/marc04AM/AiFormation/tree/main/examples/rules.

7.4 Il «perché» di una modifica: dall'archivio post-hoc alle spec

Caso reale: «Andrea vuole sapere perché Marco ha fatto questa modifica.» La risposta deve stare nel repo — non nella testa di Marco, né in una chat perduta. Due approcci: uno legacy, uno da adottare.

Oggi (legacy) — l'archivio post-hoc. Un hook PostToolUse (dopo ogni Edit/Write) inietta un prompt che costringe Claude a scrivere un file di razionale in <repo>/.claude/claude-archive/: «perché ho fatto questa modifica». È committato nel repo e non viene mai letto da Claude, se non su richiesta esplicita — documentazione per gli umani, on-demand (l'applicazione concreta del §7.2). Funziona, ma ha due limiti: dipende da un hook custom, e cattura il perché dopo — archeologia a valle, sulla singola edit, non sul disegno del cambiamento.

Da qui in avanti — spec-driven con openspec. openspec (github) ribalta la direzione: la spec e la proposta si scrivono prima di toccare il codice — «allineare umani e AI sui requisiti prima che inizi la scrittura». Il «perché» non si recupera più a valle: è la proposta, rivista prima, che resta nel repo come documentazione viva in markdown.

// struttura di openspec nel repo
openspec/
├── specs/                    // fonte di verità: come il sistema si comporta ORA
│   └── <dominio>/spec.md
├── changes/                  // una cartella per cambiamento proposto
│   └── <nome-cambiamento>/
│       ├── proposal.md       // <- il "perché", scritto e rivisto PRIMA del codice
│       ├── design.md         // approccio tecnico
│       ├── tasks.md          // checklist di implementazione
│       └── specs/<dominio>/spec.md   // delta: solo ciò che cambia
└── changes/archive/          // i cambiamenti completati finiscono qui

Ciclo: /opsx:propose (crea proposta, design, task, delta-spec) → revisione → /opsx:apply (Claude implementa contro la checklist) → /opsx:sync (fonde i delta nelle spec) → /opsx:archive. Si installa con npm i -g @fission-ai/openspec e openspec init, che genera le skill e i comandi sotto .claude/ — coerente col §6: i comportamenti stanno nel .claude, non nel CLAUDE.md.

Un subagent gira in una finestra di contesto separata e restituisce al thread principale solo il risultato. È perfetto per il lavoro che sporca il contesto: le esplorazioni («dove sono gli endpoint di autenticazione?»), le ricerche, e la review a occhi freschi prima del commit — senza il bias accumulato dalla sessione. Si creano con /agents.

Gli agent team portano l'idea oltre: più agenti coordinati che affrontano sotto-compiti in parallelo, ciascuno nel proprio contesto. La regola resta una: delega ciò che sporca il contesto, tieni nel thread principale solo la conclusione. È la stessa disciplina del §3, applicata su scala.

Una skill nasce nel progetto (§6). Per condividerla si passa dal marketplace di plugin. Il marketplace espone solo main; main ha una regola di protezione e non accetta commit diretti. Per aggiungere una skill si apre una pull request al maintainer. È l'unico modo sicuro di condividere skill: niente copie a mano che divergono, una sola versione canonica e revisionata.

Per il cowork in ufficio valgono le stesse regole, ma su un marketplace diverso (interno). Stesso meccanismo, ambito diverso.

L'analisi completa delle skill già presenti nel marketplace Sistec — 6 integrate, 14 scartate, criteri, pattern e tabella di tracciabilità — è nel documento complementare Skill marketplace — audit e criteri di integrazione.

Per la conoscenza inter-ufficio non serve inventare nulla: né un collector, né un lease Graph-ETag, né un Orchestrator con un unico scrittore. Esiste un framework universalmente noto — la wiki-LLM, il pattern di Karpathy (gist ufficiale) — e una demo funzionante è già in sistec-llm-wiki.

Il pattern è semplice: una cartella su OneDrive o NAS che tutti sincronizzano; tutti aggiungono i documenti grezzi in raw/; l'AI fa ingest e retrieval. La sincronizzazione la fa già OneDrive/il NAS. La canonicalizzazione la fa il retrieval dell'AI al momento della domanda — non un maintainer con un mutex distribuito da progettare, costruire e verificare.

Fig 4La demo sistec-llm-wiki in funzione: la struttura della cartella e la vista a grafo della conoscenza ingerita.

Vista a grafo — entità e collegamenti estratti dai documenti: progetti (progetto-atlas), persone (marco-manfrin, davide-conti…), organizzazioni (sistec, acme-spa), concetti (strangler-fig-pattern) e le fonti che li citano. Il retrieval naviga questi collegamenti.

Struttura — raw/ i documenti grezzi; wiki/ la conoscenza canonicalizzata per tipo (concetti, decisioni, fonti, organizzazioni, persone, progetti); index e log generati dall'ingest.

L'adozione non deve aspettare che tutti abbiano una licenza. Chi non ha ancora Claude può partire con opencode e modelli più semplici — meno contesto, ma gratuiti — per prendere confidenza con il ciclo agentico (§1) e con il lavoro in git (§2). Il modello mentale è lo stesso; si scala la potenza quando arriva la licenza. Nessuno resta fermo ad aspettare.

La stessa Claude si usa in tre modi. Chat è la conversazione che già conosci: domande, brainstorming, bozze. Code è ciò di cui parla tutto questo documento: costruire software nel repository. Cowork è la modalità agentica per il lavoro d'ufficio non di codice: gli dai un obiettivo, lo colleghi a cartelle e strumenti, e lavora da solo — ricerche, analisi cross-fonte, documenti finiti.

Il punto che conta per Sistec: Cowork e Code girano sullo stesso motore — sotto è Claude Code. Stessa natura agentica, stessi subagent (§8), stessa capacità di sostenere compiti lunghi. Cambia la superficie, non il motore. Chi in ufficio non scrive codice non parte da zero: usa lo stesso modello mentale del ciclo agentico (§1), su cartelle e documenti invece che su un repository.

Il ciclo agentico (§1) si chiude solo quando i risultati sono verificabili. Senza un criterio di verifica, Claude non sa se ha finito: indovina, produce codice plausibile ma non provato, e il ciclo si chiude per esaurimento del contesto, non per successo. Il modo più efficace per migliorare la qualità dell'output è dare a Claude un modo eseguibile di verificare sé stesso.

13.1 Cosa rende un criterio di verifica efficace

Tre caratteristiche, in ordine di potenza:

1. Eseguibile. Un comando che Claude può lanciare e di cui può leggere l'uscita — npm test, dotnet build, ruff check. La build che passa è la forma più forte di verifica.
2. Osservabile. Una regola che Claude può controllare leggendo un file — «la funzione accetta numeri negativi?», «tutte le traduzioni hanno il placeholder {name}?». Si verifica con un grep o un read, non con un test.
3. Descrittivo. Una condizione scritta nel prompt — «il bottone dev'essere blu, non verde» — che Claude valuta a vista. È la forma più debole: funziona, ma non chiude il ciclo da sola.

13.2 Verifica nel piano, non nel codice

Il criterio di verifica va stabilito prima di scrivere codice, nel piano (§5). Se aspetti che Claude abbia finito per controllare, scoprirai errori quando costa di più correggerli. In fase di piano chiedi: «come facciamo a sapere che è fatto bene?». La risposta è il criterio di verifica — e va scritto nel prompt, non tenuto in testa.

Non tutto va delegato a un agente. Claude Code è potente, ma ci sono cose che si fanno meglio e più veloce senza. Saperle riconoscere è parte dell'adozione matura — non è un fallimento dello strumento, è saperlo usare al posto giusto.

14.1 Cosa fare a mano

• Task meccanici e locali. Rinominare una variabile in 2-3 file? Un IDE lo fa in 5 secondi con refactor → rename. Claude ci impiega di più a capire il contesto.
• Operazioni deterministiche su larga scala. Sostituire un pattern in 50 file? sed o rg --replace in shell. Con Claude devi descrivere il pattern e verificare ogni file. Linea di comando: 1 secondo. Agente: 5 minuti.
• Una trasformazione dati una tantum. Convertire un CSV, plottare una curva, estrarre un campo da JSON annidato. Una riga di Python o jq è più veloce che descrivere il problema a Claude, aspettare che scriva lo script, eseguirlo e verificare il risultato.
• Quando sai esattamente cosa fare. Se hai già la soluzione in testa — cambi una stringa, aggiungi un import, modifichi una costante — scrivila. Il giro prompt→attesa→verifica è più lento della scrittura diretta. Claude Code non è una bacchetta magica: è uno strumento per quando non sai già la risposta.

14.2 Il test del minuto

Regola pratica: se puoi fare la cosa in meno di un minuto a mano, falla a mano. Se ti serve più di un minuto di descrizione, probabilmente Claude è la scelta giusta. Il punto di pareggio è intorno ai 30 secondi di digitazione vs 30 secondi di prompt — ma il prompt richiede verifica, la digitazione no.

14.3 Cosa evitare del tutto

• Auto-approvare in produzione. Mai lasciare Claude scrivere su branch di produzione senza review. Git è la rete di sicurezza (§2), ma la review umana resta obbligatoria sui cambiamenti critici.
• Sessioni senza criterio di verifica. Se non sai dire «fatto», Claude non lo sa nemmeno. Le sessioni senza verifica sono le più costose in token e le meno produttive.
• Usare Claude per imparare un framework. Se non conosci il dominio, non riconosci quando Claude sbaglia. Prima studia, poi delega. Claude è un acceleratore di competenza, non un sostituto.

Da stampare o tenere aperto in una scheda. Il minimo indispensabile per lavorare con Claude Code.

Prima di Claude Code viene Claude. Il corso ufficiale AI fluency — undici lezioni su claude.ai, dai fondamenti all'uso per ruolo — copre chat, progetti, artifact, skill, connettori e la modalità Research. È la base per chi non è sviluppatore, e il ponte verso Claude Code (§12). Disponibile come dispensa a parte: l'elenco delle lezioni a sinistra, il testo completo di ogni lezione a destra.

Il corso Claude Code — dodici lezioni, dai fondamenti agli hook — è disponibile come dispensa a parte: l'elenco delle pagine sulla sinistra, il testo completo di ogni lezione a destra, una pagina per markdown. Si apre in una pagina dedicata, fuori dal flusso di questo documento.