Stavo preparando un hackathon sul green software e quello che doveva essere un esperimento veloce si è trasformato in quattro tool open source in cascata, ognuno estratto dal problema reale che il precedente aveva lasciato irrisolto.
Ma partiamo dall’inizio: tutto è nato da un generatore di personaggi per Dungeons & Dragons.
Lo so, non è esattamente il progetto che ci si aspetta di proporre in un hackathon sul green software. Ma aveva una logica: volevo testare se Claude Code potesse aiutarmi a scrivere codice green, non solo codice funzionante. Il D&D Character Builder era abbastanza semplice da costruire in fretta; avevo abbastanza competenza di dominio per capire se non funzionava a dovere ed era abbastanza complesso da essere interessante come banco di prova.
Il vincolo che mi sono dato era preciso: sostenibilità come first-class constraint dal primo commit, non come rifinitura di fine progetto. La domanda che mi facevo ad ogni decisione tecnica non era “funziona?” ma “quanto costa, in termini energetici, questa scelta rispetto all’alternativa?”
Quello che non mi aspettavo è che da quel piccolo esperimento sarebbe emerso, per stratificazione naturale, un toolkit completo.
Il secondo progetto
Validato l’approccio, ho alzato l’asticella con pdf-worker: un toolkit per la manipolazione di PDF con 36 tool, tutto client-side, zero upload al server. Esistono decine di tool simili; anche qui il punto non era l’innovazione della feature, ma testare i pattern green in un contesto realistico e con l’uso di risorse maggiori.
Cosa significa, concretamente, scrivere un’applicazione web con la sostenibilità come vincolo architetturale?
System fonts invece di Google Fonts (risparmio sul round-trip HTTP per i font che l’utente probabilmente ha già). Lazy-loaded workers: così il browser non carica codice che forse non servirà mai. Tree-shaken bundles, eliminando il codice morto lasciato in circolazione da molti bundler.
Sono buone pratiche che un developer attento già applica. La differenza è averle rese esplicite, misurabili e parte del contratto del progetto e non decisioni implicite lasciate al buon senso del momento.
Il CLAUDE.md come contratto tra developer e agente
Lavorando con Claude Code in modo intensivo su entrambi i progetti, ho capito una cosa: l’agente AI è bravo quanto il contesto che gli dai. Senza vincoli espliciti, ottimizza per ciò che sa fare meglio: codice funzionante, pulito e documentato. Tutto bene, ma non necessariamente green.
Da qui è nato il file CLAUDE.md incluso nel repository di pdf-worker. Ogni modifica che l’agente propone deve rispettare una serie di guardrail espliciti: soglie di performance del budget delle prestazioni, requisiti di accessibilità secondo WCAG 2.1, linee guida W3C Web Sustainability (WSG 1.0) e una baseline di Software Carbon Intensity (SCI) da non peggiorare.
Lo SCI (Software Carbon Intensity) è la metrica proposta dalla Green Software Foundation per misurare le emissioni di carbonio di un’applicazione software in modo operativo: carbonio emesso per unità funzionale, calcolabile e tracciabile nel tempo.
Il problema, mentre iteravo sulla scrittura del CLAUDE.md, era che non esisteva un modo semplice per calcolare effettivamente lo SCI. Serviva qualcosa di misurabile, non solo di dichiarabile.
SCI Profiler
sci-profiler è la risposta a quel problema. Una libreria TypeScript a zero dipendenze che usa performance.now() per misurare il tempo di esecuzione di operazioni specifiche e calcolare la Software Carbon Intensity secondo la formula della Green Software Foundation.
Vale la pena capire cosa c’è sotto, perché la formula SCI non è banale come sembra.
La Green Software Foundation la definisce così:
SCI = (E * I + M) / RDove:
- E è l’energia consumata dall’operazione (kWh)
- I è il carbon intensity della rete elettrica dove gira il software (gCO?eq/kWh) — e varia moltissimo: la rete svedese emette circa 13g per kWh, quella polacca oltre 700g
- M è il carbonio incorporato nell’hardware (embodied carbon), distribuito sulla vita utile del device
- R è l’unità funzionale di riferimento: per operazione, per utente, per richiesta API, per transazione — dipende da cosa stai misurando
Il risultato è espresso in gCO?eq per unità funzionale. Misurabile, confrontabile, tracciabile nel tempo.
Il punto metodologico che mi interessava era proprio R: avere una granularità per singola operazione invece che per l’applicazione intera. Sapere che la compressione di un PDF da 10 MB emette X grammi di CO? equivalente è un’informazione diversa e più utile rispetto a sapere che la tua app emette Y grammi al giorno. Ti permette di ottimizzare chirurgicamente ciò che conta davvero.
Wall time e non CPU time
Una scelta metodologica su cui vale la pena soffermarsi: Sci-profiler usa performance.now(), che misura il wall clock time, il tempo reale trascorso dall’inizio alla fine dell’operazione, incluse le attese I/O, le latenze di rete e gli accessi al filesystem.
La domanda ovvia è: non sarebbe più preciso misurare il CPU time, cioè solo i cicli effettivamente utilizzati dal processore?
Dal punto di vista dell’impatto ambientale, no. Quello che conta è quanto energia il sistema ha consumato in quel lasso di tempo, e il consumo energetico segue il tempo reale, non quello della CPU. Un server che aspetta una risposta dal database per 200 ms sta comunque consumando energia: memoria attiva, interfacce di rete in polling, processi OS in attesa. Non sono cicli CPU intensivi, ma sono comunque joule.
Il CPU time è la metrica giusta per ottimizzare l’efficienza computazionale pura. Il wall time è la metrica giusta per ottimizzare l’impatto energetico effettivo. Per il green software, è il secondo a contare.
C’è anche un argomento pratico: il wall time è misurabile ovunque con performance.now(), senza permessi speciali, senza dipendenze da API di sistema, senza differenze tra ambienti. Il CPU time richiederebbe accesso a perf_hooks in Node.js o ad API native del browser non disponibili in tutti i contesti.
import { SCIProfiler } from 'sci-profiler';
const profiler = new SCIProfiler({ region: 'IT' });
const result = await profiler.measure('pdf-compression', async () => {
await compressPDF(input);
});
console.log(`SCI: ${result.carbonGrams}g CO?eq per operazione`);
In pratica, lo sci-profiler misura il wall time, stima il consumo energetico a partire da un TDP medio del device (configurabile), applica la carbon intensity della regione specificata e distribuisce una quota di embodied carbon sulla vita utile stimata dell’hardware. Le stime sono approssimate; il TDP reale varia; il carbon intensity cambia in tempo reale in base al mix energetico della rete, ma l’ordine di grandezza è corretto e, soprattutto, il delta tra due versioni della stessa operazione è affidabile. È quello che serve per ottimizzare.
Drop-in, senza dipendenze: funziona in qualsiasi progetto TypeScript. Il report SCI e il report WSG di pdf-worker sono generati direttamente con questo approccio.
L’Agent Skill
A questo punto avevo tre pezzi separati: un CLAUDE.md con le specifiche green, una libreria per misurare il SCI, e due progetti su cui avevo applicato manualmente tutto questo. La domanda naturale era: posso impacchettare questa conoscenza in modo che chiunque possa puntarla su un progetto esistente e ottenere una valutazione?
La risposta è il Sustainable Agent Skill.
Il formato AgentSkills
Prima di descrivere cosa fa la skill, vale la pena capire il contesto in cui gira. Il formato AgentSkills è uno standard aperto, sviluppato originariamente da Anthropic e rilasciato come specifica pubblica, per fornire agli agenti AI capacità specifiche in modo portabile e versionabile. L’idea è semplice: una skill è una cartella con istruzioni, script e risorse che l’agente carica on-demand quando il task lo richiede.
Il punto di forza del formato è l’interoperabilità: la stessa skill funziona su Claude Code, Cursor, Windsurf, Cline e su oltre 30 tool compatibili che implementano la specifica. Per i team, questo significa che la conoscenza organizzativa “come facciamo le code review da noi”, “quali sono i nostri standard di accessibilità”, “come misuriamo la sostenibilità” diventa un artefatto versionabile su Git, non un documento Word dimenticato su Confluence.
Le skill usano progressive disclosure: l’agente carica prima i metadati (~100 token), poi il corpo completo all’attivazione e, infine, i file di riferimento solo nelle fasi in cui li richiedono. Questo ottimizza l’uso del context window, che non è infinito, un problema che, come ho scritto altrove, ho imparato a mie spese.
Cosa fa la skill in pratica
La skill guida l’agente attraverso un workflow in 9 fasi:
- Explore — ricognizione della codebase, stack e architettura
- Energy & Carbon (SCI) — misurazione della carbon intensity per operazione tramite sci-profiler
- WSG Compliance — valutazione rispetto a tutte le 80 linee guida W3C Web Sustainability Guidelines 1.0
- Accessibility — setup di Lighthouse CI con soglie WCAG 2.1 AA
- Performance & Resource Efficiency — bundle size, lazy loading, caching, font, immagini
- Testing & Quality — infrastruttura di test, coverage, critical path
- Prioritize — ranking delle azioni per impatto × fattibilità (P0–P3)
- Establish Baselines — target misurabili per ogni dimensione
- Sustainability-Aware CLAUDE.md — codifica la sostenibilità nel workflow di sviluppo continuativo
L’output finale non è un report da leggere e dimenticare: è un piano d’azione prioritizzato con baseline concrete, più un CLAUDE.md aggiornato che rende quei vincoli permanenti nel progetto.
Come si estende
La skill, nella versione attuale, è ottimizzata per lo stack TypeScript/JavaScript: il contesto in cui è nata. sci-profiler usa performance.now(), le WSG sono pensate per il web, Lighthouse CI è uno strumento del browser ecosystem.
Ma i principi scelti, cioè misurare lo SCI per operazione, validare secondo lo standard W3C e generare un piano prioritizzato, sono agnostici al linguaggio.
Ho poi esteso il ragionamento a PHP creando un primo prototipo: sci-profiler-php. In questo caso, l’approccio usato è leggermente diverso rispetto alla versione in TypeScript, in modo che rifletta la natura del runtime.
Invece di instrumentare singole operazioni nel codice, usa la direttiva auto_prepend_file di PHP per iniettare il profiling prima di ogni esecuzione. Zero modifiche al codice applicativo. Zero wrapper da aggiungere ai controller, alle route, ai plugin. Il profiler si aggancia a livello di configurazione — php.ini, un pool FPM, il virtualhost — e da lì misura ogni richiesta HTTP come unità funzionale completa: dal momento in cui PHP inizia a eseguire fino allo shutdown, incluse query al database, chiamate a servizi esterni, accessi al filesystem. L’unità di misura non è la funzione, ma la richiesta complessiva, ossia la domanda che conta davvero: quanto carbonio emette questa pagina di WordPress? Quanto emette questa rotta di Laravel?
I risultati vengono esportati in tre reporter: JSON lines per l’analisi automatica, un log human-readable e un dashboard HTML in linea per visualizzare l’andamento senza installare nulla di aggiuntivo. Framework-agnostic (Laravel, Symfony, WordPress, Drupal, PHP vanilla) e fail-safe per il design: eventuali errori nel profiler non compromettono mai l’applicazione host. Ovviamente, il target esplicito è lo staging e lo sviluppo.
Python aprirebbe il capitolo sui workload ML e sui data pipeline, in cui il consumo energetico per operazione può essere di ordini di grandezza superiore rispetto al web tradizionale. Librerie come CodeCarbon o le API di Hugging Face per l’impatto dei modelli potrebbero essere integrate come sorgenti dati alternative per il parametro E della formula SCI.
La direzione più interessante in assoluto è separare la skill in un layer metodologico — le fasi, i criteri, il piano d’azione — e in un layer di implementazione per linguaggio, che specifica come si misura e, in quel contesto, come si misura. Il formato AgentSkills supporta già questa modularità attraverso i file di riferimento nella cartella references/: aggiungere un references/sci-php.md o references/sci-python.md è esattamente il tipo di contributo che ha senso fare senza toccare la struttura della skill.
La skill sul primo progetto, risultati concreti
Ho puntato la skill sul D&D Character Builder, il progetto di partenza. Ha identificato due antipattern che mi erano sfuggiti sotto il naso.
Il primo: jsPDF era ancora in package.json — libreria che avevo usato in una versione precedente, rimossa dal codice ma mai dalla lista delle dipendenze. Il bundler la includeva nel build senza che nessun componente la richiedesse. Pruning e tree shaking espliciti l’hanno eliminata, riducendo il bundle finale.
Il secondo: il caching era corretto ma incompleto. Il service worker gestiva bene le risorse statiche, ma alcune informazioni venivano ricalcolate ad ogni sessione senza necessità. La skill ha identificato dove aggiungere il caching client-side, senza toccare i cookie di terze parti che il progetto non usa per scelta architetturale.
Sul fronte dell’accessibilità, il report WSG segnalava come gap l’assenza di validazione automatica (linea guida 3.20). La skill ha generato tutti i tag ARIA mancanti e ha configurato Lighthouse CI con la soglia WCAG 2.1 AA.
I numeri finali nel report WSG: su 80 linee guida totali, 14 risultano N/A per la natura del progetto (solo developer, nessun server dedicato). Delle 66 applicabili: 34 full compliance (52%), 21 partial (32%), 11 gap residui — tutti documentati con action item e stima dell’effort. Per lo SCI, il delta spazia tra il 64% e il 7% per operazione rispetto alla baseline pre-ottimizzazione, misurato con lo SCI-Profiler sulle operazioni critiche del generatore.
Ovviamente non sono numeri da benchmark di settore essendo un progetto personale su GitHub Pages, ma il punto non è il risultato assoluto: è che adesso sono misurabili, tracciabili e migliorabili nel tempo. Prima di questo processo, non lo erano.
Il pattern che emerge, e perché è abduttivo
C’è una lezione metodologica in tutto questo che vale la pena rendere esplicita, perché si applica ben oltre il green software.
Ognuno di questi tool è stato estratto da un problema reale emerso nel progetto precedente, non progettato in astratto con l’obiettivo di “costruire un toolkit”. Il CLAUDE.md è emerso dalla necessità di fornire un contesto coerente all’agente. Lo sci-profiler è emerso dalla necessità di disporre di dati concreti nel file CLAUDE.md. L’Agent Skill è emersa dalla necessità di rendere ripetibile ciò che avevo fatto a mano.
Il metodo usato non è stato né induttivo (non stavo generalizzando da molti casi simili) né deduttivo (non stavo applicando regole note a un problema noto), ma abduttivo: di fronte a ogni risultato inatteso, mi sono chiesto qual era la spiegazione più plausibile e la mossa più sensata da lì in poi. È la stessa logica che Peirce aveva formalizzato nell’800 e che continua a essere il motore reale dell’innovazione pratica, molto più della deduzione applicata a specifiche perfette.
È lo stesso principio che applico quando lavoro con i clienti sugli OKR: i KPI non si disegnano in astratto, si identificano le domande a cui stai cercando risposta e si costruiscono le metriche intorno a esse. La misura deve emergere dal problema.
Questo approccio produce tool più onesti. Hanno bordi netti perché risolvono un problema specifico. Non hanno feature inutili perché non sono stati progettati per impressionare, ma per servire.
Dove iniziare
Tutto è open source (MIT). Il percorso più diretto è clonare sustainable-code-skill-setup, puntarlo sulla tua codebase e leggere il report che genera. Da lì hai una baseline. Integrare lo sci-profiler (o il suo analogo per php) nelle operazioni critiche per ottenere misure operative nel tempo e adatta il CLAUDE.md al tuo progetto, indicando i vincoli che desideri monitorare.
Se il tuo stack è PHP, sci-profiler-php ti permette di aggiungere il profiling SCI a livello di configurazione, senza toccare una riga di codice applicativo — WordPress, Laravel, Symfony o PHP vanilla, fa poca differenza.
Sono curioso di sapere cosa sta accadendo all’intersezione tra sviluppo assistito dall’AI e green software al di là della mia esperienza diretta. Scrivimi se vuoi confrontarti.