Lezione 2 · Si riparte dal kit, e la relazione va su GitHub

Si riparte dal kit

La teoria sull’agente e git sono nella lezione 1, sezioni 1 e 2: se vi siete persi qualcosa, rileggetele a casa. Le schermate che seguono sono le sue, dalla sezione 3 in poi, e la numerazione continua da lì.

Come è fatta l’ora

0-3

Dove eravamo rimasti

Questa schermata.

3-15

Il kit e il repository del gruppo

Uno scarica lo zip, crea il repository privato su GitHub e invita gli altri; gli altri clonano. Ognuno il suo miePersonalizzazioni.md.

15-25

CLAUDE.md e AGENTS.md, scritti insieme

Il contesto e i limiti per l’agente, con il progetto vero.

25-37

I flussi logici

Su carta, poi draw.io, poi docs/flussi.md: i passi del progetto.

37-55

La relazione, su GitHub

Overleaf collegato al repository (o Word), poi titolo, autori e introduzione. Il resto della sezione 10 a casa.

55-60

Compiti

La pagina di presentazione (sezione 7) e la revisione dell’agente: a casa, se in aula non c’è tempo.

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.

La relazione sta nel repository, come tutto il resto

Un posto solo per il progetto: chi apre il repository trova i passi, i dati, il codice e la relazione, con la storia di chi ha cambiato cosa. Consigliamo LaTeX; Word è permesso.

Nel kit ci sono tutti e due, con le stesse sezioni: relazione.tex e relazione.docx. Oggi il gruppo sceglie, e cancella l’altro.

LaTeX: Overleaf del Politecnico, collegato al repository

Niente da installare: si scrive nel browser, insieme, e il PDF si vede subito.

Tutti, una volta sola

1. Aprite www.overleaf.com/edu/polimi e fate Log in with SSO con le credenziali del Politecnico. È gratis per gli studenti PoliMi, con collaboratori illimitati: con un account Overleaf normale, invece, ne avreste uno solo.
2. Se avete già un account Overleaf con un’altra email: dalle impostazioni dell’account aggiungete l’email PoliMi e collegatela all’SSO.

Chi ha creato il repository su GitHub

1. Overleaf → Account Settings → GitHub → collegate il vostro account GitHub e autorizzate Overleaf.
2. Dalla lista dei progetti: New project → GitHub repo → automazione-gruppo-NN → Import to Overleaf. Entra tutto il repository, non solo relazione/: è normale. Overleaf apre da solo relazione/relazione.tex.
3. Recompile: a destra compare il PDF di esempio, due pagine. Se compare, il collegamento funziona.
4. Share → invitate gli altri componenti con la loro email PoliMi, come Editor.

Ogni volta che si scrive

Si inizia

Chi ha collegato il progetto: icona Integrations nella barra a sinistra → GitHub. Se dice che ci sono modifiche su GitHub, le prende (pull).

Si scrive

Tutti insieme in Overleaf, come in un documento condiviso. Il PDF si aggiorna con Recompile.

Si finisce

Stessa persona: Integrations → GitHub → Push Overleaf changes to GitHub, con un messaggio che dice cosa è cambiato (prende anche le modifiche arrivate nel frattempo su GitHub). Poi, in VS Code, Sincronizza: la relazione arriva anche sui PC.

Una regola sola: la relazione si scrive solo in Overleaf, tutto il resto (CLAUDE.md, AGENTS.md, docs/, dati/, codice/) solo in VS Code. Se lo stesso file cambia nei due posti, Overleaf non unisce: crea un ramo nuovo su GitHub, e rimettere insieme i pezzi è un lavoro.

Word: permesso, con una regola

Un .docx per git è un file chiuso: GitHub non mostra cosa è cambiato, e se due persone lo modificano insieme non si possono unire le due versioni, se ne tiene una e l’altra si perde. Quindi si scrive altrove, e nel repository va la versione di fine sessione.

1. Cancellate relazione.tex e bibliografia.bib dal repository e tenete relazione.docx (stesse sezioni). Le figure restano in relazione/figure/.
2. Scrivete su OneDrive del Politecnico (Microsoft 365, compreso nell’account PoliMi): caricate relazione.docx, condividetelo con il gruppo, e ci scrivete insieme.
3. A fine sessione, una persona scarica il .docx aggiornato dentro relazione/, sostituisce quello vecchio, fa commit e Sincronizza.

Cosa si scrive oggi

Titolo e autori

Una riga che dice cosa fate. Nomi, matricole, email PoliMi di tutti.

Introduzione

Mezza pagina: il problema, perché conta, cosa farete. Senza risultati: non ci sono ancora.

Metodo

I passi di docs/flussi.md, uno per paragrafo, con il diagramma flussi.drawio.png come figura.

Stato dell’arte

Tre fonti vere, in bibliografia.bib, citate nel testo. Di ognuna avete letto almeno l’abstract. Da Google Scholar: Cita → BibTeX, e si incolla.

Il testo lo scrivete voi. In fondo al template c’è la sezione Uso di strumenti di intelligenza artificiale: da oggi ci annotate come usate l’agente.

A casa: l’agente come revisore, non come autore

Dopo il Push da Overleaf e Sincronizza in VS Code, la relazione è sul vostro PC: l’agente, aperto nella cartella, la legge insieme a flussi.md. Gli chiedete di trovare i problemi, non di scrivere.

Leggi relazione/relazione.tex, relazione/bibliografia.bib e docs/flussi.md.
Non modificare nessun file.

Fammi un elenco di:
- frasi che affermano qualcosa di non ovvio senza una citazione;
- numeri senza unità di misura;
- passi di flussi.md che mancano nella sezione Metodo, o che lì sono descritti in modo diverso;
- \cite{} che non trovano una voce in bibliografia.bib.

Per ogni punto: sezione, frase, cosa manca. Non riscrivere il testo: lo correggiamo noi.

Ogni punto dell’elenco lo verificate: qualche volta ha ragione, qualche volta no. Le correzioni le fate voi, in Overleaf. Con Word questo passo non funziona bene: è uno dei motivi per cui consigliamo LaTeX.

Se si rompe, sulla relazione

In Overleaf, "GitHub repo" non mostra il repository del gruppo

Chi importa deve avere accesso al repository su GitHub (chi l’ha creato, o un collaboratore che ha accettato l’invito). Se ce l’ha e non lo vede: su github.com, Settings → Applications → Overleaf, controllate che abbia accesso ai repository privati. Un solo progetto Overleaf collegato per gruppo.

Overleaf non riesce a sincronizzare

Oltre 7 MB di file nel repository Overleaf si ferma. I dati pesanti (CSV grandi, video) non vanno nel repository: chiedete prima di caricarli.

Overleaf dice "could not be automatically merged"

La stessa riga è cambiata in Overleaf e dal PC. Overleaf non unisce: mette la sua versione in un ramo nuovo su GitHub (overleaf-data-ora) e aspetta. Non premete "I have manually merged": scrivete al docente, si sistema con un merge dal PC. Per non arrivarci: la relazione si scrive solo in Overleaf.

Il PDF non si compila

Guardate il primo errore nei log di Overleaf (l’icona accanto a Recompile): di solito è una parentesi graffa non chiusa o un carattere come % o & senza la barra davanti.

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.