Claude Code non conosce il tuo progetto. Ma ogni volta che apre una sessione, legge automaticamente CLAUDE.md. Un file ben scritto vale decine di minuti di rispiegazioni — e cambia la qualità di ogni output.

---

Perché CLAUDE.md è critico

Ogni sessione di Claude Code parte da zero. Il modello non ricorda la sessione di ieri, non conosce le tue convenzioni, non sa che hai scelto di usare Pest invece di PHPUnit, non sa che le migration non si toccano mai.

Senza CLAUDE.md, Claude fa ipotesi. Alcune buone, alcune no. Ogni output che non rispetta le tue convenzioni richiede correzione, e ogni correzione richiede spiegazione. Il costo si accumula.

CLAUDE.md risolve questo una volta sola.

Come funziona:

• Claude Code scansiona la directory di lavoro e tutte le parent directories
• Carica automaticamente ogni CLAUDE.md trovato (root → cartella corrente)
• Carica anche ~/.claude/CLAUDE.md (preferenze globali utente)
• Tutto questo prima di processare il primo prompt

Think of it as a README for the AI, not for humans.

---

Struttura raccomandata per progetti web/app

Questo è il template base che uso per progetti Laravel/Vue o simili. Adattalo al tuo stack.

# Progetto: [nome]
> Aggiornato: YYYY-MM-DD | Maintainer: [nome]

## Stack tecnico
- **Backend:** Laravel 10, PHP 8.2
- **Frontend:** Vue 3 + Inertia.js + TypeScript
- **DB:** MySQL 8 + Redis (cache + jobs)
- **Test:** Pest (unit/feature), Cypress (E2E)
- **CI/CD:** GitHub Actions → Laravel Forge

## Architettura — cartelle chiave
| Cartella | Contenuto |
|----------|-----------|
| `app/Http/Controllers/` | Resource controllers REST |
| `app/Models/` | Eloquent models + scopes |
| `app/Services/` | Business logic (no fat controller) |
| `app/Jobs/` | Background queue jobs |
| `resources/js/Pages/` | Vue components (una per route Inertia) |
| `resources/js/Components/` | Componenti riutilizzabili (no logica di business) |

## Convenzioni obbligatorie

### PHP / Laravel
- Naming: `snake_case` per variabili/metodi PHP, `PascalCase` per classi
- Controller: **sempre** Resource Controller, mai metodi custom fuori dalle 7 azioni standard
- Queries: **sempre Eloquent**, mai raw SQL (eccetto report complessi: documentare il perché)
- Autorizzazione: **sempre Gate/Policy**, mai logica auth nei controller
- Evita: fat controllers, logica nei migration, `DB::statement()` non documentato

### Vue / TypeScript
- Componenti: `PascalCase.vue`
- Props: sempre tipizzate con TypeScript interface
- No `any` type salvo casi eccezionali documentati
- State management: Pinia per stato globale, `ref`/`computed` per stato locale

### Git
- Branch naming: `feature/`, `fix/`, `refactor/`, `chore/`
- Commit format: `[tipo]: descrizione breve` (es. `feat: add user export endpoint`)
- PR: sempre con descrizione + test + checklist

## Comandi comuni

bash

Development

composer install && npm install php artisan key:generate php artisan migrate --seed npm run dev

Testing

php artisan test # Pest suite completa php artisan test --filter=UserTest # Test specifico npx cypress run # E2E

Production utils

php artisan queue:work --queue=high,default php artisan horizon # Laravel Horizon (jobs monitoring)

## Cosa NON fare mai
- ❌ Non modificare migration già in produzione (crea nuova migration)
- ❌ Non committare `.env` o chiavi/secret
- ❌ Non usare `sleep()` o `usleep()` nel codice applicativo
- ❌ Non hardcodare URL, usare `route()` o `config()`
- ❌ Non risolvere PR con force push su branch condivisi

## Contesto progetto
[Descrizione breve del progetto, target utenti, stakeholder principali]
[Decisioni architetturali prese e perché]
[Problemi noti / technical debt documentato]

---

CLAUDE.md per cartelle (folder-level)

Per repository grandi o monorepo, ha senso avere un CLAUDE.md per modulo. Claude Code li carica tutti, dal root alla cartella corrente.

Esempio: app/Services/Billing/CLAUDE.md

# Modulo Billing

## Responsabilità
Gestisce tutto il ciclo di vita degli abbonamenti: checkout Stripe, webhook, 
upgrade/downgrade, cancellazioni, rimborsi.

## Flusso principale
1. `BillingController` riceve la richiesta HTTP
2. `SubscriptionService` contiene la business logic
3. `StripeWebhookService` gestisce gli eventi asincroni
4. `BillingRepository` isola l'accesso al DB

## Regole critiche per questo modulo
- I webhook Stripe devono sempre verificare la firma prima di processare
- Ogni operazione finanziaria logga in `billing_events` con user_id + amount + timestamp
- Non modificare stati subscription senza passare da `SubscriptionService`
- I test per questo modulo usano Stripe mock (non sandbox reale)

## File da non toccare senza review
- `StripeWebhookService.php` (contiene logica idempotenza)
- `billing_plans.php` config (cambia solo con migration + deploy coordinato)

Regola di priorità: CLAUDE.md più vicino alla directory corrente sovrascrive le sezioni del root. Se il root dice "no raw SQL" e il modulo Billing dice "query analytics in raw SQL con commento", il modulo vince per quella directory.

---

~/.claude/CLAUDE.md — le preferenze globali

Questo file vale per TUTTI i progetti del tuo utente. Utile per preferenze personali che non dipendono dal progetto specifico.

# Preferenze personali Claude Code

## Come rispondo alle revisioni
- Quando finisco un task, chiedimi sempre "vuoi che faccia anche i test?"
- Dopo ogni modifica multi-file, mostrami una lista di cosa hai cambiato
- Non aggiungere import non necessari senza segnalarmelo

## Formato commit
Usa sempre questo formato:

[tipo]: descrizione breve (#issue)

Corpo opzionale: perché questa scelta, non cosa hai fatto (già si vede dal diff)

## Preferenze review
- Quando mi mostri codice, includi sempre il path del file
- Per i diff, mostra prima cosa si romperebbe, poi la soluzione
- Se hai dubbi su quale approccio scegliere, presenta le opzioni con pro/con prima di procedere

---

La cartella .claude/ — sistema avanzato

Per i workflow più strutturati, Claude Code ha un sistema di estensione basato sulla cartella .claude/ alla root del progetto.

.claude/commands/ — comandi personalizzati

File Markdown che diventano comandi slash nella CLI. Esempio: .claude/commands/audit-security.md

# Security Audit

Esegui un security audit completo di questo modulo.

Controlla:
1. **Input validation**: tutti gli input utente vengono sanitizzati?
2. **SQL injection**: query parametrizzate ovunque?
3. **XSS**: output escape corretto in tutti i template?
4. **Auth bypass**: ogni endpoint verifica le permission?
5. **Secrets**: nessuna chiave hardcodata?

Per ogni problema trovato, mostra: file + riga + severity (critical/high/medium/low) + fix suggerito.

Uso: /audit-security nella CLI.

.claude/rules/ — regole di sicurezza

Definiscono cosa Claude Code può e non può fare senza approvazione esplicita.

# Security Rules

## Mai eseguire senza conferma esplicita
- Comandi che eliminano dati (DROP TABLE, DELETE senza WHERE, rm -rf)
- Push su branch main/master
- Deploy in produzione
- Modifiche ai file .env

## Sempre richiedere review umana
- Modifiche alla logica di autenticazione
- Nuovi endpoint pubblici senza autenticazione
- Modifiche agli hook git

.claude/hooks/ — automatismi pre/post task

Script che girano automaticamente prima o dopo certi task.

Esempio: dopo ogni modifica PHP, esegui automaticamente i test correlati.

#!/bin/bash
# .claude/hooks/post-edit-php.sh
# Eseguito dopo ogni modifica a file .php

FILES_MODIFIED="$1"
php artisan test --filter=$(basename "$FILES_MODIFIED" .php)

.claude/skills/ — workflow riutilizzabili

Skills sono procedure salvate che si attivano su certi trigger o comandi.

Esempio: .claude/skills/bug-report.md

# Skill: Bug Investigation

Quando ricevi una bug report, segui SEMPRE questo processo:

1. **Riproduci prima di correggere**
   - Scrivi un test che fallisce
   - Conferma di aver riprodotto esattamente il comportamento segnalato

2. **Isola la causa**
   - Identifica il file e la funzione esatta
   - Non cercare la soluzione prima di capire la causa

3. **Fix minimale**
   - Cambia il minimo indispensabile
   - Non refactoring contestuale: crea un issue separato

4. **Verifica regressioni**
   - Esegui test suite completa
   - Verifica che il fix non rompa nulla di correlato

5. **Documenta**
   - Commit message: `fix: [descrizione] (closes #issue)`
   - Se era un edge case, aggiungi commento nel codice

---

Il CLAUDE.md che genera CLAUDE.md

Se hai un codebase esistente e non vuoi scrivere CLAUDE.md a mano, usa questo prompt:

Esplora questo repository.
Identifica: stack tecnico, architettura delle cartelle principali, 
pattern di codice ricorrenti, convenzioni di naming visibili nel codice esistente.

Poi genera un CLAUDE.md completo con:
1. Stack e versioni (ricava dal package.json/composer.json)
2. Architettura — mappa delle cartelle con spiegazione del ruolo
3. Convenzioni — inferite dal codice esistente (non inventarle)
4. Comandi — da README esistente + package.json scripts
5. Cose da non fare — solo se emergono pattern critici evidenti

Sii specifico. Non scrivere cose ovvie o generiche.

Risultato: un CLAUDE.md in 3 minuti che poi raffini a mano con le eccezioni e le regole critiche.

---

Quando aggiornare CLAUDE.md

CLAUDE.md va aggiornato quando:

• Si adotta un nuovo pattern architetturale
• Si aggiunge una dipendenza critica
• Si definisce una convenzione nuova ("d'ora in poi usiamo X")
• Si documenta una decisione importante e il perché
• Si trova un errore ripetuto da Claude (aggiungi la regola "NON fare X")

Segnale pratico: se ti trovi a correggere Claude più di 2 volte sullo stesso tipo di errore, è materiale per CLAUDE.md.

---

Prossimi passi

Con CLAUDE.md configurato, il tutorial successivo entra nei 5 pattern di workflow agentici: sequential, operator, split-and-merge, agent teams e headless autonomous. Sono i mattoni per costruire pipeline che lavorano da sole.

---

Vuoi mettere in pratica quello che hai imparato? Scopri il servizio di Sviluppo Web — realizziamo applicazioni web su misura con AI integrata: architettura, sviluppo e deploy gestiti da professionisti che usano Claude Code ogni giorno. Prossimo tutorial →Sequential, Operator, Split-merge, Agent Teams, Headless: quando usarli 14 min

---

Fonti: Youssef Hosni — "Claude Code: A Practical Guide" (Medium, 2026); henriquesd.medium.com — Claude Code workflow; MindStudio — "Claude Code Agentic Workflow Patterns" (2026); Anthropic — Claude Code documentation.