Claude Code e progettazione di un datawarehouse

Claude Code e progettazione di un datawarehouse

Claude Code e progettazione di un datawarehouse: guida pratica per DBA, ingegneri e AI engineer

Progettare un data warehouse enterprise significa scrivere e mantenere centinaia di modelli SQL, test, documentazione e pipeline. Claude Code, l’agente di coding di Anthropic che lavora nel terminale e dentro il repository, può accelerare gran parte di questo lavoro, a patto di dargli regole, contesto e guardrail. In questa guida usiamo uno stack enterprise molto diffuso (Snowflake, dbt, GitHub Actions) per vedere come impostarlo, quali MCP e skill usare, dove aiuta davvero e dove invece serve la vostra testa.

Indice dei contenuti – Claude Code e progettazione di un datawarehouse

1. Perché Claude Code cambia il lavoro sul data warehouse

2. Lo stack di riferimento: Snowflake, dbt e GitHub

3. Configurazione del workspace e delle regole

4. Struttura consigliata di un progetto DWH con Claude Code

5. Skill, subagent e hook: gli strumenti giusti per ogni compito

6. Definizione dello schema e dei modelli con dbt

7. Integrazione con i database tramite MCP

8. Automazione Git e CI/CD

9. Troubleshooting ed errori di pipeline

10. Vantaggi e svantaggi: tabella di sintesi

11. Best practice per evitare errori

12. Conclusioni e formazione professionale

1. Perché Claude Code cambia il lavoro sul data warehouse

Immaginate un collega junior velocissimo, che legge l’intero repository in pochi secondi, ma che ogni mattina si dimentica tutto. Ogni sessione di Claude Code parte infatti con una finestra di contesto nuova. Il vostro compito è scrivere il “foglio di onboarding” (il file CLAUDE.md), dargli gli attrezzi giusti (MCP, skill) e mettere dei paletti (permessi e hook).

Nel lavoro sul DWH i guadagni maggiori arrivano da attività ripetitive e ben regolate: modelli di staging, file YAML con descrizioni e test, refactoring di query legacy, documentazione, migrazioni tra dialetti SQL. Le decisioni di modellazione (grain delle fact, gestione delle dimensioni storiche, regole di business) restano invece vostre: Claude Code propone, voi validate.

2. Lo stack di riferimento: Snowflake, dbt e GitHub – Claude Code e progettazione di un datawarehouse

Cominciamo la nostra guida Claude Code e progettazione di un datawarehouse. Per gli esempi useremo una combinazione molto comune in ambito enterprise:

  • Snowflake come data warehouse cloud;
  • dbt Core (adapter Snowflake) per trasformazioni, test e documentazione come codice;
  • Airflow (oppure i job di dbt Cloud) per l’orchestrazione;
  • GitHub e GitHub Actions per versionamento e CI/CD;
  • Modellazione dimensionale Kimball (star schema) nei livelli finali.

Un cenno al Data Vault 2.0: se avete molte fonti eterogenee e requisiti forti di storicizzazione e auditabilità, si inserisce a monte come livello raw/business vault, con i data mart dimensionali sopra. Claude Code lavora bene anche qui, perché hub, link e satellite sono strutture molto regolari. In questa guida restiamo su Kimball per semplicità.

Come caso d’uso fittizio useremo MetalPress S.p.A., un’azienda manifatturiera che vuole analizzare produzione, scarti e tempi macchina a partire da ordini di produzione (ERP) e dati di reparto (MES).

3. Configurazione del workspace e delle regole

Il lavoro di configurazione iniziale è quello che rende Claude Code prevedibile. Tre elementi:

CLAUDE.md. È il file di istruzioni caricato a ogni sessione. Può stare a livello di organizzazione (managed policy, gestita da IT/DevOps), di progetto (./CLAUDE.md o ./.claude/CLAUDE.md, condiviso via Git), di utente (~/.claude/CLAUDE.md) e locale (CLAUDE.local.md). Con /init Claude analizza il codice e genera una bozza; con la sintassi @percorso/file potete importare documenti esistenti invece di duplicarli. Tenetelo corto: più è lungo, più occupa contesto.

# DWH Produzione MetalPress (Snowflake + dbt)

## Stack e comandi

- dbt Core, adapter Snowflake, target `dev` (schema personale DEV_<utente>)

- Build di un modello e dei suoi figli: `dbt build --select <modello>+`

- Lint SQL: `sqlfluff lint models/`

## Convenzioni

- Layer: staging (stg_<fonte>__<entità>), intermediate (int_), marts (fct_ / dim_)

- Chiavi surrogate con dbt_utils.generate_surrogate_key

- Ogni modello ha descrizione e test unique/not_null sulla chiave

- Fatti incrementali sempre con unique_key esplicita

## Regole ferree

- MAI eseguire comandi sul target prod. MAI leggere .env o credenziali.

- MAI SELECT * nei marts. MAI modificare i source senza chiedere.

- Prima di dire "fatto": esegui dbt build e riporta l'esito reale.

@docs/naming-conventions.md

Permessi. Le istruzioni nel CLAUDE.md sono richieste, non garanzie. I paletti veri stanno in .claude/settings.json, dove le regole *deny* hanno la precedenza su *ask* e *allow*. Ricordate anche la plan mode (claude –permission-mode plan): Claude analizza e propone, ma non modifica nulla finché non approvate.

Hook. Sono comandi che scattano in automatico negli eventi del ciclo di vita (per esempio dopo ogni modifica a un file). Qui li usiamo per lanciare il linter SQL a ogni scrittura, senza affidarci alla “buona volontà” del modello.

{

  "permissions": {

    "allow": ["Bash(dbt build *)", "Bash(dbt compile *)", "Bash(dbt test *)", "Bash(git diff *)"],

    "deny": ["Bash(git push *)", "Bash(dbt * --target prod*)", "Read(.env*)"]

  },

  "hooks": {

    "PostToolUse": [

      {

        "matcher": "Edit|Write",

        "hooks": [

          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lint-sql.sh" }

        ]

      }

    ]

  }

}

4. Struttura consigliata di un progetto DWH con Claude Code

Proseguiamo a raccontare di Claude Code e progettazione di un datawarehouse. Una buona struttura aiuta anche il modello: cartelle e nomi prevedibili riducono gli errori di posizionamento dei file. La suddivisione in staging, intermediate e marts segue le raccomandazioni di dbt Labs.

dwh-manifattura/

├── CLAUDE.md                     # contesto e regole sempre attive

├── .mcp.json                     # server MCP condivisi col team

├── .claude/

│   ├── settings.json             # permessi e hook

│   ├── rules/sql-style.md        # regole modulari

│   ├── skills/nuovo-modello-dbt/SKILL.md

│   ├── agents/dwh-reviewer.md    # subagent di revisione

│   └── hooks/lint-sql.sh

├── .github/workflows/

│   ├── dbt-ci.yml                # Slim CI sulle pull request

│   └── claude-review.yml         # code review automatica

├── dbt_project.yml

├── packages.yml

├── models/

│   ├── staging/{erp,mes}/        # stg_<fonte>__<entità>

│   ├── intermediate/production/  # int_*

│   └── marts/production/         # fct_*, dim_*

├── snapshots/                    # SCD tipo 2

├── seeds/ macros/ tests/

├── orchestration/dags/           # DAG Airflow

└── docs/                         # naming, ADR, glossario

5. Skill, subagent e hook: gli strumenti giusti per ogni compito

Claude Code offre più meccanismi di estensione e ognuno risolve un problema diverso. Una regola pratica, in linea con la documentazione ufficiale:

  • CLAUDE.md: contesto sempre attivo (convenzioni, comandi, divieti);
  • Skill: conoscenza e flussi di lavoro caricati solo quando servono;
  • MCP: connessioni a sistemi esterni (database, metadati, documentazione);
  • Subagent: lavoro isolato in un contesto separato, ideale per le revisioni;
  • Hook: automazione deterministica su eventi.

Una skill è una cartella con un file SKILL.md. Esempio minimo per standardizzare la creazione di nuovi modelli:

---

name: nuovo-modello-dbt

description: Crea un nuovo modello dbt (staging o mart) rispettando le convenzioni del progetto. Usare quando si aggiunge una tabella al DWH.

---

1. Leggi docs/naming-conventions.md e un modello simile già esistente.

2. Crea il file .sql nel layer corretto e il relativo YAML con descrizioni.

3. Aggiungi test unique/not_null sulla chiave e relationships sulle FK.

4. Esegui `dbt build --select <modello>` e riporta l'esito.

Prima di scrivere skill da zero, valutate quelle pubblicate da dbt Labs: la raccolta dbt agent skills copre analytics engineering (modelli, test, debug), Semantic Layer e configurazione del server MCP. Si installa da Claude Code così:

/plugin marketplace add dbt-labs/dbt-agent-skills

/plugin install dbt@dbt-agent-marketplace

6. Definizione dello schema e dei modelli con dbt – Claude Code e progettazione di un datawarehouse

Il flusso consigliato è sempre piano, poi codice. Avviate in plan mode e chiedete una proposta di modellazione, non subito dei file:

Leggi i source in models/staging/erp/_erp__sources.yml.

Proponi, senza scrivere codice, uno star schema per analizzare scarti

e tempi di produzione per macchina e prodotto: grain della fact,

dimensioni, chiavi, necessità di SCD tipo 2. Attendi la mia approvazione.

Dopo l’approvazione, passate all’implementazione a piccoli passi. Il primo livello è lo staging: rinomina, cast e nulla più.

-- models/staging/erp/stg_erp__production_orders.sql

with source as (

    select * from {{ source('erp', 'production_orders') }}

),

renamed as (

    select

        order_id::varchar          as production_order_id,

        machine_id::varchar        as machine_id,

        product_code::varchar      as product_code,

        qty_produced::number(12,2) as quantity_produced,

        qty_scrap::number(12,2)    as quantity_scrap,

        start_ts::timestamp_ntz    as started_at,

        end_ts::timestamp_ntz      as ended_at

    from source

)

select * from renamed

Poi la fact table nel layer marts, con carico incrementale e metriche derivate:

-- models/marts/production/fct_production_orders.sql

{{ config(materialized='incremental', unique_key='production_order_id') }}

select

    o.production_order_id,

    m.machine_key,

    p.product_key,

    o.started_at,

    o.quantity_produced,

    o.quantity_scrap,

    div0(o.quantity_scrap, o.quantity_produced + o.quantity_scrap) as scrap_rate,

    datediff('minute', o.started_at, o.ended_at)                  as duration_minutes

from {{ ref('stg_erp__production_orders') }} o

left join {{ ref('dim_machine') }} m on o.machine_id = m.machine_id

left join {{ ref('dim_product') }} p on o.product_code = p.product_code

{% if is_incremental() %}

where o.started_at > (select max(started_at) from {{ this }})

{% endif %}

E il relativo YAML con descrizioni e test, che Claude Code genera molto bene se gli date un esempio da imitare:

models:

- name: fct_production_orders

    description: "Una riga per ordine di produzione completato."

    columns:

      - name: production_order_id

        data_tests: [unique, not_null]

      - name: machine_key

        data_tests:

          - relationships:

              to: ref('dim_machine')

              field: machine_key

 

Qui il controllo umano è decisivo. Verificate sempre il grain (una riga per ordine, davvero?), la logica dell’incrementale (come gestite ordini che cambiano dopo la chiusura?) e il trattamento delle dimensioni storiche (snapshot SCD tipo 2). Per gli schemi più critici valutate anche i *model contracts* di dbt, che fanno fallire la build se colonne e tipi non rispettano quanto dichiarato.

7. Integrazione con i database tramite MCP

Approfondiamo Claude Code e progettazione di un datawarehouse. Il Model Context Protocol permette a Claude Code di parlare con sistemi esterni. I server si configurano con claude mcp add e hanno tre ambiti: locale, utente e progetto (file .mcp.json nella radice del repo, da versionare). I server di progetto richiedono un’approvazione esplicita al primo utilizzo.

Per un DWH Snowflake con dbt sono due le integrazioni più utili.

dbt MCP server. Dà all’agente contesto sul progetto (modelli, lineage, documentazione) e accesso ai comandi dbt. Funziona con dbt Core, Fusion e dbt Platform.

# aggiunge il server dbt al progetto (variabili d'ambiente nel file .env, fuori da Git)

claude mcp add dbt -s project -- uvx --env-file .env dbt-mcp

# verifica lo stato dei server configurati

claude mcp list

Snowflake-managed MCP server. Gira dentro il vostro account Snowflake, senza infrastruttura da gestire, ed espone tool come Cortex Analyst (su semantic view), Cortex Search ed esecuzione SQL. L’autenticazione è OAuth 2.0; attenzione al fatto che Snowflake non supporta la dynamic client registration, quindi l’integrazione OAuth va preparata in anticipo con il vostro team di sicurezza.

Per il lavoro quotidiano di sviluppo, un ruolo dedicato in sola lettura sull’ambiente di sviluppo è il minimo indispensabile:

CREATE ROLE CLAUDE_DEV_RO;

GRANT USAGE ON WAREHOUSE WH_DEV_XS TO ROLE CLAUDE_DEV_RO;

GRANT USAGE ON DATABASE DWH_DEV TO ROLE CLAUDE_DEV_RO;

GRANT USAGE ON ALL SCHEMAS IN DATABASE DWH_DEV TO ROLE CLAUDE_DEV_RO;

GRANT SELECT ON ALL TABLES IN DATABASE DWH_DEV TO ROLE CLAUDE_DEV_RO;

Nota sicurezza. Principio del minimo privilegio: ruolo read-only, mai accesso alla produzione, nessuna credenziale nel repository e solo server MCP verificati (Snowflake stessa raccomanda di controllare quelli di terze parti).

8. Automazione Git e CI/CD

Claude Code lavora bene con Git: crea branch, scrive messaggi di commit coerenti, prepara la pull request. Una regola che consigliamo: lasciate che prepari tutto, ma il push resta a voi (o alla pipeline), come nel deny mostrato prima.

Sul fronte CI, la tecnica chiave di dbt è la Slim CI: il selettore state:modified+ costruisce solo i modelli cambiati e i loro dipendenti, mentre –defer legge gli upstream non ricostruiti dalla produzione. Meno costi Snowflake e feedback più rapido.

# .github/workflows/dbt-ci.yml

name: dbt-ci

on:

  pull_request:

    paths: ["models/**", "macros/**", "dbt_project.yml"]

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5

        with: { python-version: "3.12" }

      - run: pip install dbt-snowflake && dbt deps

      # prima di questo step: scaricare il manifest.json di produzione in ./prod-state

      - run: dbt build --select state:modified+ --defer --state ./prod-state --target ci

        env:

          SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}

          SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_USER }}

          SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_PASSWORD }}

Potete poi affiancare una revisione automatica con l’action ufficiale anthropics/claude-code-action, che esegue Claude Code sul runner GitHub e rispetta il vostro CLAUDE.md. Il modo più rapido per installarla è lanciare /install-github-app da Claude Code.

# .github/workflows/claude-review.yml

name: claude-review

on:

  pull_request:

    types: [opened, synchronize]

jobs:

  review:

    runs-on: ubuntu-latest

    permissions: { contents: read, pull-requests: write, id-token: write }

    steps:

      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1

        with:

          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

          prompt: >

            Rivedi questa PR secondo CLAUDE.md. Controlla grain delle fact,

            test mancanti, SELECT * nei marts e impatto sui modelli a valle.

Tenete presente i costi: minuti di GitHub Actions più token API. Limitate i trigger con filtri sui percorsi, come nell’esempio.

9. Troubleshooting ed errori di pipeline

Il ciclo di debug con Claude Code è semplice ed efficace: riproduci, fornisci l’errore reale, chiedi la causa prima della correzione. Gli artefatti di dbt sono ottimi alleati: il SQL compilato in target/compiled, l’esito in target/run_results.json e il log in logs/dbt.log.

Il comando `dbt build --select fct_production_orders` fallisce.

Esegui il comando, leggi l'errore completo e il SQL compilato in target/compiled.

Spiegami la causa probabile PRIMA di modificare qualsiasi file.

Poi proponi la correzione minima e rilancia il build.

Gli errori che incontrerete più spesso:

  • Compilation Error su ref o source: nome sbagliato o modello nel layer errato. Claude lo risolve di solito in un passaggio.
  • Oggetto inesistente o non autorizzato (Snowflake): quasi sempre un problema di grant o di ruolo, non di SQL. Controllate il ruolo del target prima di far “riscrivere” la query.
  • Test falliti (unique, relationships): indagate sui dati sorgente prima di allentare il test. Un test che fallisce spesso segnala un grain sbagliato.
  • Incrementali che divergono: dopo una modifica di schema serve –full-refresh oppure una strategia on_schema_change. Decidete voi quando è sicuro.
  • Task Airflow in errore: passate a Claude log e DAG insieme, e chiedete di distinguere errori di orchestrazione da errori di trasformazione.

Un trucco utile: quando una correzione non funziona al secondo tentativo, aprite una sessione pulita (/clear) con un riepilogo del problema. Il contesto accumulato di tentativi falliti spesso peggiora le risposte.

10. Vantaggi e svantaggi: tabella di sintesi

AspettoVantaggiSvantaggi
VelocitàBoilerplate SQL, YAML e documentazione in minutiIl tempo di revisione non sparisce
CoerenzaApplica convenzioni e naming se ben istruitoIgnora regole non scritte o ambigue
ContestoLegge l’intero repo e il lineage via MCPOgni sessione parte da zero senza CLAUDE.md curato
QualitàGenera test e descrizioni sistematicamentePuò produrre SQL plausibile ma semanticamente errato
SicurezzaPermessi, hook e ruoli read-only a più livelliUn MCP o un permesso troppo ampi aumentano il rischio
CostiMeno ore su attività ripetitiveConsumo di token e minuti CI da monitorare

11. Best practice per evitare errori

  • Pianificate prima di scrivere. Usate la plan mode per le decisioni di modellazione e approvate il piano prima del codice.
  • Lavorate a piccoli passi. Un modello alla volta, non “costruiscimi tutto il DWH”.
  • Mettete le regole nel posto giusto. Convenzioni in CLAUDE.md, guardrail in settings e hook, procedure ripetibili nelle skill.
  • Fate verificare il lavoro. Imponete dbt build e test prima di dichiarare un task concluso: Claude deve mostrare l’esito reale.
  • Mai produzione. Ambiente di sviluppo isolato, ruoli read-only, deny esplicito sui target prod.
  • Segreti fuori dal repo. .env ignorato da Git e bloccato in lettura; niente credenziali nel .mcp.json.
  • Revisione umana obbligatoria. Ogni PR passa da una persona: grain, join, logica incrementale e storicizzazione sono responsabilità vostra.
  • Aggiornate il CLAUDE.md. Quando correggete due volte lo stesso errore, scrivete la regola.
  • Contesto sotto controllo. File di istruzioni brevi, /clear tra task diversi, subagent per le revisioni.
  • Verificate gli MCP. Usate server ufficiali o interni e testate ogni nuova integrazione su un ambiente di prova.
  • Monitorate i costi. Filtri sui workflow CI, Slim CI e limiti sull’uso dell’action.

12. Conclusioni e formazione professionale

Claude Code non è più uno strumento per soli sviluppatori. Lo usano DBA, data engineer, analytics engineer, architetti, AI engineer e perfino i profili di sistemistica e DevOps, ciascuno per il proprio pezzo di pipeline. Nel data warehouse il risultato si vede subito: meno tempo su attività ripetitive e più tempo su modellazione, qualità e governance.

Per le aziende non si tratta più di decidere *se* adottarlo, ma di farlo bene e in fretta: chi non aggiorna le competenze dei propri team IT rischia di accumulare ritardo su tempi di delivery, costi e qualità rispetto a chi lo ha già integrato nei processi. Servono metodo, regole condivise e persone formate.

Per questo vi consigliamo il Corso Claude Code per sviluppatori di Innovaformazione.

Il corso viene attivato su richiesta per le aziende, in modalità online in classe virtuale, con calendario da concordare. Per finanziare la formazione dei dipendenti sull’AI è possibile utilizzare una serie di voucher e fondi interprofessionali. Potete contattarci per approfondimenti.

Contatti

Richiedete un preventivo e informazioni: info@innovaformazione.net, tel. 3471012275.

Dario Carrassi, Innovaformazione

(fonte) (fonte) (fonte) (fonte)

Ti potrebbe interessare

Articoli correlati