Come Strutturare un Progetto Claude Code in VSCode: Guida Pratica

Aggiornato: aprile 2026 — Gaetano Castaldo, consulente AI e digital transformation, certificato Salesforce Architect.

La struttura di un progetto Claude Code in VSCode determina quanto Claude capisce il tuo progetto, quanto i comportamenti sono riproducibili tra sessioni e quanto velocemente un nuovo developer (o una nuova sessione AI) può operare senza spiegazioni ripetute.

Non è una questione estetica. Un progetto strutturato male significa istruzioni riscritte ogni volta, skill che non vengono caricate, hook che non scattano. Un progetto strutturato bene funziona da solo: apri VSCode, lanci Claude Code, e l'assistente sa già dove si trova.

In rete circolano infografiche sulla struttura dei progetti Claude Code. Alcune sono utili come punto di partenza, ma contengono errori nei nomi di file e cartelle (.cl Claude/ invece di .claude/, mcp.jason invece di .mcp.json, settings,json con la virgola) che portano a configurazioni rotte silenziosamente. In questa guida trovi la struttura corretta, con spiegazioni su cosa serve davvero e cosa è opzionale.

Qual è la Struttura Corretta di un Progetto Claude Code

La cartella principale è .claude/ nella root del progetto. Tutto quello che riguarda la configurazione di Claude per quel progetto vive lì.

Nota importante: il nome corretto della cartella è .claude/ (tutto minuscolo, con il punto). Nelle infografiche che circolano online trovi spesso .cl Claude/ o varianti con spazi: sono errori, Claude Code non le riconosce.

A Cosa Serve Ogni File e Cartella

CLAUDE.md: perché è il File Più Importante del Progetto

È il file più importante. Claude lo legge automaticamente all'inizio di ogni sessione, senza che tu lo richieda. Contiene tutto ciò che un developer (o una nuova sessione AI) deve sapere prima di toccare il codice: stack tecnico, convenzioni, file critici, workflow di deploy, regole di naming.

Il valore reale è nella condivisione: CLAUDE.md va su git. Ogni developer che clona il progetto ha la stessa base di contesto. Nei progetti Castaldo Solutions, un CLAUDE.md ben strutturato dimezza i tempi di onboarding: zero sessioni di allineamento verbale, zero istruzioni riscritte tra sessioni diverse.

Regola pratica: se ti ritrovi a spiegare la stessa cosa a Claude due volte in sessioni diverse, quella cosa va nel CLAUDE.md.

.mcp.json: Connessione ai Sistemi Esterni

Questo file (non mcp.jason come si vede in alcune infografiche) configura i server MCP attivi sul progetto. Definisce quali strumenti esterni Claude può usare: database, API aziendali, CRM, GitHub, Jira, Slack.

{
  "mcpServers": {
    "vtenext": {
      "type": "stdio",
      "command": "node",
      "args": ["/percorso/mcp-vtenext/index.js"]
    }
  }
}

Va su git se i server MCP sono condivisi con il team. Se contiene credenziali o path locali, va in .gitignore.

settings.json e settings.local.json

settings.json definisce permessi, tool access e hooks per il progetto. Va su git: è la configurazione condivisa del team.

settings.local.json è il suo override locale. Serve per impostazioni personali che non devono finire nel repository: path specifici della macchina, permessi aggiuntivi per uso personale, configurazioni di test. Va sempre in .gitignore.

Questa distinzione è critica: confondere i due file porta a configurazioni che funzionano solo sulla macchina di chi le ha scritte.

rules/: come Mantenere il Contesto Leggero con Regole Modulari

Le regole sono file markdown che Claude carica quando sono rilevanti per il task corrente. A differenza del CLAUDE.md che viene caricato sempre, le rules vengono caricate solo quando il contesto le richiede: se stai scrivendo test, Claude carica testing.md; se stai definendo endpoint API, carica api-conventions.md.

Questo è il meccanismo che mantiene il contesto leggero: invece di caricare tutto all'inizio di ogni sessione, le regole entrano nel contesto solo quando servono. Una singola regola ben scritta pesa 200-500 token contro i 2.000-5.000 di un CLAUDE.md che cerca di coprire tutto.

commands/: come Creare Slash Command Personalizzati per il Progetto

I file in commands/ diventano slash command invocabili con /project:nome-comando all'interno di Claude Code. Sono workflow codificati per quel progetto specifico: /project:review per la code review, /project:fix-issue per il pattern standard di fix dei bug.

La differenza rispetto alle skill globali: i comandi di progetto vivono nel repository e sono disponibili solo in quel contesto. Le skill globali (in ~/.claude/skills/) sono disponibili ovunque.

skills/: Comportamenti Specializzati On-Demand

Le skill di progetto sono istruzioni strutturate per task specifici, caricate solo quando vengono invocate. Ogni skill è una cartella con un file skill.md al centro.

skills/
└── deploy/
    ├── skill.md          ← istruzioni principali
    └── deploy-config.md  ← configurazione specifica

Per una guida completa su come costruire skill efficaci e le best practices per affilarle nel tempo, leggi Skill Claude Code 2026: Guida Completa e Best Practices.

agents/: quando Usare Subagenti con Ruoli Separati

Gli agenti sono configurazioni per subagenti con un ruolo definito, strumenti specifici e preferenze di modello. A differenza di una skill che esegue un task, un agente opera con una finestra di contesto isolata e può avere accesso a tool diversi dall'agente principale.

Esempi tipici: un agente per la code review che ha accesso solo al diff, un security auditor che non può modificare file.

hooks/: come Automatizzare Validazioni e Bloccare Operazioni Non Sicure

Gli hooks sono script che si eseguono in risposta a eventi di Claude Code: prima o dopo l'uso di un tool, prima di un commit, dopo un'operazione di scrittura. Permettono di automatizzare validazioni, linting, formattazione e bloccare operazioni non sicure prima che avvengano.

Un hook tipico: bloccare la scrittura diretta su file generati (CSS compilato da Tailwind, build artifacts) e ricordare di lanciare il build prima del deploy.

Cosa Mettere su Git e Cosa No

Come Iniziare se Parti da Zero

Non serve creare tutto in una volta. L'ordine che consiglio:

1. CLAUDE.md per primo, sempre. Anche due righe: stack tecnico e file critici.
2. settings.json appena hai un hook da configurare o un permesso da bloccare.
3. rules/ quando ti accorgi che stai riscrivendo le stesse istruzioni su coding style o testing.
4. skills/ per i workflow ripetitivi che vuoi codificare.
5. agents/ e hooks/ quando il progetto è maturo e hai pattern stabili da automatizzare.

Un CLAUDE.md ben scritto da solo vale più di una struttura completa ma superficiale.

Per vedere come queste strutture vengono applicate su un progetto reale, leggi le 8 skill dal mio workflow quotidiano.

Domande Frequenti sulla Struttura di un Progetto Claude Code

Qual è la differenza tra CLAUDE.md e le rules/ in Claude Code? CLAUDE.md viene caricato ad ogni sessione automaticamente: contiene il contesto permanente del progetto. Le rules/ sono file modulari caricati solo quando il contesto lo richiede: code style quando scrivi codice, testing quando scrivi test. CLAUDE.md è per le regole sempre valide, rules/ è per le regole specifiche per situazione.

Il file .mcp.json va messo su git? Dipende dal contenuto. Se definisce server MCP condivisi con il team (tipo un server VTENext o un database aziendale accessibile a tutti), va su git. Se contiene path assoluti locali o credenziali, va in .gitignore. Regola pratica: usa variabili d'ambiente per le credenziali e metti .mcp.json su git solo con riferimenti relativi o senza segreti.

Qual è la differenza tra commands/ e skills/ in Claude Code? I comandi in commands/ sono slash command di progetto invocabili con /project:nome e tipicamente eseguono workflow con shell execution. Le skill in skills/ sono istruzioni strutturate che configurano comportamenti e formati specifici. In pratica: un comando fa qualcosa (lancia test, crea un file), una skill dice a Claude come farlo (con quale struttura, quale tono, quali convenzioni).

settings.local.json va su git? No, mai. settings.local.json contiene override personali specifici per la tua macchina: path assoluti, permessi extra per il tuo uso personale, configurazioni di debug. Va aggiunto a .gitignore. settings.json invece va su git: è la configurazione condivisa del team.

Da dove si inizia a strutturare un progetto Claude Code da zero? Dal CLAUDE.md. Anche due righe: stack tecnico e file critici del progetto. Il resto della struttura si aggiunge quando serve: settings.json appena hai un hook, rules/ quando ripeti le stesse istruzioni, skills/ quando codifichi il primo workflow ripetitivo. Non serve creare tutto subito.

Vuoi impostare questa struttura sul tuo progetto con il supporto di un consulente?

Prenota un pre-assessment gratuito