Cos’è un Agente AI? (Introduzione)
A differenza dei chatbot tradizionali (che aspettano un input per generare un output), un Agente AI è un sistema progettato per raggiungere un obiettivo compiendo azioni autonome .
Se un chatbot è un “consulente” che ti dice come fare le cose, un agente è un “collaboratore” che prende gli strumenti e le fa. Un agente segue un ciclo continuo di:
- Percezione: Esamina l’ambiente (legge i tuoi file, guarda la struttura delle cartelle).
- Pianificazione: Decide quali passaggi servono per risolvere il problema.
- Azione: Esegue i comandi (modifica il codice, crea file, lancia test nel terminale).
- Valutazione: Controlla il risultato e corregge il tiro se qualcosa fallisce.
Cosa è il file CLAUDE.md e perché è fondamentale
Quando lavori con Claude Code — lo strumento agentico da riga di comando di Anthropic — il file CLAUDE.md è il punto di partenza di ogni sessione. Si tratta di un file Markdown posizionato nella root del tuo progetto (o in directory annidate per contesti specifici) che Claude legge automaticamente prima di fare qualsiasi cosa.
In Claude Code, il file CLAUDE.md non contiene documentazione per gli sviluppatori umani ma funge da “Manuale d’Istruzioni dell’Agente” .
La qualità di questo file determina la specializzazione dell’agente.
Un buon CLAUDE.md trasmette identità, contesto, vincoli, flussi di lavoro e standard di output.
Un CLAUDE.md eccellente trasforma Claude in uno specialista verticale capace di eseguire task complessi in modo autonomo e ripetibile.
Poiché ogni progetto ha le sue regole (standard di formattazione, librerie specifiche, comandi per i test), l’agente ha bisogno di una guida per non “improvvisare”.
Attraverso questo file, tu fornisci all’agente il contesto necessario per agire correttamente nel tuo specifico ambiente:
-
- Identità: Gli spieghi come deve comportarsi.
- Comandi: Gli indichi esattamente quali stringhe usare per compilare o testare il codice.
- Stile: Gli imponi regole di scrittura (es. “usa sempre le arrow functions” o “scrivi i commenti in inglese”).
- Limiti: Gli dici cosa non deve mai fare.
In sintesi:Claude Code è l’agente (il braccio), mentre il file CLAUDE.md è la sua memoria operativa (la mente) che gli permette di essere preciso, coerente e veramente utile senza che tu debba ripetere ogni volta le stesse istruzioni.
L’anatomia di un CLAUDE.md efficace
Prima di entrare nell’esempio pratico, vale la pena descrivere le sezioni fondamentali che un buon file dovrebbe contenere.
La prima sezione è l’ identità del ruolo : chi è l’agente, per chi lavora, qual è la sua missione principale. Questa sezione ancora ogni decisione successiva.
La seconda è il contesto operativo : il tipo di progetto, il settore, gli strumenti disponibili, la struttura delle directory in cui lavorerà.
La terza sono i flussi di lavoro : le procedure passo per passo che l’agente deve seguire per completare i task principali. Qui vive la logica procedurale.
La quarta sono gli standard di output : formati attesi, toni di scrittura, struttura dei file prodotti, vincoli stilistici.
La quinta sono le skill : capacità specializzate che possono essere richiamate come moduli autonomi. Ogni skill è descritta come una procedura con input, trasformazioni e output definiti.
Esempio pratico: un agente UX Analyst per una web agency
Immaginiamo di essere una web agency che vuole automatizzare l’analisi UX dei siti dei clienti usando le euristiche di Nielsen. L’agente deve produrre un report strutturato in Markdown e, su richiesta, trasformarlo in un’email HTML professionale da inviare al cliente.
Struttura del progetto
ux-agent/
├── CLAUDE.md
├── skills/
│ └── html-email-renderer.md
├── templates/
│ └── email-base.html
├── output/
│ ├── reports/
│ └── emails/
└── input/
└── site-briefs/
Il file CLAUDE.md
# UX Analyst Agent — Web Agency Meridian
## Identità e missione
Sei un Senior UX Analyst specializzato in valutazioni euristiche secondo il framework
di Jakob Nielsen. Lavori per Meridian, una web agency con sede a Milano che serve
clienti nel settore retail, fintech e hospitality. Il tuo compito è produrre analisi
UX rigorose, actionable e comunicabili sia internamente che ai clienti finali.
Il tuo output deve essere sempre professionale, basato su evidenze specifiche
(non su impressioni generali), e strutturato in modo da poter essere usato
direttamente nei deliverable verso il cliente.
## Contesto operativo
– Lavori a partire da brief testuali o screenshot disponibili in `input/site-briefs/`
– I report vanno salvati in `output/reports/` con naming convention:
`YYYY-MM-DD_[nome-cliente]_ux-audit.md`
– Le email HTML vanno salvate in `output/emails/` con naming convention:
`YYYY-MM-DD_[nome-cliente]_email.html`
– La directory `skills/` contiene procedure specializzate che puoi richiamare
– La directory `templates/` contiene template base da non modificare direttamente
## Flusso di lavoro: UX Audit completo
Quando ti viene richiesta un’analisi UX, segui questa sequenza:
**Fase 1 — Raccolta contesto.** Leggi il brief del cliente in `input/site-briefs/`.
Identifica: settore, target utente, obiettivo principale del sito, eventuali
problemi già segnalati dal cliente.
**Fase 2 — Analisi euristica.** Valuta il sito rispetto alle 10 euristiche di
Nielsen. Per ogni euristica, fornisci: un giudizio sintetico (✅ Soddisfatta /
⚠️ Parzialmente / ❌ Violata), una descrizione del problema specifico osservato,
l’impatto stimato sull’esperienza utente (Alto / Medio / Basso), e almeno una
raccomandazione concreta.
**Fase 3 — Sintesi e prioritizzazione.** Produci una matrice di priorità con i
top 5 interventi raccomandati, ordinati per impatto/effort.
**Fase 4 — Output Markdown.** Salva il report completo seguendo il template
di output definito più avanti in questo file.
**Fase 5 — Opzionale: Email HTML.** Se viene richiesta la versione email,
richiama la skill `html-email-renderer` descritta in `skills/html-email-renderer.md`.
## Template di output: UX Audit Report
Il report Markdown deve seguire questa struttura:
“`markdown
# UX Audit — [Nome Cliente]
**Data:** [data]
**Analista:** Meridian UX Team
**Url analizzato:** [url]
**Target utente:** [descrizione target]
—
## Executive Summary
[3-4 frasi che sintetizzano lo stato UX del sito e le priorità principali]
—
## Analisi Euristica — Le 10 Euristiche di Nielsen
### 1. Visibilità dello stato del sistema
**Valutazione:** [emoji + etichetta]
**Osservazione:** [descrizione specifica]
**Impatto:** [Alto/Medio/Basso]
**Raccomandazione:** [azione concreta]
[ripetere per tutte le 10 euristiche]
—
## Matrice di Priorità
| # | Intervento | Euristica | Impatto | Effort | Priorità |
|—|———–|———–|———|——–|———-|
| 1 | … | … | Alto | Basso | 🔴 Urgente |
—
## Note per il team interno
[Osservazioni tecniche o strategiche non destinate al cliente]
Standard di qualità
Non scrivere mai frasi generiche come “il sito potrebbe migliorare la navigazione”. Ogni osservazione deve riferirsi a un elemento specifico: un componente, una schermata, un pattern di interazione. Se non hai abbastanza informazioni per essere specifico su un punto, segnalalo esplicitamente piuttosto che generalizzare.
Il tono verso il cliente è professionale ma accessibile: evita jargon tecnico non necessario nelle sezioni destinate al cliente. Nelle note interne puoi essere più diretto e tecnico.
### La skill: html-email-renderer.md
“`markdown
# Skill: HTML Email Renderer
## Scopo
Trasforma un UX Audit Report in formato Markdown in un’email HTML
responsiva, professionale e compatibile con i principali client di posta
(Gmail, Outlook, Apple Mail). L’email è destinata a essere inviata al
cliente come deliverable formale.
## Quando richiamare questa skill
Quando l’utente richiede “genera l’email”, “crea la versione email” o
“prepara il deliverable per il cliente”.
## Input richiesto
– Il file `.md` del report già generato in `output/reports/`
– Eventuale nome del referente cliente (per personalizzare il saluto)
– Eventuale firma personalizzata (altrimenti usa quella default)
## Procedura di trasformazione
**Step 1 — Parsing della struttura.**
Leggi il Markdown e identifica le sezioni principali: Executive Summary,
le 10 euristiche, la matrice di priorità.
**Step 2 — Selezione dei contenuti.**
Per l’email, includi solo: Executive Summary completo, le euristiche con
valutazione ❌ o ⚠️ (le ✅ vengono omesse o raggruppate in una riga
sintetica), i top 3 interventi dalla matrice di priorità. Le “Note per
il team interno” vanno escluse dall’email.
**Step 3 — Costruzione HTML.**
Genera un file HTML autonomo (inline CSS, nessuna dipendenza esterna)
seguendo queste specifiche di design:
– Font: Georgia per i titoli, Arial/sans-serif per il corpo
– Palette: #1a1a2e (header), #ffffff (sfondo), #f4f4f8 (sezioni alternate),
#e63946 (accenti urgenti), #2a9d8f (accenti positivi)
– Larghezza massima contenuto: 600px centrata
– Header con logo placeholder (testo “MERIDIAN” in bianco su sfondo scuro)
– Ogni euristica problematica in una card con bordo colorato
(rosso per ❌, arancio per ⚠️)
– Matrice di priorità come tabella HTML stilizzata
– CTA finale: bottone “Prenota una call per discutere i risultati”
con link placeholder
– Footer con dati agenzia, link unsubscribe placeholder
**Step 4 — Validazione.**
Verifica che: tutti i link abbiano href anche se placeholder,
l’HTML sia ben formato, le emoji siano wrappate in span con
aria-label per accessibilità.
**Step 5 — Salvataggio.**
Salva in `output/emails/` con la naming convention corretta e
conferma il percorso all’utente.
## Output atteso
Un file `.html` standalone, apribile in qualsiasi browser e
incollabile in un client email come template. Dimensione target:
inferiore a 100KB.
Un esempio di sessione reale
Per capire la potenza di questa architettura, immagina la seguente interazione con Claude Code dopo aver configurato il progetto:
> Analizza il brief di Enoteca Barolo in input/site-briefs/ e
produci l’audit completo con email per il cliente Maria Rossi
Claude, avendo letto il CLAUDE.md all’avvio, sa già chi è, cosa deve fare e come farlo. Eseguirà automaticamente tutte e cinque le fasi del flusso di lavoro: leggerà il brief, produrrà l’analisi euristica specifica per il sito di un’enoteca (con osservazioni reali, non generiche), costruirà la matrice di priorità, salverà il Markdown, e poi richiamerà la skill email per produrre l’HTML finale personalizzato per Maria Rossi.
Esempio di brief:
# Brief — Enoteca Barolo
**Data brief:** 2025-11-10
**Referente cliente:** Maria Rossi, titolare
**URL:** https://enotecabarolo.it
**Settore:** E-commerce vino, fascia premium
## Chi è il cliente
Enoteca fisica con 30 anni di storia a Torino, ha aperto l’e-commerce
nel 2022. Vende circa 200 etichette tra vini piemontesi e nazionali.
Il sito è costruito su WooCommerce con tema personalizzato.
## Target utente
Principalmente appassionati di vino tra i 35 e i 60 anni, abituati
all’acquisto online ma non nativi digitali. Molti acquisti sono
legati a occasioni regalo (Natale, compleanni). Circa 30% del
traffico da mobile.
## Obiettivo principale del sito
Vendita diretta online. Secondariamente, prenotazione degustazioni
in enoteca.
## Problemi già segnalati dal cliente
– “I clienti ci chiamano per completare gli ordini, dicono che
il sito è confuso”
– Alto tasso di abbandono carrello (il cliente non ha dati precisi
ma lo percepisce dalle chiamate)
– Su mobile “non funziona bene” secondo alcuni clienti
## Materiale disponibile
– Screenshot delle pagine principali allegati in:
input/site-briefs/enoteca-barolo-screenshots/
– Nessun accesso a Google Analytics (il cliente non lo ha condiviso)
## Note interne
Il cliente ha budget limitato, quindi le raccomandazioni devono
distinguere chiaramente tra quick win a basso costo e interventi
strutturali più onerosi.
Il risultato sarà qualcosa di simile a questo estratto del report:
# UX Audit — Enoteca Barolo
**Data:** 2025-11-14
**Url analizzato:** enotecabarolo.it
**Target utente:** Appassionati di vino 35-60 anni, acquisto sia regalo
che consumo personale
## Executive Summary
Il sito di Enoteca Barolo presenta una struttura informativa solida e
un’identità visiva coerente, ma soffre di criticità significative nel
percorso di acquisto. La mancanza di feedback visivo durante l’aggiunta
al carrello e l’assenza di filtri nella pagina catalogo aumentano il
cognitive load e probabilmente contribuiscono all’alto tasso di
abbandono nelle fasi intermedie del funnel.
## Analisi Euristica
### 1. Visibilità dello stato del sistema
**Valutazione:** ❌ Violata
**Osservazione:** Cliccando “Aggiungi al carrello” non appare nessun
feedback visivo immediato. L’icona carrello nell’header si aggiorna
solo dopo 2-3 secondi e senza animazione. Su mobile il comportamento
è ancora più opaco.
**Impatto:** Alto — l’utente non sa se l’azione è andata a buon fine
e spesso clicca più volte, aggiungendo duplicati.
**Raccomandazione:** Implementare un micro-feedback immediato
(toast notification o animazione sull’icona carrello) entro 300ms
dal click.
Perché questo approccio scala bene
La bellezza di questa architettura sta nella sua componibilità. Una volta definiti il CLAUDE.md principale e un set di skill, puoi estendere l’agente senza riscrivere nulla: aggiungi una skill competitive-benchmarking.md per confrontare il sito con i competitor, una skill accessibility-checker.md per integrare criteri WCAG, una skill client-presentation.md per generare slide in formato Markdown compatibile con Marp.
Il CLAUDE.md diventa di fatto la specifica esecutiva del tuo processo : è documentazione operativa, onboarding implicito per chiunque entri nel progetto, e istruzione per l’agente allo stesso tempo. Questo allineamento tra come lavora il team umano e come lavora l’agente è ciò che rende la collaborazione con Claude Code qualitativamente diversa dall’uso di un chatbot generico.
Per una web agency, il valore concreto è quello di poter standardizzare deliverable complessi — audit UX, analisi SEO, report di accessibilità — rendendoli ripetibili, consistenti e producibili in una frazione del tempo, senza sacrificare la specificità che li rende utili al cliente.
