Architettura
strumenti
Come sono costruiti e collegati tutti gli strumenti AI dentro PROGETTI AI. Un pattern comune a ogni progetto: Claude Code fa il lavoro, una persona controlla e decide. Un solo modo di lavorare, riusato ovunque.
In una frase, e a chi serve
Cos'è. La cassetta degli attrezzi condivisa da tutti i progetti di PROGETTI AI. Non un singolo software: l'insieme di scelte tecniche che si ripetono su ogni progetto - stesso motore, stessi principi, stessa cartella iCloud.
Il problema che risolve. Senza uno standard, ogni progetto sarebbe fatto in modo diverso e incoerente. Con un'architettura comune, chi impara un progetto capisce anche gli altri: cambia il contenuto, non il modo di lavorare.
Perché è fatto così. Tutto gira in locale sull'abbonamento di Claude, senza API key da pagare o custodire, e con l'umano che approva prima di pubblicare o inviare. Facile da capire e da mettere le mani.
- TomasUsa gli stessi strumenti su ogni progetto, senza reimparare tutto da capo ogni volta.
- Collaboratore tecnicoCapisce il pattern una volta sola e lo ritrova identico in ogni progetto della cartella.
- ClienteRiceve output preparati dall'AI ma sempre controllati da una persona reale prima di uscire.
Stack e strumenti
| Strumento | Ruolo nel progetto | Perché scelto |
|---|---|---|
| Claude Code motore | Fa il lavoro: in chat, o headless (claude -p) come sottoprocesso di uno script. | Usa l'abbonamento: zero costo extra, nessuna API key da gestire. |
| Python colla | Lega gli strumenti: legge l'input, chiama Claude, scrive l'output. | Una lingua sola, semplice da leggere e da modificare. |
| iCloud Drive sync | Ospita tutti i progetti e li sincronizza tra Mac e PC Windows. | Stesso file su due dispositivi, con percorsi relativi. |
| Notion hub | Raccoglie dati condivisi e board (hub social, questi vademecum). | Editabile da browser, condivisibile con un semplice link. |
| Composio connettori | Collega app esterne (Instagram, Gmail) a Claude Code. | Autenticazione gestita, niente integrazioni scritte a mano. |
| GitHub Actions cron | Fa girare bot pianificati (es. Telegram) senza PC acceso. | Gratis per repo piccoli, schedulazione già integrata. |
OAuth + secrets/ accesso | Login alle API (Gmail, Google), con token salvato in locale. | Lo script gira per conto suo, fuori dalla chat. |
I progetti sotto l'architettura
| Progetto | Cosa fa | Motore |
|---|---|---|
| Automazione Social AL | Crea e ricicla contenuti social per più clienti. | Claude Code + skill |
| Mail Automation | Prepara bozze di risposta in Gmail nel tuo stile. | claude -p + Gmail API |
| Preventivi AI | Preventivi e deck con prezzi (es. Food Lab Experience). | Claude Code |
| Configuratori AI | Configuratore prodotto (tool-vernici). | HTML/JS + Claude |
| Siti Web Evolution | Landing per clienti da un motore di temi. | motore-landing |
| Storytelling | Sito e blog di storytelling per AL. | HTML + Claude |
Come funziona - il flusso
Ogni progetto, diverso nel contenuto, segue lo stesso schema: input → il motore elabora → bozza → una persona approva → esce. L'ultimo passo è quasi sempre manuale, di proposito.
Input
Dati grezzi: mail non lette, brief, profilo cliente, foto di un lavoro.
datiMotore
Claude Code elabora, in chat o headless lanciato da uno script.
claude -pBozza
Produce un output di bozza: testo, slide, preventivo, contenuto.
outputApprova
Una persona rilegge e corregge. Questo passo non si salta mai.
umanoPubblica / Invia
Caricato o inviato a mano, oppure da un cron esplicitamente autorizzato.
manualeprocessed.json), così rilanciare non crea doppioni.Mappa cartelle di PROGETTI AI
| Cartella | Contenuto |
|---|---|
SOCIAL FORMAT/AUTOMAZIONI/ | Motore social multi-cliente (skill + dati clienti). |
MAIL AUTOMATION/ | Agente bozze Gmail: Python + claude -p. |
PREVENTIVI AI/ | Preventivi e deck (es. Food Lab Experience). |
CONFIGURATORI AI/ | Configuratori prodotto (tool-vernici). |
SITI WEB EVOLUTION/ | Landing clienti + motore-landing con temi. |
STORYTELLING/ · VADEMECUM/ | Sito/blog storytelling AL · questi dossier di onboarding. |
Onboarding collaboratore + spiegazione cliente
Da zero a produttivo
- Installa Claude Code e accedi con l'abbonamento: nessuna API key da comprare o custodire.
- Apri la cartella PROGETTI AI da iCloud: i percorsi sono relativi, funziona uguale su Mac e Windows.
- Leggi il README del progetto che ti interessa: ognuno spiega il proprio setup passo passo.
- Prova un progetto in locale (es. Mail Automation con
python run.py) prima di toccare i dati veri.
Le competenze minime
Python di base per leggere e lanciare gli script, dimestichezza col terminale, e la capacità di distinguere l'ambiente di test da quello di produzione. Non serve costruire modelli AI: il motore è già Claude Code.
Regola d'oro: mai committare segreti. Token e credentials.json stanno solo in secrets/ locale, mai nel repo.
"Usiamo l'intelligenza artificiale come un assistente veloce che prepara il lavoro - bozze di mail, contenuti, preventivi - ma è sempre una persona a controllare e a decidere cosa esce davvero."
Ottieni la velocità dell'AI senza perdere il controllo né la qualità: niente va verso l'esterno senza un'approvazione umana.
- Niente invii automatici. Nessuno strumento pubblica o invia senza l'approvazione di una persona.
- Mai segreti nel repo. Token e credenziali restano solo in locale, dentro
secrets/. - Prima il test. Di default si lavora su dati e ambiente di prova, mai in produzione senza richiesta esplicita.
Paletti, limiti e stato
Da fare più avanti
| Cowork | In panchina: non serve ora, si valuta se il carico di lavoro cresce. |
| Standardizzazione | Portare tutti i progetti allo stesso schema di cartelle e README. |
| Vademecum | Completare il dossier di onboarding per ogni progetto grosso. |