Dal bisogno al processo

Un processo nuovo non si disegna in un'interfaccia: si scrive nel repository noeva-etl con Claude Code, e arriva nell'app passando da una Pull Request. Il repository contiene già ciò che serve perché Claude lo faccia secondo le regole del progetto: comandi che generano lo scheletro, una skill che insegna come si costruisce un grafo, subagent che lo materializzano e lo rivedono. Sono tutti nel catalogo degli strumenti.

La parte che nessun agente può inventare è il dominio: da dove leggere, cosa trasformare, dove scrivere, cosa fare degli errori. Se manca, l'agente si ferma e la chiede invece di indovinarla.

Prima di iniziare

Servono accesso al repository, Node ≥ 20, pnpm 9 e Claude Code. Ogni attività vive in un worktree suo, con un branch staccato da dev: così puoi portare avanti più processi in parallelo senza che si pestino i piedi.

git fetch origin
git worktree add --no-track -b feat/fatture-clienti-daily .claude/worktrees/fatture-clienti-daily origin/dev
cd .claude/worktrees/fatture-clienti-daily
pnpm install
claude

Il file .env con le credenziali serve solo se il processo va provato contro sistemi reali. I dettagli e le insidie del worktree sono nel git workflow.

I sei passi

1. Descrivi il processo. Scrivi a Claude cosa deve fare il processo, con le decisioni di dominio già prese. Il compositore del prompt ti guida campo per campo e ti dice cosa manca.

2. Lascia fare lo scaffold. /new-pipeline <nome> genera tutto ciò che un processo richiede: i contratti dati, il grafo, il collegamento ai connettori reali, la registrazione nell'elenco dei processi, i test e la scheda di documentazione. Se la forma del processo è già decisa nei dettagli, Claude può affidarla al subagent graph-builder.

3. Fai passare i test. Un processo è finito quando i test dimostrano che i record validi vengono caricati, quelli invalidi finiscono nello scarto, i contatori tornano e rieseguirlo non duplica dati. pnpm run check fa girare lo stesso controllo della CI.

4. Fai rivedere il lavoro. /etl-review controlla la correttezza del dato; i subagent graph-auditor e schema-contract-auditor guardano struttura del grafo e contratti. A lavoro finito, /doc-sync verifica che la documentazione dica ciò che il codice fa.

5. Apri la Pull Request verso dev. Codice, test e documentazione viaggiano insieme. La promozione verso staging e main passa sempre da altre Pull Request.

6. Porta il processo nell'app. Dopo il rilascio il server ETL va riavviato, perché l'elenco dei grafi si costruisce all'avvio; e per il pulsante Esegui il nome del processo va aggiunto all'elenco dei processi ammessi nel server Noeva. Vedi L'app desktop.

Cosa ti chiederà l'agente

Sono le decisioni che fanno la differenza fra un processo corretto e uno che sembra funzionare:

Decisione	Perché conta
Da dove leggere	quale connettore, quale istanza, quali righe o file: definisce la sorgente e il suo filtro
Cosa trasformare	le regole di business, una per una: diventano nodi distinti, visibili nel grafo
Dove scrivere	destinazione e formato
Su quale chiave rendere idempotente	senza chiave naturale, rieseguire il processo duplica i dati
Cosa fare dei record invalidi	scarto e run che prosegue, oppure run che si ferma: dipende da cosa significa il dato

Il compositore del prompt le raccoglie tutte e produce il testo da incollare.

Cosa non chiedere

Alcune cose il progetto non le accetta, e l'agente lo sa: una query dentro una trasformazione (per quello c'è il nodo lookup), un record scartato senza lasciare traccia, una scrittura che duplica i dati a ogni riesecuzione, una credenziale nel codice. L'elenco completo è nella guida allo sviluppo.