Infrastruttura di condivisione

L'infrastruttura si regge su due fonti di verità separate, ciascuna proprietaria di un tipo di contenuto diverso. Non si sovrappongono e non richiedono un orchestratore comune.

Le due fonti di verità si attivano a livello utente: due modifiche, fatte una volta su ogni PC, valide per qualunque progetto l'operatore apra dopo.

2.1 settings.json — autorizzare la lettura della wiki

La cartella della wiki sincronizzata è fuori dal repository: senza un'autorizzazione esplicita, Claude Code chiederebbe conferma ad ogni lettura. Si risolve con un allow permanente nel settings.json utente (C:\Users\<utente>\.claude\settings.json):

{
  "permissions": {
    "allow": [
      "Read(C:\\Users\\Sistec 32\\Sistec srl\\Sistec AM-AI Stack - sistec-wiki\\**)",
      "Bash(qmd:*)"
    ]
  }
}

Il percorso è quello locale della sync SharePoint/OneDrive — dipende dall'account Windows, quindi va scritto nel settings.json personale, non in quello di progetto. La seconda riga autorizza il motore di ricerca della wiki (§2.4): senza, ogni singola ricerca chiede conferma — lo stesso attrito che la prima riga elimina sulla lettura dei file.

2.2 CLAUDE.md — un paragrafo, non una skill

Perché Claude Code consulti la wiki senza doverlo ricordare a ogni sessione, basta un rimando nel CLAUDE.md utente. Un paragrafo, non una skill: la procedura di ingest/query/lint è già scritta nel CLAUDE.md della wiki stessa, qui basta indicare dove trovarla.

In "C:\Users\Sistec 32\Sistec srl\Sistec AM-AI Stack - sistec-wiki" è presente una LLM wiki aziendale
(fatti, decisioni, documenti). Consultala seguendo le regole nel suo CLAUDE.md per ottenere contesto sui
progetti a cui stai lavorando, prima di chiedere all'operatore.

2.3 skills/ — installate dal marketplace

Le skill installate dal sistec plugin marketplace (GitHub) vivono in ~/.claude/skills/ (o registrate come plugin). Stessa logica: installazione una tantum per PC, disponibili in ogni progetto senza configurazione per-repo.

2.4 qmd — l'indice di ricerca, locale e non sincronizzato

La wiki non si consulta leggendo le cartelle a tentoni: il suo CLAUDE.md prescrive qmd per ogni ricerca — BM25 su parole chiave, ricerca vettoriale semantica, reranking. qmd lavora su un indice SQLite più i modelli di embedding, e né l'uno né gli altri vivono nella cartella sincronizzata:

Setup una tantum per PC, dopo che la cartella wiki è sincronizzata:

npm i -g @tobilu/qmd
cd "C:\Users\<utente>\Sistec srl\Sistec AM-AI Stack - sistec-wiki"
qmd collection add wiki/ --name wiki
qmd update && qmd embed

Il primo embed scarica i modelli (~1,6 GB): su rete aziendale non è istantaneo. Da lì in poi tutti i comandi sono nudi — qmd search "..." — senza INDEX_PATH né altre variabili.

Claude Code viene eseguito nella cartella del repository, com'è pensato dalla documentazione ufficiale Anthropic. Dentro quella cartella non c'è nulla di condiviso tra progetti — niente skill, niente conoscenza aziendale: solo ciò che è specifico di questo repo.

• Nessuna skill — stanno nella configurazione utente (~/.claude), installate dal marketplace GitHub (§2.3).
• Nessuna conoscenza oltre al repo — decisioni, contesto, storia del progetto stanno nella wiki (§2.2), non in file locali al repository.
• .claude/rules/ — le convenzioni di scrittura del codice (naming, pattern, cosa evitare) restano nel repo, versionate con il codice che disciplinano: sono specifiche di quel progetto, non trasferibili come le skill. Esempio concreto — le rule estratte dai progetti FAEL/LAG: github.com/marc04AM/AiFormation/examples/rules.
• graphify — l'unica altra aggiunta alla cartella di progetto: mappa e indicizza il codice del repo in graphify-out/, così Claude Code può fare ricerche senza leggere ogni file del repository per orientarsi.

3.1 Eccezione: skill che devono vivere anche nel progetto

Non tutte le skill restano solo a livello utente. openspec è l'eccezione: opera su file che devono esistere dentro il repository (openspec/, openspec/changes/), quindi le sue skill (openspec-propose, openspec-apply-change, openspec-archive-change, ecc.) vanno installate anche in .claude/skills/ del progetto, non solo a livello utente. Stesso discorso per graphify: la skill è a livello utente, ma va inizializzata per-progetto (graphify-out/ nasce dentro il repo).

Guida passo-passo per inizializzare graphify e openspec su un nuovo progetto: «Iniziare un nuovo progetto con Claude Code» (OneNote, Claude AI).

La wiki non riceve solo testo: qualunque documento aziendale utile come fatto o conoscenza può finire in raw/ — email, schemi elettrici, disegni meccanici, verbali, oltre ai prodotti di analisi generati lavorando su un progetto.

4.1 Prodotti di analisi dal repository

openspec, l'output di graphify, e qualunque altro prodotto di analisi del repository sono fatti: la conoscenza che serve per ricostruire perché e come è stata presa una decisione. L'operatore li copia manualmente in raw/ della wiki e chiede l'ingest — non c'è sincronizzazione automatica tra repository e wiki.

4.2 Log e indice — generati, non scritti a mano

Durante l'ingest, la wiki produce da sola due file: log.md (registro cronologico append-only di ogni ingest/query/lint) e index.md (catalogo aggiornato di tutte le pagine). L'operatore non li mantiene: sono l'output dell'operazione di ingest definita nel CLAUDE.md della wiki.

4.3 Non solo testo

La cartella raw/ accetta qualunque formato: markdown, PDF, immagini di schemi elettrici o disegni meccanici, export di scambi email. L'ingest li legge (testo e immagini) e produce il riassunto in wiki/fonti/, aggiornando le pagine sintetiche toccate — la regola è la stessa qualunque sia il formato d'origine: nella wiki finisce il risultato dell'analisi, non il racconto di come si è arrivati lì.

Il ciclo quotidiano di lavoro è quello descritto dalla documentazione ufficiale Anthropic: si lavora dentro la cartella del repository. A questo si aggiungono due meccanismi che chiudono il ciclo verso la wiki.

5.1 Hook claude-archive — il perché e il come, a fine modifica

Il plugin marketplace/hmi-developer include la skill/hook archive: a fine di una modifica al codice, scrive un riepilogo conciso — perché è stata fatta, come è stata fatta — in .claude/claude-archive/<data>-<slug>.md, dentro al repository. È esattamente ciò che serve sapere per ricostruire una decisione senza dover rileggere il diff: candidato naturale per la copia manuale in raw/ (§4.1).

5.2 Modifiche complesse — openspec direttamente in Claude Code

Per modifiche di maggiore portata si usa openspec direttamente dentro Claude Code (skill installate anche nel progetto, §3.1): prima di implementare, produce in openspec/changes/<nome>/ gli artefatti standard — proposal.md, specs/, design.md, tasks.md. Questi file sono prodotti di analisi a tutti gli effetti (§4.1): si copiano in raw/ e si indicizzano, cosicché la decisione progettuale sopravviva al repository in cui è nata.

Le due fonti di verità in alto, la configurazione a livello utente al centro, il repository in basso — con il metodo di lavoro che chiude il ciclo copiando i prodotti di analisi in raw/.