Flusso di Lavoro con l'IA

Questo progetto è stato costruito con Claude Code. La maggior parte delle dichiarazioni “costruito con l’IA” si ferma all’etichetta. Qui c’è il quadro completo: cosa sa l’IA, come funzionano le sessioni, come appare il prompting nella pratica e dove l’essere umano traccia il confine. Se stai costruendo con l’IA anche tu, o sei semplicemente curioso di sapere come funziona davvero, questa pagina è per te.

Cosa Sa l’IA

Claude Code ha un file di memoria persistente che trasporta il contesto tra una sessione e l’altra. Invece di ri-esplorare il codebase ad ogni conversazione, riprende da dove avevamo lasciato. Ecco cosa contiene (sanitizzato):

Identità del Progetto

Nome dell’app, posizione del sorgente, licenza, identificatore dell’app
Relazione di fork: l’upstream è En Croissant di Francisco Salgueiro, noi manteniamo il nostro fork in modo indipendente
Perché esiste il fork: il maintainer upstream ha declinato la funzionalità TTS, il che è legittimo — visioni diverse per lo stesso progetto

Regole di Build

Solo pnpm — npm rompe vanillaExtract (schermo bianco a runtime, nessun errore, semplicemente nulla)
Node.js 22+ richiesto (Vite 7 necessita di crypto.hash)
Sempre pnpm format && pnpm lint:fix prima di fare commit
Chiudere l’app prima di sovrascrivere il binario (“Text file busy”)
Dopo aver spostato directory sorgente, cargo clean per eliminare i riferimenti a percorsi obsoleti

Conoscenza dell’Architettura

Quali file gestiscono quali funzionalità (atom in atoms.ts, navigazione dell’albero in tree.ts, motore TTS in tts.ts)
Perché tutti gli atom TTS necessitano di getOnInit: true (letture imperative tramite store.get() prima che React si sottoscriva)
Come funziona la cache audio (chiavi provider:voiceId:lang:text)
Il fix delle coordinate di chessground è lato CSS, non un fork della libreria
Layout dei dati: cosa risiede dove, cosa è collegato tramite symlink, cosa sopravvive ai riavvii dell’app

Cosa Non Sa

La memoria non contiene chiavi API, password o credenziali. Fa riferimento alle loro posizioni di archiviazione (nomi degli atom in localStorage) ma mai ai valori. L’IA genera codice che legge le chiavi dalle impostazioni — non vede né gestisce mai i segreti reali.

Cosa Viene Detto all’IA

Oltre al file di memoria, Claude Code segue regole integrate nel suo sistema:

Non sovra-ingegnerizzare. Apportare solo le modifiche direttamente richieste. Un bugfix non richiede la pulizia del codice circostante. Tre righe di codice simili sono meglio di un’astrazione prematura.
Non inventare URL. Non fabbricare mai link o endpoint.
Leggere prima di modificare. Non proporre mai modifiche a codice che non è stato letto.
Preferire la modifica alla creazione. Non creare nuovi file a meno che non sia assolutamente necessario.
Nessuna vulnerabilità di sicurezza. Attenzione a injection, XSS e problematiche della OWASP top 10.
Chiedere in caso di incertezza. Se un’istruzione è ambigua, chiedere piuttosto che tirare a indovinare.
Misurare due volte, tagliare una. Operazioni distruttive (force push, reset —hard, eliminazione di file) richiedono approvazione esplicita da parte dell’umano.

Scrivere Buoni Prompt

La differenza tra un’interazione utile con l’IA e una frustrante è quasi sempre il prompt.

Essere specifici su cosa si vuole. Non “sistema il bug” ma “la chiave della cache TTS non include il nome del provider, quindi passando da ElevenLabs a Google viene riprodotto l’audio di ElevenLabs dalla cache invece di generare nuovo audio.”

Includere il contesto che l’IA non ha. L’IA può leggere il tuo codice, ma non può leggere la tua mente. “L’utente ha segnalato che le coordinate sono invertite sulla scacchiera” è meno utile di “il CSS in chessgroundBaseOverride.css ha righe e colonne invertite — l’originale di Francisco le aveva al contrario.”

Dichiarare i propri vincoli. “Non creare nuovi file” o “usa il pattern degli atom esistenti” o “deve funzionare senza una chiave API” dicono all’IA dove sono i paletti.

Dire cosa non si vuole. “Non aggiungere gestione degli errori per casi che non possono verificarsi” o “non rifattorizzare il codice circostante” previene la sovra-ingegnerizzazione — la modalità di fallimento più comune dell’IA.

Lo schema è: intento + contesto + vincoli. Padroneggia questo e l’IA diventa drammaticamente più utile.

Modalità Piano: Usare un Claude per Fare il Prompt a un Altro

Claude Code ha una “modalità piano” che separa il pensiero dall’azione. In modalità piano, l’IA legge i file, esplora il codebase e produce un piano — ma non scrive codice. Tu revisioni il piano, lo aggiusti, poi passi alla modalità implementazione dove l’IA lo esegue.

Perché funziona? Perché la parte più difficile di qualsiasi compito di programmazione non è scrivere il codice. È capire quale codice scrivere — quali file modificare, quali pattern seguire, quali casi limite esistono. La modalità piano dedica piena attenzione a questa domanda prima che venga scritta una singola riga.

Da questo progetto: quando abbiamo ristrutturato il menu Aiuto per aggiungere il selettore della lingua, la conversazione in modalità piano ha esplorato come funzionano i menu di Tauri, quali atom esistevano già, come il visualizzatore di documentazione risolveva i percorsi delle risorse e come appariva l’API della finestra di conferma. Nel momento in cui siamo passati all’implementazione, l’IA aveva una mappa completa delle modifiche. Nessuna falsa partenza.

In sostanza stai usando un’istanza dell’IA come architetto senior e un’altra come sviluppatore. Stesso modello, ruoli diversi.

Come Funzionano le Sessioni

Una sessione tipica si presenta così:

L’umano dichiara l’intento. “Aggiungi una nota sulla cache nella sezione KittenTTS.” “Rimuovi la telemetria PostHog.” “Le valutazioni di qualità sono sbagliate, ecco quali dovrebbero essere.”
L’IA legge i file rilevanti. Non indovina cosa c’è in un file. Lo legge, comprende lo stato attuale, poi propone le modifiche. Più file vengono letti in parallelo quando sono indipendenti.
L’IA apporta la modifica. Modifiche mirate ai file esistenti. Non riscritture — modifiche chirurgiche che preservano tutto ciò che le circonda.
L’umano revisiona. Ogni modifica viene mostrata prima di essere scritta su disco. L’umano approva, rifiuta o reindirizza. “No, è troppo morbido — dì che fa genuinamente schifo.” “Sposta quel paragrafo più su.” “Non è quello che intendevo.”
Commit su comando. L’IA non fa mai commit di propria iniziativa. L’umano dice “commit” o “commit and push.” I commit includono Co-Authored-By: Claude Opus 4.6 — sempre attribuiti, mai nascosti.

Finestre di Contesto e Punti di Salvataggio

Ogni conversazione con l’IA ha una finestra di contesto — la quantità totale di testo che può mantenere in memoria contemporaneamente. Quando la conversazione diventa abbastanza lunga, i messaggi più vecchi vengono compressi per fare spazio.

Due strategie: mantenere le conversazioni focalizzate (un compito per conversazione), e usare i punti di salvataggio (Claude Code salva le trascrizioni come file JSONL da cui puoi riprendere con il contesto completo ripristinato). Il file di memoria ha uno scopo diverso — è una base di conoscenza persistente che sopravvive attraverso tutte le conversazioni.

Cosa Propone l’IA vs. Cosa Viene Rilasciato

Il primo suggerimento dell’IA è raramente la versione finale. Uno scambio tipico:

L’IA redige qualcosa di ragionevole
L’umano dice “troppo aziendale” o “sii più diretto” o “è sbagliato, ecco perché”
L’IA aggiusta
L’umano approva

Il gusto, il tono e la decisione finale sono sempre umani. L’IA gestisce la velocità — leggere file, comprendere il contesto, apportare modifiche precise attraverso un codebase che può tenere in memoria. L’umano gestisce il giudizio — cosa costruire, come deve risultare, quando fermarsi.

Skill e Comandi Slash

Claude Code supporta le “skill” — prompt riutilizzabili salvati come file markdown nella directory .claude/commands/. Si invocano con un comando slash, come /translate-docs.

Questo progetto usa una skill /translate-docs che automatizza la traduzione della documentazione in più lingue. Il file della skill contiene le istruzioni complete: quali file tradurre, quale formato usare, come gestire blocchi di codice e link, quale tono mantenere. Invece di spiegare tutto questo ogni volta, basta digitare /translate-docs e l’IA sa esattamente cosa fare.

Le skill codificano processi, non solo informazioni. Puoi costruirle per qualsiasi flusso di lavoro ricorrente: eseguire test, fare deploy, revisionare PR, aggiornare changelog.

Principi di Programmazione

Il documento completo dei principi si trova nel repository a .claude/01_UNIVERSAL_PRINCIPLES.md. È nato dal Clean Code (2008) di Robert C. Martin più aggiunte per l’era dell’IA. Poi abbiamo avuto una conversazione onesta su cosa regge ancora e cosa no.

Cosa È Senza Tempo

Nomi che rivelano l’intento. Sempre. Per sempre.
Le funzioni fanno una cosa sola. Il vero principio è la coerenza, non la dimensione.
Nessun effetto collaterale. Ancora la fonte della maggior parte dei bug.
I commenti spiegano il perché, non il cosa.
Responsabilità Unica. Un modulo dovrebbe avere un solo motivo per cambiare.
Programmare verso le interfacce, non le implementazioni.
Non ingoiare gli errori. Ogni errore è informazione.
Design emergente: esegue tutti i test, nessuna duplicazione, esprime l’intento, minimizza la complessità. In quest’ordine.

Cosa È Contestuale

Questi principi sono solidi, ma le regole specifiche riflettono un mondo pre-IA o specifico di un linguaggio. Applichiamo lo spirito, non la lettera:

DRY. La duplicazione che diverge nel tempo è pericolosa. Ma estrarre ogni pattern ripetuto in un’astrazione crea un’indirezione che può essere peggiore. A volte tre righe leggibili qui e ora sono meglio di un’astrazione prematura in un altro file.
Cerimonia rigorosa del TDD. Il principio — rilasciare codice testato, sapere che funziona — non è negoziabile. La cerimonia — il test deve esistere prima del codice — è stata progettata per un flusso di lavoro dove gli umani digitano lentamente. Scrivi i test. Assicurati che passino. Se sia nato prima il test o il codice è meno importante del fatto che entrambi esistano.
La Regola del Boy Scout. “Lascia il campeggio più pulito” — sì. Ma il boy scout puliva il campeggio, non l’intera foresta. Sistema ciò che tocchi. Non rifattorizzare l’intera struttura di un file perché hai cambiato una riga al suo interno.

Aggiunte dell’Era dell’IA

La guida basata su principi scala meglio delle regole. Il principio consente il giudizio; la regola è fragile.
Se l’agente lo costruisce, l’agente può mantenerlo. Conserva il contesto della conversazione e gli artefatti. Documenta il processo di costruzione, non solo il risultato.
Chiaro più che furbo. Il sistema che ha costruito questo deve poter ricostruire il ragionamento e modificarlo correttamente. La struttura esplicita batte le piccole astrazioni furbe.
Potrebbe diventare infrastruttura? Uno strumento risolve un problema per te. Un’infrastruttura consente ad altri di costruirci sopra. Progetta di conseguenza.

Dove l’Umano Traccia il Confine

L’IA è uno strumento. Uno notevolmente buono. Ma ci sono cose che non fa:

Decisioni di prodotto. Quali funzionalità costruire, cosa tagliare, come dovrebbe risultare l’app. “La valutazione di qualità del System TTS dovrebbe dire ‘passabile’ perché fa genuinamente schifo” — quello è un giudizio umano basato sull’averlo effettivamente ascoltato.
Gusto. L’IA può scrivere prosa pulita, ma la voce del progetto, la decisione di essere schietti sulla qualità, la scelta di dare credito prominente a Francisco — quelle sono scelte umane.
Etica. Rimuovere PostHog non era un compito di refactoring. Era “la pagina delle impostazioni dice che non raccogliamo telemetria, ma c’è una chiave API PostHog attiva nel codice. Questa è una bugia. Sistemala.” L’IA ha eseguito. L’umano ha identificato il problema e se n’è preoccupato.
Scacchi. Alla scacchiera non interessa dei tuoi strumenti.

Perché Condividere Questo

Perché “costruito con l’IA” è diventato privo di significato. Tutti lo dicono. Nessuno lo mostra. La domanda interessante non è se l’IA sia stata coinvolta — è come è stata coinvolta, e cosa l’umano abbia effettivamente contribuito.

Questa è la risposta. L’umano porta la visione, il gusto, il giudizio e la responsabilità. L’IA porta la velocità, la memoria e l’instancabile disponibilità a leggere messaggi di errore di Rust alle 2 di notte.

Nessuno dei due costruisce questa cosa da solo. Entrambi sono accreditati. Questo è il patto.

En Parlant~ è un fork di En Croissant di Francisco Salgueiro, costruito con Claude Code di Anthropic.