Lezione 1 · Il progetto parte bene: cartella, regole, repository

Il kit: uno per gruppo

Uno per gruppo lo scarica, lo scompatta dove tiene i progetti e apre la cartella in VS Code (File → Apri cartella). Gli altri la riceveranno da GitHub nella sezione 5. Il file delle regole si chiama CLAUDE.md per Claude Code e AGENTS.md per Codex, Gemini CLI e opencode: nel kit ci sono entrambi, stesso testo. La relazione (LaTeX e Word, stesse sezioni: scegliete uno dei due) e il diario del progetto sono già lì.

Il contesto e i limiti, scritti in un file

CLAUDE.md e AGENTS.md sono lo stesso file di testo con due nomi: Claude Code legge il primo, Codex, Gemini CLI e opencode il secondo. L’agente lo legge da solo, all’inizio di ogni sessione, senza che glielo chiediate, a patto che sia aperto dentro la cartella del progetto. Dentro ci va quello che un collega nuovo avrebbe bisogno di sapere il primo giorno: cosa stiamo facendo, com’è fatta la cartella, e cosa non deve fare.

Nelle parole della sezione 1: è il contesto che il modello ha sotto gli occhi a ogni giro, e i limiti che gli mettete prima che parta. È del gruppo: sta in git, ed è lo stesso sui tre PC.

Si scrive adesso, tutti davanti allo stesso schermo

1. Cos’è il progetto: due o tre frasi che un estraneo capisce. Se non le sapete scrivere, è il primo problema da risolvere oggi.
2. Chi ci lavora: nomi veri. E la frase "nessuno di noi programma di mestiere" resta se è vera.
3. Com’è fatta la cartella: lasciate le righe del kit, aggiungete le cartelle che già sapete di volere (dati/, per esempio).
4. Regole di lavoro: leggetele una per una. Toglietene una solo se sapete perché.
5. Salvate, poi copiate tutto il testo anche in AGENTS.md: i due file restano sempre uguali. Da questo momento qualunque agente aperto in questa cartella legge le regole.

La sezione più utile è quella delle regole negative: cosa non deve fare. Sono quelle che vi risparmiano i disastri. E niente commit da parte dell’agente: li fate voi, dopo aver letto.

Il punto di partenza

# CLAUDE.md - Nome del progetto

## Cos'è questo progetto

Due o tre frasi: cosa vogliamo ottenere e per chi. Esempio: "Studio di un sistema di
ricarica condominiale con load balancing: normativa, requisiti, modello di ripartizione
dei costi fra i condomini."

Progetto del corso di Automazione dei sistemi elettrici di trasporto, Politecnico di
Milano, gruppo NN.

## Chi ci lavora

Nome Cognome, Nome Cognome, Nome Cognome. Nessuno di noi programma di mestiere: spiega le
scelte in italiano semplice e non dare per scontato niente.

## Preferenze personali

Se nella radice del progetto esiste `miePersonalizzazioni.md`, leggilo prima di iniziare e
segui le sue indicazioni: sono le preferenze di chi sta lavorando in questa sessione.
Non modificarlo e non metterlo mai in un commit.

Ogni componente del gruppo lo crea sul proprio PC (è nel `.gitignore`, non va su GitHub)
con questa struttura:

    # Le mie personalizzazioni
    ## Chi sono
    Nome, sistema operativo, editor, agente che uso.
    ## Come voglio che mi parli
    Lingua, lunghezza delle spiegazioni, quando chiedermi conferma.
    ## Cosa so fare e cosa no
    Terminale, git, programmazione: sì / no / un po'.
    ## Note di lavoro
    Comandi che uso spesso, errori già visti, cose che ho capito.

## Com'è fatta la cartella

- `docs/` - documenti di lavoro: `flussi.md` e `flussi.drawio.png` (i passi del progetto, in parole e in un diagramma; il diagramma lo disegniamo noi), appunti, note sulle fonti.
- `relazione/` - la relazione del corso, in LaTeX e in Word. Non toccarla mai senza che te lo chieda esplicitamente.
- `dati/` - i dati raccolti. Ogni file è registrato nella tabella di `dati/README.md` con la sua provenienza.
- `codice/` - il codice: script, modello, grafici. Ogni script dice in testa cosa fa, cosa legge e cosa produce.
- `presentazione/` - le slide finali. `sito/` - la pagina di presentazione.
- `diario.md` - il diario del progetto: avanzamento e decisioni. Lo scriviamo noi, non tu.
- `README.md` - cos'è il progetto, per chi arriva da fuori.
- Ogni cartella ha un README.md che dice cosa ci va: leggilo prima di scriverci. Nuove cartelle solo dopo averlo proposto e avuto l'ok.

## Regole di lavoro

- Un passo alla volta. Fai quello che ti ho chiesto, poi fermati e dimmi cosa hai fatto.
- Prima di creare un file nuovo, dimmi quale e perché.
- Se non ti riesce qualcosa, dillo. Non inventare numeri, fonti, nomi di pacchetti o risultati.
- Codice semplice e commentato in italiano: lo dobbiamo leggere noi.
- Niente librerie in più senza chiedermelo prima.
- Non modificare `relazione/` e `diario.md`.
- Niente commit e niente push da solo: li facciamo noi, dopo aver letto le modifiche.

## Come si scrive

Italiano. I numeri hanno sempre l'unità di misura. Ogni affermazione non ovvia ha una
fonte. Niente emoji.

Il file tuo: miePersonalizzazioni.md

Dentro CLAUDE.md e AGENTS.md c’è anche la struttura di miePersonalizzazioni.md: come vuoi che ti parli, cosa sai fare, il tuo sistema operativo. Ognuno lo crea sul proprio PC, e non finisce su GitHub perché il .gitignore lo esclude. L’agente lo legge perché le regole gli dicono di farlo. Lo fate nella sezione 5, quando ognuno avrà la sua copia del repository.

Com’è fatta una sessione di lavoro

A · Chi crea il repository (uno per gruppo)

Tutto dal pannello Controllo del codice sorgente di VS Code (l’icona dei rami nella barra a sinistra). Lo fa la persona che ha la cartella aperta.

1. Pannello Controllo del codice sorgente (icona dei rami, a sinistra) → Inizializza repository.
2. Nel campo del messaggio scrivete "kit di partenza", poi Commit. Se chiede di preparare tutti i file (stage), sì.
3. Controllo: nell’elenco dei file committati NON deve esserci miePersonalizzazioni.md. Se c’è, il .gitignore non è nella cartella.
4. Pulsante Pubblica su GitHub → scegliete "repository privato", nome automazione-gruppo-NN. Alla prima volta VS Code chiede di accedere a GitHub: sì.
5. Su github.com, pagina del repository → Settings → Collaborators → Add people: il nome utente GitHub di ogni compagno.

B · Gli altri, poi C · tutti

B · Gli altri componenti

1. Accettare l’invito: arriva per mail da GitHub, oppure su github.com/notifications.
2. In VS Code: File → Nuova finestra, poi "Clona repository Git" → Clona da GitHub → automazione-gruppo-NN. Scegliete dove tenerlo e apritelo.

C · Tutti: le proprie preferenze

1. File → Nuovo file, nome miePersonalizzazioni.md, nella radice del progetto. Struttura: quella scritta in CLAUDE.md e AGENTS.md. Compilatelo: cinque minuti.
2. Controllo: nel pannello Controllo del codice sorgente il file NON deve comparire tra le modifiche. Se compare, il nome non è esatto.

Da qui in poi, ogni volta che qualcuno cambia un file: Commit con un messaggio che dice cosa è cambiato, poi Sincronizza (pull e push insieme). Prima di iniziare a lavorare: Sincronizza.

Prima di chiedere di costruire, sapere cosa

Non il codice: i passi. Cosa entra, cosa succede, cosa esce, in che ordine. Un agente ottimizza il percorso verso l’obiettivo che gli date, e a ogni giro controlla se l’ha raggiunto: se non è chiaro cos’è “fatto”, o si ferma troppo presto o non si ferma. La domanda è vostra.

Si fa su carta, poi si disegna con draw.io nel browser e si mette nel repository. In aula si inizia; si finisce a casa, con calma, perché questi passi diventano la sezione Metodo della relazione.

Dal foglio al file

1. Su carta, tutto il gruppo: cosa entra nel progetto (dati, misure, normativa, persone), cosa ci fate, cosa esce (un numero, un grafico, una decisione, un documento). Scatole e frecce, dieci minuti, niente PC.
2. Numerate le scatole. Ogni scatola deve rispondere a: cosa entra, cosa succede, cosa esce. Se una non risponde, o si spacca in due o si cancella.
3. Uno del gruppo apre draw.io nel browser (app.diagrams.net, gratis, senza account) e ricopia il foglio: scatole e frecce, con i numeri. Poi File → Esporta come → PNG, con la spunta "Includi una copia del diagramma", e salva il file come flussi.drawio.png nella cartella docs/ del progetto: è un’immagine normale, GitHub la mostra, e si riapre in draw.io per modificarla.
4. La stessa persona apre l’agente nella cartella e incolla il prompt qui sotto con i vostri passi al posto dei segnaposto: il testo lo scrive lui, il disegno resta vostro.
5. Leggete docs/flussi.md insieme. Le domande in fondo sono il vero risultato: rispondete e correggete il file a mano.
6. Commit dal pannello Controllo del codice sorgente ("flussi del progetto"), poi Sincronizza. Aprite il repository su github.com: il diagramma si vede lì.

Aprire l’agente nella cartella giusta

claude
codex
gemini
opencode
grok

Cursor, TraeCode e Copilot in VS Code: l’agente è già dentro l’editor. Vale la stessa regola: la cartella aperta è quella in cui cerca le regole.

Come NON si chiede

fammi lo schema del progetto

Cosa succede: inventa lui i passi del vostro progetto, e sembrano pure sensati. È il modo più veloce per ritrovarsi a lavorare sul progetto di qualcun altro.

Come si chiede

Abbiamo disegnato i passi del nostro progetto: il diagramma è in docs/flussi.drawio.png.
Eccoli, in ordine:
1. <primo passo: cosa entra, cosa succede, cosa esce>
2. <secondo passo>
3. <terzo passo>

Scrivi docs/flussi.md con: una riga di introduzione, l'immagine del diagramma
(![Flussi del progetto](flussi.drawio.png)), e per ogni passo una frase che dice cosa
entra, cosa succede, cosa esce.

Se un passo ti sembra mancare o essere ambiguo, segnalalo in fondo al file con una
domanda: non inventarlo. Non creare altri file, non toccare il diagramma e non
modificare CLAUDE.md e AGENTS.md.

Quando hai finito, fermati e dimmi cosa hai scritto.

Quattro cose lo rendono diverso: gli date voi il contenuto, dite esattamente cosa scrivere e dove, dite cosa non fare, e gli chiedete le domande invece delle risposte. Non dice “leggi le regole”: quello lo fa da solo, se è nella cartella giusta. E il diagramma non glielo fate fare: il disegno è il vostro ragionamento, lui ci mette le parole intorno.

Se c’è tempo: una pagina che presenta il progetto

Un solo file in sito/, si apre con un doppio clic, niente server. Serve a vedere l’agente costruire qualcosa di visibile partendo solo da quello che avete scritto: se lì c’è poco, la pagina viene vuota, ed è giusto così.

Crea sito/index.html: una sola pagina statica, HTML e CSS nello stesso file, niente
JavaScript e niente librerie, che presenta il progetto a chi non lo conosce: titolo, una
frase che dice cosa facciamo, chi siamo, i passi del progetto presi da flussi.md, come
contattarci.

Testo in italiano, preso da CLAUDE.md (o AGENTS.md) e docs/flussi.md: non inventare niente. Deve aprirsi con
un doppio clic sul file. Non creare altri file.

Quando hai finito, fermati e dimmi come la apro.

Aprite sito/index.html con un doppio clic, leggete cosa c’è scritto, e cercate la frase che non avete mai detto: c’è quasi sempre. Poi commit e Sincronizza.

Tre segnali, tre regole

Sono i tre “non può” della sezione 1 visti da vicino: inventa perché produce testo plausibile, fa troppo perché il ciclo non sa dove fermarsi, dice “fatto” perché non ha un passaggio di verifica. Il passaggio di verifica siete voi.

1. Un passo alla volta. Una richiesta, una cosa.
2. Prima di dire di sì, leggi cosa ha cambiato. Se non capisci un file, chiedigli di spiegartelo riga per riga.
3. Commit e push li fai tu, dopo aver letto. Mai l’agente da solo.

Se si rompe

In VS Code non compare "Pubblica su GitHub"

Non avete fatto il login a GitHub dentro VS Code: icona Account in basso a sinistra → Accedi con GitHub. Poi riaprite il pannello Controllo del codice sorgente.

"Clona da GitHub" non mostra il repository del gruppo

Non avete ancora accettato l’invito: github.com/notifications. Oppure incollate l’indirizzo del repository a mano.

`Permission denied` o `403` quando sincronizzate

Non siete collaboratori del repository, o l’invito non è accettato.

miePersonalizzazioni.md compare tra le modifiche

Il nome non è esattamente quello (maiuscole comprese), oppure il file non è nella radice, oppure manca il .gitignore del kit.

Conflitto durante Sincronizza

Due persone hanno cambiato la stessa riga. VS Code mostra le due versioni una sopra l’altra: scegliete, salvate, commit di nuovo, Sincronizza.

L’agente ignora le regole

Quasi sempre è aperto in un’altra cartella. Chiudetelo, aprite il terminale da VS Code (Terminale → Nuovo terminale, si apre nella cartella giusta), rilanciatelo. Per controllare, chiedetegli: "quali file di regole hai caricato?"

L’agente ha riscritto mezzo progetto

Pannello Controllo del codice sorgente → sui file cambiati, Ignora modifiche: torna tutto all’ultimo commit. Poi rifate la richiesta più stretta.