Come pulire un export CSV con Claude Code senza alterare l'originale

Un export CSV raramente è pronto per essere importato o analizzato. Le date possono avere formati diversi, i numeri possono usare separatori incoerenti, le colonne possono cambiare nome e alcune righe possono essere incomplete. Correggere tutto a mano sembra rapido finché non devi spiegare quali valori hai trasformato, quali righe hai scartato e se il totale coincide ancora con l'ingresso.

Claude Code può lavorare sui file della directory ed eseguire strumenti nel perimetro autorizzato. Questo lo rende adatto a costruire una trasformazione ripetibile, purché il compito non inizi con “pulisci il file”. Prima devi congelare l'originale, definire lo schema di uscita e osservare i problemi senza correggerli. Anthropic, come funziona Claude Code.

Il risultato corretto non è un unico CSV apparentemente ordinato. È un pacchetto composto da file pulito, file degli scarti, report delle trasformazioni e prova di quadratura.

La pulizia non deve cancellare il problema

Quando una data come 03/04/26 viene trasformata in 2026-04-03, hai compiuto un'interpretazione. In alcuni sistemi quella data potrebbe significare 4 marzo. Quando due contatti hanno la stessa email, unirli può sembrare ragionevole, ma potresti cancellare una relazione distinta. Quando un importo non è valido, sostituirlo con zero cambia il significato del dato.

Una pulizia controllata separa tre casi:

• trasformazione deterministica, quando la regola è approvata e non perde significato;

• eccezione, quando serve una decisione umana o una fonte aggiuntiva;

• errore strutturale, quando la riga non può essere letta secondo il contratto.

Le eccezioni non sono rumore da nascondere. Sono parte del risultato. Se spariscono, il file pulito non permette più di capire che cosa non è stato trasformato.

Conserva l'export originale

Copia l'export in una cartella di lavoro e trattalo come immutabile. Non rinominarne le colonne, non correggere valori e non salvarlo dallo strumento che potrebbe modificarne codifica o separatori. Puoi assegnargli un nome stabile che includa la data di acquisizione, ma conserva anche il nome originario nel registro.

Una struttura minima è:

csv-cleanup/
  input/
    export-originale-2026-09-06.csv
  rules/
    schema-output.md
    regole-trasformazione.md
  output/
  tests/
    fixtures/

Limita le modifiche alla cartella output e agli script creati per il lavoro. La documentazione di Claude Code permette di configurare regole allow, ask e deny; le regole più restrittive possono proteggere input e percorsi non pertinenti. Anthropic, permessi di Claude Code.

Conservare l'originale ti permette di ripetere la trasformazione dopo una correzione delle regole. Senza quella copia, ogni tentativo parte da uno stato diverso e il confronto perde valore.

Descrivi lo schema di uscita

Lo schema non è soltanto un elenco di colonne. Per ciascun campo descrivi nome, tipo, obbligatorietà, formato, valori ammessi e comportamento quando il dato manca.

La regola “sistema i valori mancanti” è pericolosa perché non dice se lasciare vuoto, scartare la riga o ricostruire da un'altra fonte. Ogni campo deve avere un comportamento esplicito.

Questo schema è un'applicazione concreta del contratto degli input di un workflow AI: prima di trasformare, dichiari che cosa è accettabile e che cosa deve fermarsi.

Profila il file prima di correggerlo

Avvia Claude Code in modalità plan o chiedi esplicitamente una fase di sola lettura. La documentazione sui flussi comuni descrive la modalità plan come un modo per analizzare il progetto e proporre il lavoro prima delle modifiche. Anthropic, flussi comuni di Claude Code.

Il profilo dovrebbe registrare:

• numero di righe e colonne lette;

• intestazioni esatte e possibili duplicati;

• codifica e delimitatore rilevati;

• valori vuoti per campo;

• formati osservati per date e numeri;

• valori fuori dall'elenco ammesso;

• righe non leggibili;

• chiavi duplicate, senza ancora unirle;

• esempi mascherati o sintetici per ogni anomalia.

Non chiedere di stampare dati personali nel report. Conta e classifica le anomalie, poi usa identificatori tecnici o righe sintetiche per discutere le regole. Se un esempio reale è indispensabile, applica le regole privacy dell'organizzazione e limita il perimetro.

Il profilo deve finire con domande precise. “Ci sono date ambigue nelle colonne created_at e closed_at: vanno scartate o interpretate secondo una provenienza dichiarata?” è una domanda utile. “Il file è sporco, procedo?” non lo è.

Trasforma solo regole approvate

Dopo il profilo, scrivi un registro di trasformazione. Ogni regola deve avere un identificatore, una condizione, un'azione e almeno un caso di prova.

R01
Condizione: amount_eur contiene spazi esterni e simbolo €.
Azione: rimuovi spazi e simbolo, conserva due decimali.
Caso valido: " € 12,50 " -> "12.50"
Caso di arresto: "circa 12" -> scarto AMOUNT_NOT_NUMERIC

Evita regole basate sull'intuizione del singolo file se devono diventare una procedura ricorrente. Se oggi attivo e in corso sembrano sinonimi, verifica che il sistema di destinazione li consideri davvero equivalenti. Una normalizzazione può alterare stati operativi e report.

Prima dell'intero export, esegui le regole su fixture sintetiche che comprendano casi normali, limiti ed errori. Puoi usare un dataset di test per il workflow AI per rendere ripetibile questa prova senza esporre dati reali.

Separa output, scarti e report

La trasformazione deve produrre almeno tre file:

output/
  clienti-puliti.csv
  clienti-scarti.csv
  report-trasformazione.json

Il file pulito contiene soltanto righe che rispettano lo schema. Il file degli scarti conserva la riga o un riferimento sicuro, il codice dell'errore e il campo coinvolto. Il report registra conteggi, regole applicate, versione dello script e hash dell'input quando la procedura lo prevede.

Non usare un unico contenitore “errori” per casi diversi. Distingui almeno formato non valido, campo obbligatorio assente, valore non ammesso, chiave duplicata e riga illeggibile. Codici stabili rendono più semplice decidere se correggere la fonte, aggiornare una regola o chiedere un intervento umano.

Gli scarti non devono essere reimportati automaticamente dopo una correzione manuale. Conserva il legame con l'esecuzione di origine e ripeti la pipeline sull'input previsto, così la procedura resta riproducibile.

Verifica la quadratura

La prima uguaglianza da controllare è semplice:

righe ingresso = righe pulite + righe scartate

Se esistono righe escluse prima della lettura, duplicati consolidati o intestazioni multiple, devono comparire come categorie separate. Non correggere la formula finché torna il numero. Correggi la classificazione finché ogni riga ha una destinazione esplicita.

Controlla poi i totali pertinenti. Per importi, confronta somma in ingresso leggibile, somma in uscita e importi negli scarti. Per stati, confronta le distribuzioni prima e dopo la mappatura. Per date, verifica estremi e valori fuori periodo. Una quadratura numerica può ancora nascondere un errore semantico, quindi aggiungi casi di controllo scelti per rischio.

Preleva un campione da tre gruppi: righe trasformate, righe rimaste invariate e scarti. Ricostruisci per ciascuna il percorso dall'originale alla regola applicata. La checklist di verifica degli output AI può diventare la base del verbale di approvazione.

Un prompt operativo per Claude Code

Puoi partire da una richiesta di questo tipo:

Lavora nella cartella csv-cleanup. Tratta input/ come sola lettura.
Non modificare o sostituire l'export originale.

Fase 1: profila il CSV e restituisci intestazioni, formati, vuoti,
duplicati e anomalie. Non trasformare ancora i dati. Proponi uno
schema e fammi le domande che cambiano il significato dei valori.

Dopo la mia approvazione:
1. implementa regole identificate e testate su fixture sintetiche;
2. crea file pulito, file scarti e report;
3. verifica la quadratura delle righe e i totali concordati;
4. mostra comandi eseguiti, test, differenze e limiti rimasti.

Non importare dati, non collegarti a sistemi esterni e non inviare file.

Completa il prompt con i comandi ammessi, l'ambiente e la prova richiesta. Claude Code può usare gli strumenti presenti, ma non dovrebbe installare dipendenze, cambiare configurazioni o accedere alla rete senza un'autorizzazione coerente con il progetto.

Rendi la procedura ripetibile

Una pulizia occasionale può diventare un processo se salvi schema, regole, fixture e report. Alla nuova esportazione, la prima fase confronta la struttura con quella attesa. Se appare una colonna nuova o scompare un campo obbligatorio, l'esecuzione si ferma prima di produrre un file plausibile ma incompatibile.

Versiona le regole insieme ai test. Nel report indica quale versione ha prodotto l'output. Se una mappatura cambia, conserva la motivazione e ripeti le prove che dipendono da quel campo.

Nomina anche la persona responsabile del significato dei dati. Claude Code può implementare la trasformazione; non può stabilire da solo se uno stato commerciale equivale a un altro o se una riga incompleta debba essere esclusa da una decisione.

Quando fermarti

Fermati se la codifica non permette di leggere il file senza perdita, se lo schema varia all'interno dello stesso export, se una regola richiede informazioni non presenti o se il trattamento dei dati non è autorizzato. Anche una percentuale alta di eccezioni segnala che stai cercando di riparare a valle un problema della fonte.

Non usare la procedura per mascherare una modifica del gestionale. Se il significato di una colonna è cambiato, serve una nuova versione del contratto e probabilmente un confronto con chi produce l'export.

Il risultato corretto può essere un report bloccato con domande precise. È preferibile a un file completo nel quale gli errori sono diventati valori apparentemente normali.

Trasforma un export ricorrente in una procedura

Scegli un CSV che oggi correggi periodicamente e ricostruisci le azioni manuali come regole esplicite. Parti dal profilo, approva lo schema, prova casi sintetici e chiedi sempre output, scarti e quadratura.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi portare un file o un processo reale e progettare una trasformazione controllata, dalla cartella di lavoro alle prove. L'obiettivo non è automatizzare ogni eccezione, ma sapere quali righe puoi trasformare e quali devono restare visibili.