Knowledge She Doesn't Know · Quick Reference

Glossary tech + Sharkcode patterns + anti-mistakes + decision rules. Lo apri cuando no entendés algo, sin verguenza.

Atelier Noelia · Wave 5 cheat sheet "cosas che lei non sa" · 2026-05-24

1. Tech glossary base

~30 termini tech che useras Day 1+ con Claude. Si NO entendés uno, abri este cheat sheet.

Git basics (los más críticos)

repo (repository)

Cartella codice tracciata da Git. Ha history (chi ha cambiato qué cuando) + branches + remote.

branch

Linea di sviluppo parallela. Tu su noelia-etsy-launch, Michel su main. Modifiche tue NON impattano main fino a merge.

commit

Snapshot de las tue modifiche con messaggio descrittivo. Es. git commit -m "feat: primer listing". Locale finche push.

push

Sube i tuoi commit local al remote GitHub. Altri (Michel) vedono solo después push.

pull

Baja commits del remote nel tuo local. Da fare PRIMA di push se altri tienen pushato.

merge

Combina 2 branch in 1 (es. noelia-etsy dentro main). Auto se file diversi, manual se conflict.

conflict

Git non puo auto-mergere perche entrambi avete editado stessa linea. Tu decidi manualmente quale resta.

clone

Scarica repo remote nel tuo local prima volta. Es. git clone git@github.com:Michel9329/sharkcode.git.

remote (origin)

Server GitHub dónde vive il repo "ufficiale". origin = nickname remote tuo (default).

SSH key

Chiave crittografica che identifica te a GitHub (NO password). Generata Day 0 prep + aggiunta GitHub Settings.

Collaborator

Tu invitata da Michel ai repo Sharkcode + Wedding-Templates. Write access = puoi push.

PR (Pull Request)

Richiesta merge controllato tuo branch a main. Michel reviews + approva + merge.

Tool + workflow

deploy

Pubblicare site online (es. Cloudflare Pages atelier-noelia.pages.dev). Automatic post-commit push.

env var

Variabile d'ambiente (es. TAVILY_API_KEY) usata da app sin hard-code in codice. Setup via zshrc.

API

Application Programming Interface. Modo standardizzato per app comunicare (es. Etsy API per liste).

MCP (Model Context Protocol)

Anthropic standard per connettere Claude a tool esterni (Sanity + Tavily + ecc.). 20 server configurati.

hook

Script che gira automatic prima/después azioni Claude Code. Es. auto-retrieval-preload inietta memorie pre-risposta.

agent (sub-agent)

Claude specializzato spawned task-specific (es. sharkcode-brand). 47 agenti OS disponibili Day 1.

skill

Capability modulare Claude (es. impeccable per UI critique). 83 project skill + Tier 3 user-scope.

plugin

Estensione Claude Code installata via marketplace (es. typescript-lsp). Day 30+ opzionali.

slash command

Comando rapido /xxx in Claude chat. Es. /run-pipeline. Vedi cheat sheet completa.

pipeline

Sequenza fasi cliente Sharkcode OS (lead → proposal → contract → brand → design → build → ecc.).

Stack tecnico Sharkcode

Bun

JavaScript runtime moderno (alternative Node.js, piu veloce). Usato Sharkcode main + tools.

Node.js

JavaScript runtime classico. Usato per alcuni script + hook.

pnpm

Package manager (alternative npm/yarn) usato Wedding-Templates monorepo workspace.

Astro

Framework site statici premium. Stack default cliente Sharkcode (portfolio + landing).

Sanity CMS

Headless CMS dónde cliente edita content. Stack default Sharkcode (NO WordPress).

Cloudflare Pages

Hosting siti statici globale fast. Stack default cliente (atelier-noelia.pages.dev aquí).

VSCode

Editor codice Microsoft. Tu lo usi Day 1 con Claude Code dentro.

Claude Code

CLI Anthropic per integrare Claude in workflow developer. Tu lo lanci dentro VSCode.

2. Sharkcode-specific patterns

15 patterns Sharkcode che NO esistono standard developer. Lei deve conoscerli + applicarli.

🤝 Pair-mode (lei + Michel + Claude)

Workflow 3-persona: tu dirigi ES + Michel supervisiona + Claude esegue tecnico. Day 1 setup MacBook + Welcome Tutorial = pair-mode pieno. Day 30+ task specifici pair-mode con Michel.

🔄 Pipeline OS `/run-pipeline {client} {fase}`

Entry point obbligatorio per qualsiasi deliverable cliente. NO spawn agenti isolati. Pipeline orchestra automatic team OS + tracking + dashboard.

🌳 Scenario A branch dedicati Day 1 (D1)

Tu su branch noelia-XYZ, Michel su main. Merge controllato via PR. Vedi GIT-WORKFLOW-COLLAB.

🧠 Memorie shared `SHARKCODE_MEMORY_DIR`

90 memorie cross-cliente accessibili Claude automatic via env var dotfile. Lei NO scrive memorie (Michel sync weekly Sunday automatic).

🔒 Protected paths + AUDIT preventivo

File critici (compile-*.ts + templates/brand/** + .claude/agents/*.md) richiedono AUDIT.md approved_by Michel prima modifica. Hook protected-paths-block bloca runtime.

🤖 Sub-agent OS spawn pattern

47 agenti specializzati (sharkcode-brand + sharkcode-design + ecc.) spawned task-specific da Claude main. Lei NO spawn agenti direct, Claude main orchestra.

🎨 Brand pipeline R0-R6

Brand identity cliente 7 round: R0 voice extraction + R0.5 site audit + R1 reposition + R2 brand strategy + R3 naming + R4 deep analysis + R5 visual identity + R6 logo prompt engineer.

🎓 Welcome Tutorial T1-T5 cadenza

Day 1 post-setup: T1 Welcome App Tour (30m) + T2 Esempi conversazionali (30m) + T3 Prompt Library (45m) + T4 Visual feedback loop (30m) + T5 Approval workflow (15m). Tot 2.5h.

🔁 Memory sync weekly Sunday 21:00 automatic

Michel Win Task Scheduler triggera cada Domenica 21:00: sync memorie + commit + push. Lunedi mattina gp ricevi memorie aggiornate Mac suo.

🔍 Topic Matches auto-injection (hook auto-retrieval-preload)

Quando scrivi prompt Claude, hook BM25 search inietta memorie + research rilevanti cómo system-reminder. Lei vede "Topic Matches" in risposta = context-aware automatic.

📦 Project scope vs user scope

Project scope (`.claude/agents/` + skills + commands + .mcp.json + CLAUDE.md) ereditato via clone. User scope (~/.claude/ Michel) NON eredita, setup separato Mac suo.

⚙️ Setup script automatic `setup-mac-user-scope.sh`

10 step Day 1 user-scope: hooks copy + settings.json + TAVILY env + markitdown-mcp override + workspace + Vscode settings + Node deps verify + knowledge-graph build + BM25 index + log rebuild.

📊 Knowledge Graph dashboard /brain

Dashboard locale Bun http://localhost:4000/brain mostra ~418 nodi (phases + research + intel + skills + agents + commands + clienti) navigabili. Wave 5 setup rebuild Day 1 automatic.

📥 Pipeline ingest PDF/EPUB → markdown

3 use case: libri research (bun run ingest:book) + intake cliente (bun run ingest:client) + intel paper (bun run ingest). MCP markitdown-mcp on-the-fly también.

📝 CLIENT DATA HANDLING verbatim

IBAN + codice fiscale + telefono + indirizzi cliente: NUNCA paraphrase, siempre copy-paste verbatim. Read-back pre-deploy. Incident 2026-05-02 IBAN errato production lezione cementata.

3. Anti-mistakes · 10 errori comuni da evitare

Errori che potresti commettere Day 1+ + cómo evitarli. Salvati la tabella mentalmente.

Force push git push --force

NUNCA. Reescribe historia remote, puede borrare commits Michel. Mai sin autorizzazione esplicita Michel.

Editar shared file sin avisar in chat

Se tocchi stato-lavoro-os.md o CHANGELOG.md o MEMORY.md shared: avisa Michel WhatsApp prima.

Branch confusion (sharkcode main vs Wedding master)

Sharkcode usa main (moderno). Wedding-Templates usa master (legacy). Sempre verifica con git branch --show-current.

Commit message format wrong (no Conventional Commits)

Usa prefisso semantico: feat(noelia-etsy): listing 1, fix(wedding): typo nav, chore(memory-sync): refresh, docs: update README. Hook conventional-commits.py blocca format wrong.

Edit protected file sin AUDIT preventivo

File cómo compile-*.ts + templates/brand/** + .claude/agents/*.md son protetti. Hook protected-paths-block ti bloca. Chiedi Michel se devi davvero modificare.

Spawn agenti isolati (NO usare /run-pipeline)

Entry point cliente siempre /run-pipeline {client} {fase}. NO chiamare sub-agent direct (es. NO "Spawn sharkcode-brand"). Pipeline orchestra automatic + tracking + dashboard.

Modify .mcp.json local sin override .mcp.json.local

.mcp.json tracked git project scope, modifiche tue Mac impatta Michel Win. Usa .mcp.json.local Mac suo (gitignored, override locale).

Forget git pull prima di git push

Sempre git pull origin <branch> PRIMA di push. Se Michel ha pushato nel frattempo, Git rifiuta tuo push fino a integri. Alias gp = git pull.

Workspace VSCode cerrado accidentale (single root mode)

Apri siempre code ~/Code/noelia.code-workspace per multi-root 5 folder (Sharkcode + Wedding + Pinna + Etsy + Atelier docs). NO code . in subfolder.

Editare codice cliente sin Claude in chat (vibe coding)

Tu NO scrivi codice raw. Sempre dici a Claude "fai X" + Claude scrive + tu reviewa visualmente browser + approvi. Pattern app-style 100%.

4. When to ask vs when to try · decision rules

3 categorie decisione: prova sola, chiedi Michel, chiedi Claude. Per ognuna esempi concreti.

✅ Prova sola (autonoma)

Comando standard documentato (git pull/push/commit)
Troubleshooting noto (vedi Troubleshooting SETUP-MACBOOK)
Decision design soft (colore palette, font weight, spacing)
Listing Etsy descrizione + tags scelta
Canva design exploratorio
Browser navigation Etsy seller dashboard

⚠️ Chiedi Michel

Decision strategica cliente (pricing, scope, kill trigger)
Cost decision (compra plan, SSD, abbonamento)
Merge branch tuo a main (PR review)
Conflict complesso che NO sai risolvere
Modifica protected path (AUDIT preventivo)
Deploy production cliente reale (signal Michel pre-deploy)
Email cliente hecha da te (Michel reviewa pre-send)

💬 Chiedi Claude (in chat)

Tech glossary "che vuol dire X?"
Comando esatto "cómo faccio Y?"
Workflow standard "qual è ottimale per Z?"
Code generation (Claude scrive, tu reviewi)
Design suggestion Wedding template
Translation IT ↔ ES ↔ EN cliente
Research competitor + content idee

Default: Claude prima: in dubbio, chiedi siempre Claude prima. Lui ti dice "fallo tu sola" OR "chiedi Michel" se appropriato. Lower friction + zero stress.