Il mio allenatore di corsa è un repository Git e un agente Claude

Finisco la mia seduta. L'orologio si sincronizza da solo con Strava, come sempre. Vado a farmi la doccia.

Quando esco, tre cose sono successe senza che io toccassi niente. L'analisi della seduta è scritta nel mio repository di allenamento. La settimana è stata riaggiustata, con la ragione del cambiamento annotata di fianco. E sotto l'attività Strava c'è un commento del mio allenatore, che mi dice quanto vale la seduta e che cosa cambia per venerdì.

Quell'allenatore non è un'applicazione che ho sviluppato. È un repository Git di file Markdown, un abbonamento Claude e AgentsRoom che tiene insieme il tutto. Nessun server scritto, nessuna fattura a token, più o meno un fine settimana di montaggio.

Il tutto è pubblicato come modello: github.com/AgentsRoomDev/running-performance-coach. Puoi clonarlo e renderlo tuo riempiendo gli spazi lasciati vuoti. Questo articolo spiega come funziona, pezzo per pezzo, dando per scontato che tu abbia sentito la parola "API" ma non abbia mai scritto un webhook.

Per inquadrare: corro da parecchio, 2h47 in maratona, 1h13:59 in mezza, 33:45 sui 10 km. L'obiettivo del ciclo attuale è tornare sotto i 34 minuti sui 10 km. Conta per quello che segue: un allenatore generico che mi rispiega che cos'è una seduta di soglia non mi serve a niente, ed è esattamente il problema che questo montaggio risolve.

Che cosa succede tra la fine della mia corsa e il commento

La catena completa sta in sei passaggi:

1. L'orologio manda l'attività a Strava. Quella parte succede già a tutti.
2. Ogni 15 minuti, un piccolo script Python chiede a Strava se c'è qualcosa di nuovo.
3. Quando trova una seduta nuova, fabbrica una scheda di seduta Markdown nel mio repository: i giri, i parziali, il volume, la frequenza cardiaca. Solo dati misurati.
4. Riscrive anche il titolo e la descrizione dell'attività su Strava, così il mio feed smette di dire "Corsa del pomeriggio".
5. Poi manda un messaggio firmato ad AgentsRoom, che apre un agente Claude con la seduta già in mano.
6. Quell'agente fa il lavoro da allenatore: legge, confronta, scrive l'analisi, aggiusta la settimana, fa commit, fa push, commenta su Strava e mi manda il rapporto lungo per email.

I primi cinque passaggi sono idraulica. Il sesto è l'argomento di questo articolo.

Il diario di allenamento è un repository Git, non un database

Questa è la decisione che cambia tutto, ed è anche quella che sorprende di più.

Una seduta = un file, journal/2026/2026-09-03.md. Una settimana = un file, plan/weeks/2026-W36.md. Un cambio di piano = un commit, con la sua ragione nel messaggio. Non c'è database, non c'è schema, non c'è migrazione, non c'è interfaccia.

Tre conseguenze, in ordine di importanza:

L'allenatore può rileggere la propria storia. Sa che cosa ha prescritto tre settimane fa, e può verificare se ha funzionato. Un chatbot a cui racconti la tua seduta riparte da zero a ogni conversazione. Un agente che ha un repository ha una memoria, e quella memoria è leggibile da un umano.

Leggo il mio piano dal telefono, nell'app GitHub. Il README.md del repository non è una pagina di presentazione: è il mio cruscotto. Il contratto scritto in CLAUDE.md è esplicito su questo, nessuna pianificazione è finita finché il README non la riflette. Il risultato: non ho nessuna interfaccia da mantenere, eppure ho uno schermo che mi dice che cosa faccio oggi.

Niente è irreversibile. Tutto quello che l'agente scrive è un commit. Posso leggerlo, contestarlo, annullarlo. È molto diverso da un'applicazione che decide per conto suo.

Passo 1: Strava sveglia un piccolo script

Strava espone un'API: un modo, per un programma, di chiedere "dammi le attività recenti di questo atleta". Lo script strava_sync.py fa esattamente questo, e trasforma la risposta in una scheda di seduta.

La parte interessante non è la chiamata di rete, è la ricostruzione. Un orologio registra dei giri grezzi. Lo script deve capire che seduta fosse:

Lap 1  : 4.40 km in 26'07 (5:56/km)   ← riscaldamento
Lap 2  : 1.00 km in 3'41  (3:41/km)   ← ripetuta 1
Lap 3  : 0.20 km in 1'59  (9:55/km)   ← recupero
...                                     → "5 x 1000m r' 2'"

Prova tutti i tagli della forma "i k giri più veloci sono le ripetute" e tiene il migliore che regge. Sembra banale e non lo è: un raggruppamento ingenuo per velocità cade in trappola appena un riscaldamento è più veloce di un recupero.

Soprattutto, la forma della seduta viene ricostruita dall'orologio, mai dal piano. È tentante fare il contrario (il piano dice 5 x 1000m, tanto vale scriverlo) ed è esattamente l'errore: tutto il senso sta nel rilevare i giorni in cui ho fatto altro. Quando i due divergono, è quella divergenza l'informazione, e l'allenatore la vede:

Previsto 3 x 8' → corso in continuo

Due avvertimenti prima di partire.

L'API di Strava richiede un abbonamento sviluppatore a pagamento da giugno 2026. Senza, ogni chiamata risponde 403 Application Status Inactive. Il ripiego esiste ed è previsto nel modello: esportare un file TCX dall'orologio e passarlo a import_tcx.py. Tutto quello che sta a valle dell'importazione funziona identico.

Le quote sono larghe, ma reali. Sulla mia applicazione, 300 richieste ogni 15 minuti e 3.000 al giorno in lettura. Lo script ne consuma una per passaggio a regime, quindi 96 al giorno. Siamo lontanissimi dal tetto, ma è il genere di cosa che si verifica prima, non dopo.

Passo 2: lo script sveglia l'agente, con una firma

È qui che diventa interessante.

Un webhook è il contrario di una domanda. Invece di chiedere ogni cinque minuti se c'è qualcosa di nuovo, dai un indirizzo web a un programma, ed è lui a mandarti un messaggio quando l'evento accade. Non paghi niente finché non succede niente.

AgentsRoom espone esattamente questo: un trigger webhook. Crei un trigger nell'applicazione, lei ti restituisce una URL e un segreto. Chiunque mandi un messaggio JSON a quella URL apre un agente, con il prompt che hai scritto e il contenuto del messaggio già iniettato dentro.

Il messaggio che il mio script manda è volutamente minuscolo:

{
  "type": "created",
  "title": "03/09 · 5 x 1000m r' 2'",
  "body": "Seduta del 03/09/2026 importata da Strava.\n\nSeduta di qualità: 5 x 1000m r' 2'\nSplits: 3'41 - 3'40 - 3'38 - 3'40 - 3'35\n\nVolume totale: 12.51 km in 1h07'42 (5:25/km), D+ 56 m\nSeduta prevista: RP10-5x1000\n\nScheda di seduta: journal/2026/2026-09-03.md\nScheda di settimana: plan/weeks/2026-W36.md"
}

Nota quello che non c'è: il testo del piano. Il webhook trasporta il codice della seduta prevista e il percorso delle schede, mai il loro contenuto. Un agente che ha il repository andrà a leggerle da solo; un agente che non ce l'ha non ha niente a che fare con le mie istruzioni interne. È la stessa regola delle descrizioni pubblicate su Strava.

La firma, e la trappola che si porta dietro

Una URL pubblica che apre un agente non può restare aperta al primo che la trova. Quindi il trigger è firmato: lo script calcola un'impronta del messaggio con il segreto condiviso (un HMAC-SHA256, se il termine ti dice qualcosa) e la manda nell'header X-AgentsRoom-Signature. Il server ricalcola la stessa impronta dalla sua parte; se non coincidono, rifiuta.

Senza firma, la risposta è netta:

{"error":"REJECTED","message":"Signature missing."}

Ed ecco la trappola, che mi è costata una serata. La firma copre i byte esatti che partono sulla rete, non l'oggetto in memoria. Se firmi un file così com'è sul disco, e poi lasci che un altro strato riserializzi l'oggetto (uno spazio in più, un ordine di chiavi diverso, un accento sfuggito in un altro modo), ottieni una firma perfettamente valida per un messaggio che il server non riceverà mai. Il rifiuto è impossibile da debuggare: sembra tutto corretto da entrambe le parti.

La correzione sta in una frase: si serializza e si firma nello stesso posto. Nel modello, è la funzione post_json a fare entrambe le cose, e nient'altro ha il diritto di toccare il corpo del messaggio.

Passo 3: tre livelli dicono all'allenatore chi è, come funzionano le cose qui e che cosa fare adesso

Un agente che allena non è un prompt gigante. Sono tre testi separati, e la separazione conta.

Livello 1, la persona: chi è

Un prompt di sistema collegato all'agente in AgentsRoom. Porta la filosofia di allenamento, ed è volutamente generico rispetto allo sport: allenerebbe chiunque.

Il tuo lavoro non è semplicemente generare piani di allenamento. Alleni l'atleta in modo continuo, analizzando il suo allenamento, capendo la sua forma attuale, adattando le sedute che arrivano. […] Parla come un allenatore esperto, non come un chatbot motivazionale.

Dice anche quello che non fa: non giudicare una seduta solo in base al fatto che il ritmo obiettivo sia stato tenuto, essere esplicito sull'incertezza di una previsione di tempo, e non validare un obiettivo solo perché l'atleta lo desidera. Quest'ultima riga è quella che rende utile l'allenatore.

Non devi scriverla tu: questa persona è pubblicata nel catalogo di agenti di AgentsRoom con il nome Allenatore di Performance di Corsa. Un clic la installa, pronta all'uso.

Livello 2, CLAUDE.md: come funzionano le cose qui

Questo è il contratto, letto all'inizio di ogni sessione. Contiene la struttura dei file, le regole che la tengono coerente, i principi di allenamento che vincolano ogni proposta e soprattutto il rituale: la sequenza esatta da svolgere quando viene riportata una seduta.

Un estratto, perché mostra il livello di precisione:

Ordine di sacrificio quando la settimana deraglia: prima i minuti in più sui fondi lenti, poi il lavoro di forza, poi la lunghezza del lungo, poi una seduta di qualità. Mai la settimana intera.

È qui che l'allenatore smette di essere un chatbot. Non improvvisa una procedura ogni volta, segue quella che ho scritto una volta per tutte. Se devi leggere un solo file del repository modello, leggi quello.

Livello 3, il prompt del trigger: che cosa fare adesso

È il messaggio consegnato all'agente quando atterra una seduta. Riceve l'attività tramite variabili di template: {{event.title}}, {{event.body}}, {{event.url}}. Così l'agente parte con la seduta già in mano, invece di andarsela a cercare.

Ecco la sua ossatura, così com'è nel trigger:

Nuova seduta importata da Strava.

**{{event.title}}** · attività {{event.id}}
{{event.url}}

{{event.body}}

---

Sei nel repository `training-plan`. Leggi `CLAUDE.md` per primo: fa legge.
Scrivi nella mia lingua e mi dai del tu ovunque (§3).

Il rituale del §6 si applica, ma il suo **passo 1 è già fatto**:
`strava_publish.py` ha creato la scheda di seduta e l'ha committata. Riprendi
dal passo 2 e vai fino in fondo. Tre consegne, in quest'ordine: **l'analisi
nel repository**, **il commento sotto l'attività Strava**, **l'email**.

⚠️ **Stai girando senza supervisione: nessuno leggerà una domanda.** Non
chiedere mai un arbitrato: decidi, agisci, e di' nel tuo resoconto che cosa hai
deciso e perché.

## 1 · Analizzare e aggiustare il piano (rituale §6, passi da 2 a 6)

1. `git pull --rebase` prima di tutto: la scheda può venire dal server.
2. Leggi, in quest'ordine: la scheda di oggi, la scheda di settimana,
   `athlete/zones-and-paces.md`, e **le ultime 3 schede di seduta**:
   una seduta non si giudica mai da sola.
3. Scrivi la sezione `## Analysis`: **prima il verdetto**, poi i segnali che
   lo sostengono, poi quello che cambia.
   ⛔ Se `## Analysis` è già riempita, non riscriverla.
4. Aggiorna la scheda di settimana e traccia **ogni** cambio di piano sotto
   `## Adjustments`, con la sua ragione.
5. **Rigenera il `README.md`**: è lo schermo che leggo dal telefono.
6. Commit e push, percorsi espliciti, ⛔ mai `git add -A`.

## 2 · Kudos e commento su Strava
   ⛔ Un commento Strava è PUBBLICO: niente frequenza cardiaca obiettivo,
   niente acciacchi, nessun arbitrato interno, nessun tempo previsto.

## 3 · Il rapporto completo per email

La riga che lavora di più è quella in mezzo: "nessuno leggerà una domanda". Un agente che gira senza nessuno davanti allo schermo e che chiede un arbitrato non sta commettendo un errore, semplicemente si ferma, e tu lo scopri il giorno dopo.

Quale modello, e perché un milione di token non è un capriccio

Il contesto lungo non è una civetteria. Per giudicare una seduta come si deve, l'allenatore legge la scheda del giorno, la scheda di settimana, la tabella dei ritmi di riferimento e le tre sedute precedenti. Una seduta non si giudica mai da sola: il carico accumulato, la sequenza dei giorni e i punti di attenzione in corso cambiano completamente il verdetto. Tre ripetute a 3:38 il giorno dopo un lungo di due ore non raccontano la stessa storia degli stessi 3:38 dopo un giorno di riposo.

La modalità autonoma non è sciatteria, è una conseguenza: un'esecuzione senza nessuno davanti allo schermo non ha nessuno che approvi un git push. E l'accesso al browser è quello che permette all'agente di andare a commentare su Strava e di mandare l'email, due cose che qui non hanno un'API comoda.

Che cosa è automatizzato, e che cosa volutamente non lo è

Questa è la decisione di progettazione di cui sono più contento, ed è facile non accorgersene.

Il lavoro di importazione registra e pubblica, non giudica mai.

Uno script che si mettesse a giudicare produrrebbe verdetti senza contesto, con una logica congelata dentro codice che nessuno rilegge. Giudicare vuol dire tenere insieme il carico della settimana, la forma del momento e quello che è stato detto l'ultima volta: è lavoro da allenatore, e lo fa l'agente, con tutto il fascicolo davanti.

Il beneficio pratico è immediato: quando l'agente non ha girato (macchina spenta, API giù), la scheda esiste comunque. Non si perde niente, manca solo il commento, e basta rigiocare l'evento.

Un'altra scelta va nella stessa direzione: lo script non tiene nessun file di stato per sapere che cosa ha già trattato. È la descrizione su Strava a fare fede. Vuota, scrive; se porta la sua firma, passa oltre; non vuota e senza firma, l'hai scritta tu e non la tocca. Un file di stato locale non avrebbe potuto dire niente di quello che ha fatto un'altra macchina; così, due macchine possono girare in parallelo senza pestarsi i piedi.

Altre due regole di separazione, incise nel repository e da non aggirare:

• la descrizione pubblicata su Strava non ricopia mai il testo del piano: la mia scheda di settimana contiene frequenze cardiache obiettivo e arbitrati che non hanno niente a che fare con un'attività pubblica;
• una descrizione scritta a mano non viene mai sovrascritta.

Il commento che atterra sotto l'attività

Il punto non è l'autocelebrazione. È che il verdetto dell'allenatore sia leggibile dal mio telefono, sotto l'attività, senza aprire il repository, e che resti lì, attaccato alla seduta, per sempre.

Perciò il commento è volutamente stretto: un'emoji di verdetto, il numero che lo sostiene, e quello che cambia per la seduta successiva. Circa 250 caratteri.

✅ Cinque ripetute a 3'39 di media per un obiettivo di 3'38-3'44, e il cardiaco piatto su tutto il blocco. La tabella dei ritmi regge. Venerdì resta in fondo lento: hai speso il margine della settimana.

La versione lunga, quella con le frequenze cardiache, il punto di attenzione che ho segnalato e l'arbitrato sul volume della settimana prossima, va nel repository e nell'email. Due canali, due pubblici, ed è il prompt a tenere il confine.

Tre cose che si rompono solo in produzione

Ognuna di queste righe esiste perché qualcosa si è rotto senza di lei. Sono più istruttive del resto dell'articolo.

1. Fissare il browser. Ho due estensioni Claude collegate in Chrome. Niente garantisce quale tocca all'agente, e una sola porta la sessione Strava. Il risultato: un'esecuzione su due, l'agente finiva nel browser sbagliato, scollegato, incapace di commentare qualsiasi cosa. La selezione del browser per identificativo di dispositivo non viene conservata da una sessione all'altra: deve quindi stare nel prompt, con il divieto esplicito di andare a chiedere all'utente quale scegliere. Girando senza supervisione, una domanda è un blocco.

2. Il campo commento di Strava non ha maxlength. Niente, nel browser, impedisce di scrivere troppo lungo: è il server a rifiutare all'invio. Un agente che redige un bel paragrafo di 600 caratteri lo digita tutto, clicca su "Pubblica" e si becca un errore che non capisce. Quindi il prompt deve imporre la brevità prima della scrittura, e prevedere il caso: se l'invio fallisce, si accorcia e si ripubblica, mai si taglia in due commenti.

3. Un commento di allenatore per attività. Quando rigiochi un evento per testare (cosa che si fa molto all'inizio), senza questa regola l'agente impila commenti su un'attività già trattata. Perciò il prompt gli fa leggere la scheda "Commenti" prima di scrivere, e passare il turno se è già lì. Stessa logica lato repository: se la sezione ## Analysis è già riempita, non viene riscritta.

Quanto costa

Non c'è nessuna chiave API fatturata a token in questo montaggio. È il punto che trovo più sottovalutato: la stessa cosa costruita su un'API pagata a consumo avrebbe un contatore che gira a ogni seduta, e probabilmente non l'avrei tenuta.

Costruiscilo questo fine settimana

I passi, in ordine. Conta una serata se hai già un account Strava e un abbonamento Claude.

1. Clonare il modello e renderlo tuo.

git clone https://github.com/AgentsRoomDev/running-performance-coach.git my-coach
cd my-coach
rm -rf .git && git init

Rendi privata la tua copia. Un diario di allenamento contiene dati sanitari: frequenza cardiaca, sonno, infortuni. Il modello è pubblico, la tua copia non dovrebbe esserlo.

Poi riempi, in quest'ordine: athlete/profile.md (chi sei come podista), athlete/records.md (i tuoi primati), athlete/constraints.md (gli slot di cui disponi davvero), athlete/zones-and-paces.md (i tuoi ritmi di riferimento), plan/objective.md (la gara e l'obiettivo), poi CLAUDE.md, dove sostituisci ogni segnaposto {{...}}.

Infine, apri il repository con il tuo agente Claude e digli: "leggi CLAUDE.md e athlete/, poi costruiscimi la prima settimana."

2. Collegare Strava.

cp .env.example .env && chmod 600 .env
python3 scripts/strava_oauth.py     # un clic nel browser, una volta sola
python3 scripts/strava_sync.py --dry-run

Il --dry-run mostra quello che verrebbe scritto senza scrivere niente. È il momento di verificare che la ricostruzione delle sedute ti convinca.

3. Creare il trigger in AgentsRoom. In Triggers, New trigger:

AgentsRoom fabbrica una URL e un segreto di firma. Metti entrambi nel tuo .env:

WEBHOOK_URL=https://agentsroom.dev/api/triggers/t_xxxxxxxxxxxx
WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxx

4. Testarlo prima di fidarti.

python3 scripts/webhook_replay.py scripts/examples/webhook-session.json --dry-run
python3 scripts/webhook_replay.py scripts/examples/webhook-session.json

Questo rigioca una seduta dentro il trigger senza aspettare la tua prossima uscita e senza toccare lo stato del lavoro automatico. Devi vedere ✅ HTTP 202, e una scheda di agente deve aprirsi in AgentsRoom.

5. Farlo girare ogni 15 minuti.

bash scripts/systemd/install.sh          # su un server Linux

Un'unità oneshot più un timer: nessun processo residente, e un passaggio saltato mentre la macchina era spenta viene recuperato al riavvio successivo.

Se non hai una macchina accesa in permanenza, salta questo passo: lancia strava_sync.py a mano quando ti va, oppure racconta semplicemente la tua seduta all'agente in una conversazione. Il rituale di CLAUDE.md funziona identico. Perdi l'automazione, non l'allenatore.

Che cosa mi porto via, al di là della corsa

Questo montaggio non ha niente di specifico della corsa. Quello che mostra è uno schema riutilizzabile per praticamente qualsiasi ambito in cui accumuli dati personali e vorresti un parere competente su di essi.

Tre pezzi, e basta. Un repository Git di file Markdown come memoria leggibile dalla macchina e da te. Un evento che sveglia un agente invece di un agente che interroga in loop e brucia token per niente. Tre livelli di configurazione che separano in modo pulito chi è l'agente, come lavora a casa tua, e che cosa deve fare in questo istante.

Sostituisci "seduta di corsa" con "estratto conto", "sessione di codice", "misurazione della glicemia" o "nota di lettura": la meccanica non cambia.

Domande frequenti

Bisogna saper programmare per costruirsi un allenatore di corsa con l'IA?

Bisogna saper lanciare un comando in un terminale e modificare un file di testo. Il repository modello è pronto da clonare, gli script Python non usano nient'altro che la libreria standard (nessun pip install), e la parte di allenamento si configura scrivendo prosa normale dentro file Markdown. Il lavoro vero non è tecnico: è descrivere onestamente chi sei come podista e che cosa stai puntando.

Quanto costa al mese?

L'agente gira sull'abbonamento Claude che hai già (Pro o Max): non c'è nessuna chiave API fatturata a token. In più può servirti una piccola macchina accesa in permanenza per interrogare Strava ogni 15 minuti, intorno ai 5 euro al mese su un VPS, oppure zero su un Raspberry Pi. Il repository Git privato è gratuito. Resta l'API di Strava, che richiede un abbonamento sviluppatore a pagamento da giugno 2026.

Perché un repository Git invece di un database?

Perché lo storico diventa leggibile, dall'allenatore e da te. Ogni seduta è un file Markdown, ogni cambio di piano è un commit con la sua ragione. L'agente può rileggere quello che ha prescritto tre settimane fa e verificare se ha funzionato, e tu leggi il tuo piano dal telefono nell'app GitHub, senza scrivere una riga di interfaccia.

Che cos'è un webhook, spiegato semplice?

Un webhook è un servizio che chiama te invece di essere tu a chiamare lui. Invece di chiedere ogni cinque minuti se c'è qualcosa di nuovo, dai un indirizzo web a un programma, ed è lui a mandarti un messaggio quando l'evento accade. Qui, lo script che importa la seduta manda quel messaggio ad AgentsRoom, che apre un agente Claude nel giro di un secondo. È anche quello che rende il montaggio economico: un agente che interroga in loop brucia token a ogni giro, un trigger webhook non costa niente finché non succede niente.

Funziona per uno sport diverso dalla corsa?

Sì. L'importazione ricostruisce i giri dell'orologio, e anche il ciclismo e il nuoto registrano dei giri. Quello che cambia sono i file di strategia e il catalogo delle sedute, che sono testo che riscrivi tu. La meccanica (importazione, webhook, agente, repository) non si muove.

L'agente può sbagliare e distruggermi il piano?

Può sbagliare, ma non può distruggere granché: tutto quello che scrive è un commit Git che puoi leggere, contestare e annullare. Il file CLAUDE.md gli vieta esplicitamente di riscrivere lo storico, di inventare dati che non gli hai fornito, di cambiare il piano senza tracciare la ragione e di dare pareri medici. Un dolore sospetto, e ti manda da un professionista.

---

Il repository modello è qui: AgentsRoomDev/running-performance-coach. Clonalo, riempi i tuoi ritmi, e hai il tuo allenatore. Se vuoi vedere il pezzo che sveglia l'agente, è descritto nella pagina trigger webhook, e AgentsRoom si scarica qui.