Lo so, non \u00e8 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<\/em>, 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.<\/p>\n\n\n\n Il vincolo che mi sono dato era preciso: sostenibilit\u00e0 come first-class constraint dal primo commit<\/strong>, 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?”<\/p>\n\n\n\n Quello che non mi aspettavo \u00e8 che da quel piccolo esperimento sarebbe emerso, per stratificazione naturale, un toolkit completo.<\/p>\n\n\n\n Validato l’approccio, ho alzato l’asticella con pdf-worker<\/a>: 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.<\/p>\n\n\n\n Cosa significa, concretamente, scrivere un’applicazione web con la sostenibilit\u00e0 come vincolo architetturale?<\/p>\n\n\n\n System fonts invece di Google Fonts (risparmio sul round-trip HTTP per i font che l’utente probabilmente ha gi\u00e0). Lazy-loaded workers: cos\u00ec il browser non carica codice che forse non servir\u00e0 mai. Tree-shaken bundles, eliminando il codice morto lasciato in circolazione da molti bundler. <\/p>\n\n\n\n Sono buone pratiche che un developer attento gi\u00e0 applica. La differenza \u00e8 averle rese esplicite, misurabili e parte del contratto del progetto e non decisioni implicite lasciate al buon senso del momento.<\/p>\n\n\n\n Lavorando con Claude Code in modo intensivo su entrambi i progetti, ho capito una cosa: l’agente AI \u00e8 bravo quanto il contesto che gli dai. Senza vincoli espliciti, ottimizza per ci\u00f2 che sa fare meglio: codice funzionante, pulito e documentato. Tutto bene, ma non necessariamente green<\/em>.<\/p>\n\n\n\n Da qui \u00e8 nato il file CLAUDE.md<\/a> 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\u00e0 secondo WCAG 2.1, linee guida W3C Web Sustainability (WSG 1.0) e una baseline di Software Carbon Intensity (SCI) da non peggiorare.<\/p>\n\n\n\n Lo SCI (Software Carbon Intensity) \u00e8 la metrica proposta dalla Green Software Foundation<\/a> per misurare le emissioni di carbonio di un’applicazione software in modo operativo: carbonio emesso per unit\u00e0 funzionale, calcolabile e tracciabile nel tempo. <\/p>\n\n\n\n Il problema, mentre iteravo sulla scrittura del CLAUDE.md, era che non esisteva un modo semplice per calcolare<\/em> effettivamente lo SCI. Serviva qualcosa di misurabile, non solo di dichiarabile.<\/p>\n\n\n\n sci-profiler<\/a> \u00e8 la risposta a quel problema. Una libreria TypeScript a zero dipendenze che usa Vale la pena capire cosa c’\u00e8 sotto, perch\u00e9 la formula SCI non \u00e8 banale come sembra.<\/p>\n\n\n\n La Green Software Foundation la definisce cos\u00ec:<\/p>\n\n\n\n Dove:<\/p>\n\n\n\n Il risultato \u00e8 espresso in gCO?eq per unit\u00e0 funzionale. Misurabile, confrontabile, tracciabile nel tempo.<\/p>\n\n\n\n Il punto metodologico che mi interessava era proprio R<\/strong>: avere una granularit\u00e0 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 \u00e8 un’informazione diversa e pi\u00f9 utile rispetto a sapere che la tua app emette Y grammi al giorno. Ti permette di ottimizzare chirurgicamente ci\u00f2 che conta davvero.<\/p>\n\n\n\n Una scelta metodologica su cui vale la pena soffermarsi: Sci-profiler usa La domanda ovvia \u00e8: non sarebbe pi\u00f9 preciso misurare il CPU time, cio\u00e8 solo i cicli effettivamente utilizzati dal processore?<\/p>\n\n\n\n Dal punto di vista dell’impatto ambientale, no. Quello che conta \u00e8 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.<\/p>\n\n\n\n Il CPU time \u00e8 la metrica giusta per ottimizzare l’efficienza computazionale pura. Il wall time \u00e8 la metrica giusta per ottimizzare l’impatto energetico effettivo. Per il green software, \u00e8 il secondo a contare.<\/p>\n\n\n\n C’\u00e8 anche un argomento pratico: il wall time \u00e8 misurabile ovunque con 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 \u00e8 corretto e, soprattutto, il delta tra due versioni della stessa operazione \u00e8 affidabile. \u00c8 quello che serve per ottimizzare.<\/p>\n\n\n\n Drop-in, senza dipendenze: funziona in qualsiasi progetto TypeScript. Il report SCI<\/a> e il report WSG<\/a> di pdf-worker sono generati direttamente con questo approccio.<\/p>\n\n\n\n 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?<\/p>\n\n\n\n La risposta \u00e8 il Sustainable Agent Skill<\/a>.<\/p>\n\n\n\n Prima di descrivere cosa fa la skill, vale la pena capire il contesto in cui gira. Il formato AgentSkills<\/a> \u00e8 uno standard aperto, sviluppato originariamente da Anthropic e rilasciato come specifica pubblica, per fornire agli agenti AI capacit\u00e0 specifiche in modo portabile e versionabile. L’idea \u00e8 semplice: una skill \u00e8 una cartella con istruzioni, script e risorse che l’agente carica on-demand quando il task lo richiede.<\/p>\n\n\n\n Il punto di forza del formato \u00e8 l’interoperabilit\u00e0: 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\u00e0”, “come misuriamo la sostenibilit\u00e0” diventa un artefatto versionabile su Git, non un documento Word dimenticato su Confluence.<\/p>\n\n\n\n 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 \u00e8 infinito, un problema che, come ho scritto altrove<\/a>, ho imparato a mie spese.<\/p>\n\n\n\n La skill guida l’agente attraverso un workflow in 9 fasi:<\/p>\n\n\n\n L’output finale non \u00e8 un report da leggere e dimenticare: \u00e8 un piano d’azione prioritizzato con baseline concrete, pi\u00f9 un CLAUDE.md aggiornato che rende quei vincoli permanenti nel progetto.<\/p>\n\n\n\n La skill, nella versione attuale, \u00e8 ottimizzata per lo stack TypeScript\/JavaScript: il contesto in cui \u00e8 nata. sci-profiler usa Ma i principi scelti, cio\u00e8 misurare lo SCI per operazione, validare secondo lo standard W3C e generare un piano prioritizzato, sono agnostici al linguaggio. <\/p>\n\n\n\n Ho poi esteso il ragionamento a PHP<\/strong> creando un primo prototipo: sci-profiler-php<\/a>. In questo caso, l’approccio usato \u00e8 leggermente diverso rispetto alla versione in TypeScript, in modo che rifletta la natura del runtime.<\/p>\n\n\n\n Invece di instrumentare singole operazioni nel codice, usa la direttiva 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 \u00e8 lo staging e lo sviluppo.<\/p>\n\n\n\n Python <\/strong>aprirebbe il capitolo sui workload ML e sui data pipeline, in cui il consumo energetico per operazione pu\u00f2 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.<\/p>\n\n\n\n La direzione pi\u00f9 interessante in assoluto \u00e8 separare la skill in un layer metodologico \u2014 le fasi, i criteri, il piano d’azione \u2014 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\u00e0 questa modularit\u00e0 attraverso i file di riferimento nella cartella Ho puntato la skill sul D&D Character Builder, il progetto di partenza. Ha identificato due antipattern che mi erano sfuggiti sotto il naso.<\/p>\n\n\n\n Il primo: jsPDF era ancora in Il secondo: il caching era corretto ma incompleto<\/strong>. Il service worker gestiva bene le risorse statiche, ma alcune informazioni venivano ricalcolate ad ogni sessione senza necessit\u00e0. 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.<\/p>\n\n\n\n Sul fronte dell’accessibilit\u00e0, 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.<\/p>\n\n\n\n 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 \u2014 tutti documentati con action item e stima dell\u2019effort. 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.<\/p>\n\n\n\n Ovviamente non sono numeri da benchmark di settore essendo un progetto personale su GitHub Pages, ma il punto non \u00e8 il risultato assoluto: \u00e8 che adesso sono misurabili, tracciabili e migliorabili<\/strong> nel tempo. Prima di questo processo, non lo erano.<\/p>\n\n\n\n C’\u00e8 una lezione metodologica in tutto questo che vale la pena rendere esplicita, perch\u00e9 si applica ben oltre il green software.<\/p>\n\n\n\n Ognuno di questi tool \u00e8 stato estratto da un problema reale emerso<\/strong> nel progetto precedente, non progettato in astratto con l’obiettivo di “costruire un toolkit”. Il CLAUDE.md \u00e8 emerso dalla necessit\u00e0 di fornire un contesto coerente all’agente. Lo sci-profiler \u00e8 emerso dalla necessit\u00e0 di disporre di dati concreti nel file CLAUDE.md. L’Agent Skill \u00e8 emersa dalla necessit\u00e0 di rendere ripetibile ci\u00f2 che avevo fatto a mano.<\/p>\n\n\n\n Il metodo usato non \u00e8 stato n\u00e9 induttivo (non stavo generalizzando da molti casi simili) n\u00e9 deduttivo (non stavo applicando regole note a un problema noto), ma abduttivo<\/strong>: di fronte a ogni risultato inatteso, mi sono chiesto qual era la spiegazione pi\u00f9 plausibile e la mossa pi\u00f9 sensata da l\u00ec in poi. \u00c8 la stessa logica che Peirce aveva formalizzato nell’800<\/a> e che continua a essere il motore reale dell’innovazione pratica, molto pi\u00f9 della deduzione applicata a specifiche perfette.<\/p>\n\n\n\n \u00c8 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.<\/p>\n\n\n\n Questo approccio produce tool pi\u00f9 onesti. Hanno bordi netti perch\u00e9 risolvono un problema specifico. Non hanno feature inutili perch\u00e9 non sono stati progettati per impressionare, ma per servire.<\/p>\n\n\n\n Tutto \u00e8 open source (MIT). Il percorso pi\u00f9 diretto \u00e8 clonare sustainable-code-skill-setup<\/a>, puntarlo sulla tua codebase e leggere il report che genera. Da l\u00ec 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.<\/p>\n\n\n\n Se il tuo stack \u00e8 PHP, sci-profiler-php<\/a> ti permette di aggiungere il profiling SCI a livello di configurazione, senza toccare una riga di codice applicativo \u2014 WordPress, Laravel, Symfony o PHP vanilla, fa poca differenza.<\/p>\n\n\n\n![\"\"](\"https:\/\/i0.wp.com\/www.fullo.net\/blog\/wp-content\/uploads\/2026\/03\/frankenstein-junior-jr-1799166-1.gif?resize=454%2C250&ssl=1\")
<\/a><\/figure>\n\n\n\nIl secondo progetto<\/h3>\n\n\n\n
Il CLAUDE.md come contratto tra developer e agente<\/h3>\n\n\n\n
SCI Profiler<\/h3>\n\n\n\n
performance.now()<\/code> per misurare il tempo di esecuzione di operazioni specifiche e calcolare la Software Carbon Intensity secondo la formula della Green Software Foundation.<\/p>\n\n\n\nSCI = (E * I + M) \/ R<\/code><\/pre>\n\n\n\n\n
Wall time e non CPU time<\/h4>\n\n\n\n
performance.now()<\/code>, 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.<\/p>\n\n\n\nperformance.now()<\/code>, senza permessi speciali, senza dipendenze da API di sistema, senza differenze tra ambienti. Il CPU time richiederebbe accesso a perf_hooks<\/code> in Node.js o ad API native del browser non disponibili in tutti i contesti. <\/p>\n\n\n\nimport { SCIProfiler } from 'sci-profiler';\n\nconst profiler = new SCIProfiler({ region: 'IT' });\nconst result = await profiler.measure('pdf-compression', async () => {\n await compressPDF(input);\n});\n\nconsole.log(`SCI: ${result.carbonGrams}g CO?eq per operazione`);\n<\/code><\/pre>\n\n\n\nL’Agent Skill<\/h3>\n\n\n\n
Il formato AgentSkills<\/h4>\n\n\n\n
Cosa fa la skill in pratica<\/h3>\n\n\n\n
\n
Come si estende<\/h3>\n\n\n\n
performance.now()<\/code>, le WSG sono pensate per il web, Lighthouse CI \u00e8 uno strumento del browser ecosystem.<\/p>\n\n\n\nauto_prepend_file<\/code> 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 \u2014 php.ini<\/code>, un pool FPM, il virtualhost \u2014 e da l\u00ec misura ogni richiesta HTTP come unit\u00e0 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\u00e0 di misura non \u00e8 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?<\/p>\n\n\n\nreferences\/<\/code>: aggiungere un references\/sci-php.md<\/code> o references\/sci-python.md<\/code> \u00e8 esattamente il tipo di contributo che ha senso fare senza toccare la struttura della skill.<\/p>\n\n\n\nLa skill sul primo progetto, risultati concreti<\/h3>\n\n\n\n
package.json<\/code><\/strong> \u2014 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.<\/p>\n\n\n\n![\"\"](\"https:\/\/i0.wp.com\/www.fullo.net\/blog\/wp-content\/uploads\/2026\/03\/Screenshot-2026-03-13-alle-13.13.18.png?resize=580%2C286&ssl=1\")
<\/a><\/figure>\n\n\n\nIl pattern che emerge, e perch\u00e9 \u00e8 abduttivo<\/h3>\n\n\n\n
Dove iniziare<\/h2>\n\n\n\n