Le repo di GitHub spiegate a chi parte da zero: il manuale di bordo degli agenti AI
Una repo GitHub ordinata, con file come CLAUDE.md e skill scritte in linguaggio semplice, è il manuale di benvenuto che un agente AI come Claude Code legge per capire come lavorare in azienda. La guida spiega cosa sono repo, commit e branch, e perché istruzioni chiare scritte una volta restano valide per sempre.
PlayGuide: oggi rendiamo semplice GitHub.
In due righe
Una repo (repository) è una cartella di progetto custodita su GitHub che ricorda ogni modifica mai fatta. Per un agente AI come Claude Code è molto di più: è il posto dove trova il lavoro da fare e le istruzioni su come farlo. Se la repo è in ordine, l'agente lavora bene. Se è un caos, l'agente si perde.
Immaginate il primo giorno di lavoro
Partiamo da una scena che conoscete.
Arriva un nuovo collega. È bravissimo, velocissimo, conosce mille linguaggi. Ma non sa niente della vostra azienda: dove stanno i file, quali regole seguite, cosa non va mai toccato. Che cosa gli date? Un manuale di benvenuto, le procedure, la cassetta degli attrezzi.
Ecco: Claude Code è quel collega. E la repo è il suo ufficio, con il manuale già sulla scrivania.
GitHub, Git, repo: mettiamo ordine
Git è il "registro delle versioni": fotografa il progetto a ogni modifica, così si può sempre tornare indietro.
GitHub è il sito che ospita questi progetti online, li rende condivisibili e permette di lavorarci in squadra.
Repo è il singolo progetto: una cartella con dentro i file e tutta la loro storia.
Pensatela come un quaderno che non si può strappare: ogni pagina scritta resta lì, datata e firmata. Se domani qualcosa si rompe, sappiamo esattamente quando, dove e chi.
Cosa c'è in una repo pensata per un agente AI
Oltre al codice, una repo moderna contiene file scritti apposta per l'agente. Sono testi in linguaggio normale, non programmazione.
CLAUDE.md (o AGENTS.md per altri agenti): le regole della casa. Spiega com'è fatto il progetto, cosa fare e cosa evitare. È il manuale di benvenuto.
Skills (cartelle con un file SKILL.md): competenze specifiche, come "scrivere un report" o "controllare la sicurezza". Sono i corsi di specializzazione.
Comandi: scorciatoie per i compiti ripetuti. Sono le procedure standard.
Subagenti: assistenti specializzati a cui l'agente delega pezzi di lavoro. Sono i colleghi esperti di reparto.
Plugin: pacchetti che raccolgono tutto quanto sopra, installabili in un colpo solo. Sono il kit completo pronto all'uso.
Come si comporta l'agente
Qui sta la magia, ed è più semplice di quanto sembri.
All'avvio legge il manuale. Appena entra nella repo, Claude Code legge CLAUDE.md. Da quel momento sa con chi ha a che fare.
Le competenze le apre solo quando servono. Delle skill conosce prima solo il titolo e una breve descrizione. Quando il compito lo richiede, apre quella giusta e la segue. Come un professionista che non si porta in testa tutti i manuali, ma sa quale prendere dallo scaffale.
Lavora lasciando traccia. Ogni modifica finisce nella storia della repo. Nulla sparisce, tutto si può controllare e annullare.
Perché "insegnano" a Claude
Un agente AI senza istruzioni fa cose ragionevoli. Un agente con una buona repo fa cose giuste per voi. La differenza è enorme.
Scrivere una regola una volta sola, nel file giusto, significa non doverla ripetere mai più. È formazione che resta: oggi, domani, e per chiunque apra il progetto dopo di voi. Ed è il motivo per cui su GitHub esistono migliaia di repo condivise piene di skill e plugin: persone che hanno insegnato qualcosa al proprio agente e lo regalano agli altri.
Una regola d'oro prima di iniziare
Garbage in, garbage out. Istruzioni confuse producono lavoro confuso. E una repo scaricata da sconosciuti va letta prima di installarla: dentro ci sono ordini che l'agente eseguirà. Fidarsi è bene, leggere è meglio.
Il messaggio da portare a casa
GitHub non è un posto per soli programmatori. È il luogo dove si scrive, in parole semplici, come vogliamo che le cose vengano fatte. Chi sa scrivere un buon manuale sa guidare un agente AI. E questa, credetemi, è una competenza che vale oro.
Mini-glossario della PlayGuide
Repository (repo): cartella di progetto con tutta la sua storia.
Commit: una "fotografia" salvata delle modifiche, con una nota che le descrive.
Branch: una copia di lavoro parallela, per provare senza rompere l'originale.
Pull request: la richiesta di unire le modifiche al progetto principale, dopo una revisione.
Coding agent: un'AI che non solo suggerisce codice, ma lo scrive, lo prova e lo modifica in autonomia.