Dal bisogno al processo

Un processo nuovo non si disegna in un'interfaccia: si scrive con Claude Code nel repo cliente, noeva-etl-<slug>, e arriva nell'app passando da una Pull Request e da un deploy. Il repo cliente contiene già ciò che serve perché Claude lo faccia secondo le regole del core: il kit dell'agente, con le skill che generano lo scheletro, una skill che insegna come si costruisce un grafo e i subagent che lo materializzano e lo rivedono. Sono tutti nel catalogo degli strumenti. Le cartelle del repo, il catalogo e i comandi etl sono nella guida allo sviluppo.

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 repo cliente e al pacchetto del core, Node ≥ 26, 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 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, la prima versione del processo con lo snapshot del suo piano, il collegamento ai connettori reali, la voce nel catalogo di etl.config.ts, 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. Prima della Pull Request fai girare i controlli della CI del repo: pnpm exec etl ci, la stessa sequenza 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 deploy il server ETL va riavviato, perché l'elenco dei grafi si costruisce all'avvio; il pulsante Esegui si abilita da solo quando il worker riparte e dichiara al server Noeva i processi che sa eseguire. 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 core 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.