chore(claude): architettura base .claude — skill preventivo e audit, hook di guardia, piani nel repo
La cartella aveva dentro solo rules/ e i settings: nessun posto dove mettere una skill, un hook o un piano. Ora ha lo scheletro completo e un .claude/CLAUDE.md che spiega cosa va dove — non duplica CLAUDE.md di progetto, che resta quello che comanda. Due skill locali (le altre restano globali in ~/.claude/skills/): - /preventivo — la catena agent.ts → schema.ts → assemble.ts → ProposalDeck e i tre modi di romperla, di cui uno solo fa rumore. Nessun prompt di generazione qui dentro: quello vive in agent.ts ed e' l'unico. Porta check-profilo.sh. - /audit — guida scripts/audit-fonti.ts, nuovo, che mette in moto le cinque fonti di src/lib/audit/sources/, in prod dal 2026-08-19 ma mai chiamate da nessuno. Provate su giojello.com: 5 su 5, 42,7 s, PageSpeed mobile 58 / desktop 93. Due hook, provati a mano (6 casi il primo, 5 il secondo): - guardia-migration.sh BLOCCA l'SQL distruttivo sulle entita' protette — il vincolo Data Safety (LOCKED) fatto rispettare dalla macchina invece che dalla memoria. - guardia-token.sh AVVISA sulle classi Tailwind grezze. Non blocca: con ~450 occorrenze di debito, bloccare lo renderebbe un ostacolo da disattivare. I tre piani di v2.5 entrano nel repo: stavano solo in ~/.claude/plans/ e STATE.md avvertiva che senza quelli la milestone non era ricostruibile. Passati al setaccio per credenziali prima di committarli. Corretta in rules/memory-discipline.md la chiave della memoria persistente: e' …-Vault-IAMCAVALLI-hub, non quella del workspace. Sedici file stavano nella prima, la regola indicava la seconda. Impeccable resta abilitato solo a livello globale: fuori da settings.json locale. Nessun tocco al prodotto. Build e lint verdi, lint identico al baseline. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# `.claude/` — la cartella di configurazione di ClientHub
|
||||
|
||||
Questo file si carica quando si lavora **dentro `.claude/`**. Spiega cosa va dove, e basta.
|
||||
|
||||
**Per il progetto comanda [`../CLAUDE.md`](../CLAUDE.md)**: stack, vincoli LOCKED, procedura
|
||||
di deploy, accesso al DB, design system. Qui non si duplica niente di quello — una seconda
|
||||
copia è il modo più veloce per averne due che si contraddicono.
|
||||
|
||||
## Cosa va in ogni cartella
|
||||
|
||||
| Cartella | Cosa ci va | Cosa **non** ci va |
|
||||
|---|---|---|
|
||||
| `rules/` | Regole caricate per contesto. Oggi: `memory-discipline.md`, importata da `../CLAUDE.md` | Documentazione di feature — quella sta in `STATUS.md` |
|
||||
| `skills/` | **Solo** skill specifiche di ClientHub: `preventivo/`, `audit/` | Le skill globali (`/seo-audit`, `/copywriting`, `/docx`…) — stanno in `~/.claude/skills/` |
|
||||
| `agents/` | **Solo** agenti specifici di ClientHub. Oggi vuota: quello dell'audit nasce col motore | I 18 agenti globali di `~/.claude/agents/` |
|
||||
| `hooks/` | Script eseguibili richiamati da `settings.json` | Logica di prodotto |
|
||||
| `plans/` | I piani delle milestone, versionati | Piani usa-e-getta di una singola sessione |
|
||||
| `commands/`, `workflows/`, `projects/` | Vuote per ora, sono lo scheletro | — |
|
||||
| `memory/` | Appunti di lavoro versionati nel repo | **La memoria persistente. Non è qui** → vedi sotto |
|
||||
| `worktrees/` | Generata dagli strumenti | — |
|
||||
|
||||
### Agenti e skill globali non si copiano qui
|
||||
|
||||
Regola già fissata in [`../../CLAUDE.md`](../../CLAUDE.md): agenti e skill che valgono per
|
||||
tutti i progetti vivono in `~/.claude/` e si invocano da qualunque cartella. Copiarne uno qui
|
||||
crea due file destinati a divergere, e il primo a cambiare vince a caso.
|
||||
|
||||
In locale ci va solo ciò che **senza questo repo non ha senso**: le due skill qui sotto.
|
||||
|
||||
### `.claude/memory/` ≠ memoria persistente
|
||||
|
||||
Due posti diversi con lo stesso nome, e confonderli fa perdere il lavoro:
|
||||
|
||||
- **`.claude/memory/`** (questa cartella) — appunti versionati nel repo, li vede chiunque
|
||||
faccia clone.
|
||||
- **`~/.claude/projects/-Users-simonecavalli-Vault-IAMCAVALLI-hub/memory/`** — la memoria
|
||||
persistente vera, un file per fatto più `MEMORY.md` come indice. Sta fuori dal repo, non
|
||||
si committa, e viene iniettata in automatico a inizio sessione.
|
||||
|
||||
Ci va quello che **non si deduce dal repo**: perché una decisione è stata presa, un vincolo
|
||||
operativo, una cosa provata che non funziona. Regole complete in
|
||||
[`rules/memory-discipline.md`](rules/memory-discipline.md).
|
||||
|
||||
## Le skill del progetto
|
||||
|
||||
- **`/preventivo`** — l'attrezzo per lavorare sulla pipeline che genera i preventivi
|
||||
(`src/lib/proposal/`) senza romperla. Non contiene un prompt di generazione: quello vive
|
||||
in `agent.ts` ed è l'unico.
|
||||
- **`/audit`** — fa girare le cinque fonti di `src/lib/audit/sources/` su un URL e dice cosa
|
||||
è stato **misurato** e cosa no. Le fonti sono in produzione ma inerti: nessuna route le
|
||||
chiama ancora.
|
||||
|
||||
## Gli hook attivi
|
||||
|
||||
Tutti e tre in [`settings.json`](settings.json). Si provano a mano prima di fidarsi.
|
||||
|
||||
| Hook | Quando | Cosa fa |
|
||||
|---|---|---|
|
||||
| Promemoria memoria | `Stop` | Se `src/` o `.planning/` hanno modifiche non committate, ricorda di aggiornare `STATE.md`. Non blocca |
|
||||
| [`guardia-migration.sh`](hooks/guardia-migration.sh) | `PreToolUse` su Write/Edit in `src/db/migrations/` | **Blocca** l'SQL che cancella dati dalle entità protette (`clients`, `projects`, `payments`, `phases`). È il vincolo Data Safety LOCKED fatto rispettare dalla macchina |
|
||||
| [`guardia-token.sh`](hooks/guardia-token.sh) | `PostToolUse` su `.tsx`/`.css` | **Avvisa** se compaiono classi Tailwind grezze o hex letterali. Non blocca: le eccezioni sanzionate esistono e stanno nella whitelist dello script |
|
||||
|
||||
Per provarli senza passare da Claude:
|
||||
|
||||
```bash
|
||||
echo '{"tool_input":{"file_path":"src/db/migrations/9999_x.sql","content":"DROP TABLE payments;"}}' \
|
||||
| .claude/hooks/guardia-migration.sh; echo "exit=$?" # atteso: 2
|
||||
|
||||
echo '{"tool_input":{"file_path":"src/x.tsx","content":"<div className=\"bg-slate-100\"/>"}}' \
|
||||
| .claude/hooks/guardia-token.sh; echo "exit=$?" # atteso: 0 + avviso
|
||||
```
|
||||
|
||||
## I piani
|
||||
|
||||
`plans/` contiene i piani della milestone v2.5, portati dentro il repo il 2026-08-26 perché
|
||||
stavano solo in `~/.claude/plans/` e `STATE.md` avvertiva che senza quelli la milestone non
|
||||
era ricostruibile. Dettaglio in [`plans/README.md`](plans/README.md).
|
||||
Reference in New Issue
Block a user