Come creare davvero il tuo primo agente AI con Claude Code (Corso completo per principianti)

impara come installare Claude Code, scrivere il tuo primo agente da zero e ottenere qualcosa di concreto: un agente funzionante che legge una cartella, individua i problemi e scrive un report, senza alcuna esperienza di programmazione.

un chatbot aspetta che tu faccia una domanda e risponde. un agente AI è diverso: gli dai un obiettivo, e lui capisce i passaggi, legge i file, esegue comandi e agisce autonomamente fino a quando il lavoro non è completato. non stai guidando ogni singola mossa. stai impostando la destinazione.

questa distinzione è importante perché cambia ciò che puoi automatizzare. non stai scrivendo prompt uno alla volta. stai costruendo qualcosa che fa il lavoro mentre tu ti concentri su altro.

Cosa ti serve prima di iniziare

ecco tutto ciò di cui hai bisogno prima di toccare un singolo comando:

• un account Claude con un piano a pagamento (Pro a $20/mese è il minimo; Claude Code è incluso)

• un Mac con macOS 13 o successivo, o un PC Windows, o un computer Linux

• una connessione internet

• circa 30-45 minuti per la configurazione completa e la prima build

nessuna esperienza di programmazione richiesta. ogni comando in questa guida è scritto per intero. copi, incolli e premi Invio.

costo per seguire questa guida: $0 oltre al tuo abbonamento. Claude Code è incluso in tutti i piani Claude a pagamento.

Installa Claude Code (Tramite App Desktop, Nessun Terminale Richiesto)

il percorso più semplice per un principiante è l'app desktop. ti offre tutta la potenza di Claude Code senza dover prima imparare i comandi del terminale.

vai su claude.ai e scarica l'app desktop per la tua piattaforma. su macOS, apri il file .dmg e trascina Claude nella cartella Applicazioni. su Windows, esegui l'installer. avvia l'app, accedi con il tuo account Claude e clicca sulla scheda Code al centro della parte superiore dello schermo.

se la scheda Code ti chiede di aggiornare il tuo piano, il tuo piano attuale non include Claude Code. se ti chiede di accedere online, completa l'accesso e riavvia l'app. in ogni caso, una volta dentro, ti ritroverai in un'area di lavoro pulita.

come riconoscere il successo: vedi una casella di prompt vuota con una scheda Code attiva e nessun messaggio di errore. questa è la tua area di lavoro per l'agente. tutto ciò che costruisci vive qui.

Cosa costruirai

costruirai un agente specifico e lo utilizzerai per tutta questa guida.

il compito dell'agente: leggere una cartella di file di testo, trovare qualsiasi file a cui manca una riga di titolo all'inizio e scrivere un report chiamato missing-titles.txt elencando ogni file che necessita di correzione.

questo è un compito reale e utile. mostra ogni comportamento fondamentale dell'agente: leggere file, prendere decisioni e scrivere output. ed è abbastanza semplice da verificare a occhio quando funziona.

Passo 1: Crea la tua cartella di lavoro

crea una nuova cartella sul tuo Desktop chiamata my-agent. qui è dove l'agente lavorerà. può vedere e toccare solo i file all'interno di questa cartella, il che mantiene tutto sicuro e contenuto.

all'interno di my-agent, crea una seconda cartella chiamata articles. qui è dove l'agente cercherà i file da controllare.

ora crea quattro file di testo semplice all'interno di articles. chiamali post-one.txt, post-two.txt, post-three.txt e post-four.txt. aprine due e aggiungi questa come primissima riga:

1Title: My Article

lascia gli altri due file completamente vuoti. il compito dell'agente è trovare quelli vuoti.

come riconoscere il successo: la struttura della tua cartella è my-agent/articles/ e contiene quattro file .txt, due con una riga di titolo e due senza.

Passo 2: Scrivi il file di istruzioni CLAUDE.md

CLAUDE.md è un file di testo semplice che Claude Code legge all'inizio di ogni sessione. sono le istruzioni permanenti del tuo agente, l'equivalente di una descrizione del lavoro che non dimentica mai.

all'interno della cartella my-agent (non dentro articles), crea un nuovo file chiamato CLAUDE.md. aprilo con qualsiasi editor di testo, incluso Blocco note su Windows o TextEdit su Mac, e incolla esattamente questo:

1# My File Checker Agent
2
3## Il tuo lavoro
4
5Controlla ogni file .txt all'interno della cartella /articles.
6
7## Cosa cercare
8
9Un file valido inizia con una riga che recita esattamente: Title:
10
11Se la prima riga non inizia con "Title:", al file manca il titolo.
12
13## Cosa fare
14
151. Leggi ogni file .txt in /articles uno per uno.
16
172. Annota quali file non hanno la riga Title.
18
193. Scrivi un file chiamato missing-titles.txt nella cartella principale.
20
214. In quel file, elenca ogni nome di file che non ha superato il controllo, uno per riga.
22
235. Se tutti i file superano il controllo, scrivi "All files have titles." in missing-titles.txt.
24
25## Cosa non fare
26
27Non modificare nessuno dei file degli articoli. Solo lettura. Scrivi solo su missing-titles.txt.

salva il file. questo è l'intero cervello del tuo agente. Claude Code lo leggerà prima di fare qualsiasi cosa.

come riconoscere il successo: hai un file in my-agent/CLAUDE.md e contiene le istruzioni sopra.

Passo 3: Punta Claude Code alla tua cartella

apri l'app desktop Claude Code e clicca sull'icona della cartella o sull'opzione "Apri cartella" per navigare fino alla tua cartella my-agent. selezionala e conferma.

Claude Code leggerà automaticamente il tuo file CLAUDE.md. non vedrai un messaggio di conferma per questo, avviene silenziosamente in background ogni volta che apri una cartella.

se stai usando il terminale invece dell'app desktop, apri il tuo terminale ed esegui:

1cd ~/Desktop/my-agent
2claude

il comando cd significa "cambia directory." ti sposta nella tua cartella my-agent. digitare claude avvia la sessione dell'agente da quella cartella.

Passo 4: Esegui l'agente

nella casella del prompt in fondo all'interfaccia di Claude Code, digita esattamente questo:

1Leggi ogni file .txt nella cartella articles. Trova qualsiasi file a cui manca una riga Title all'inizio. Scrivi i risultati in missing-titles.txt come indicato in CLAUDE.md.

premi Invio. guarda cosa succede.

Claude Code ti mostrerà il suo lavoro mentre viene eseguito: quali file sta leggendo, cosa trova in ciascuno e cosa scrive. questa trasparenza è intenzionale. puoi vedere ogni azione prima che accada e fermarla se qualcosa sembra sbagliato.

come riconoscere il successo: Claude legge quattro file, identifica due senza titolo e crea missing-titles.txt nella tua cartella my-agent. apri quel file e dovresti vedere i due nomi di file elencati, uno per riga.

Errore comune da principiante: L'agente dice di aver finito ma il file è vuoto

questo accade quando l'agente scrive missing-titles.txt ma in realtà non ci mette nulla dentro. la causa è quasi sempre un'istruzione CLAUDE.md troppo vaga.

la soluzione: apri CLAUDE.md e rendi le istruzioni di output più esplicite. invece di "elenca i file", scrivi "scrivi ogni nome di file sulla propria riga, in questo modo: post-two.txt." esempi concreti nelle tue istruzioni producono output concreti ogni volta.

se l'agente scrive i nomi di file sbagliati o ne salta uno, controlla che i tuoi file articolo abbiano effettivamente estensione .txt e non .txt.txt, cosa che può succedere su Windows quando le estensioni dei file sono nascoste. attiva "mostra estensioni file" nelle impostazioni di Esplora file per controllare.

Passo 5: Verifica ed estendi

apri missing-titles.txt e conferma che elenchi esattamente i due file che hai lasciato vuoti. se lo fa, il tuo agente ha funzionato correttamente dall'inizio alla fine.

ora hai un agente funzionante. vive in my-agent, legge da CLAUDE.md e può essere eseguito ogni volta che inserisci nuovi file nella cartella articles e lanci lo stesso prompt.

il chiaro passo successivo: aggiorna CLAUDE.md per controllare anche che ogni file sia più lungo di cinque righe. aggiungi questo sotto "Cosa cercare":

1Un file valido ha anche più di 5 righe di contenuto.
2
3Se un file ha 5 righe o meno, segnalo come "troppo corto" insieme al controllo del titolo.

esegui di nuovo l'agente con lo stesso prompt. ora controllerà due cose invece di una, senza modifiche al tuo prompt, solo una modifica al file di istruzioni.

Cosa hai appena costruito e perché è importante

hai costruito un agente che legge file, prende decisioni e scrive output, senza che tu supervisioni ogni passaggio. questo è lo schema fondamentale dietro ogni agente più avanzato che costruirai mai.

il file CLAUDE.md è la parte che scala. ogni nuova regola, nuovo controllo o nuovo formato di output che aggiungi lì cambia ciò che l'agente fa senza che tu cambi il modo in cui lo esegui. il prompt rimane lo stesso. le istruzioni si evolvono.

da qui, le estensioni naturali sono: controllare più tipi di file, scrivere il report in un formato diverso come CSV, o eseguire il controllo su base programmata usando la funzione Routines integrata di Claude Code.

domande su un passaggio? lasciale qui sotto.