Creare file CLAUDE.md efficaci

Sviluppo software con Claude Code

Dani Zysman

AI Curriculum Manager @ DataCamp

Best practice per CLAUDE.md

Parti da /init, poi itera
- Aggiungi contesto quando Claude sbaglia
- Includi cambi di convenzione
Obiettivo: un documento vivo che cresce col progetto

Il progetto finora

music-analytics-api/
  app.py           # Punto d'ingresso dell'applicazione
  routes.py        # Endpoint API
  models.py        # Modelli Artist/Album
  analytics.py     # Funzioni statistiche
  middleware.py    # Logging delle richieste
  config.py        # Impostazioni di sessione
  CLAUDE.md        # <- File di memoria del progetto

Cosa va DENTRO vs. FUORI da CLAUDE.md

recraft: Cosa includere vs cosa lasciare fuori da CLAUDE.md

Regola: se è più lungo di un post‑it, non va dentro.

Iterare su CLAUDE.md

> Add error handling to the /artists endpoint.

Done. I've added error handling to /artists (routes.py:9-19):
- Try-except block wrapping retrieval and serialization
- AttributeError handler if the data store isn't initialized
- General exception handler returning error details with 500 status

return jsonify({'error': f'Failed to retrieve artists: {str(e)}'}), 500

> Don't expose exception details to users, that's a security risk. Log internally 
and return a generic message.  Update CLAUDE.md.

Updated /artists to log errors internally and return a 
generic 500 message. CLAUDE.md updated with the convention: 
never expose exception details in responses.

Buono vs. Gonfio in CLAUDE.md

Gonfio (200+ righe)

# Inventory API
Questa è una Inventory Management 
API costruita con Flask...

## Codice sorgente completo
### routes.py
from flask import jsonify...
[intero file incollato]

### models.py
[intero file incollato]

## Documentazione API
GET /items restituisce...

Buono (15 righe)

# Inventory API
REST API Flask per l'inventario.

## Comandi
- Avvio: flask run --port 5001
- Test: pytest tests/

## Convenzioni
- Usa type hint
- Mantieni le route leggere

Riferimenti ai file - Uso di @

> @routes.py what endpoints does this API have?

Endpoint API (6 route GET)

Artists
- GET /artists              Tutti gli artisti
- GET /artists/<id>         Singolo artista per ID
- GET /artists/<id>/albums  Album di un artista
Albums
- GET /albums               Tutti gli album
- GET /stats/albums         Statistiche popolarità album
- GET /stats/average-tracks Media tracce per album

Tutti gli endpoint restituiscono JSON.

CLAUDE.md + @ insieme

# CLAUDE.md - Music Analytics API
A Flask-based REST API for music data analytics, providing endpoints for artists,
albums, and statistics.
...


## Key Files
@routes.py - API endpoint definition
@models.py - Artist and Album data models with in-memory store
...

CLAUDE.md offre contesto persistente. Usa @ così Claude conosce sempre i file chiave.

Tre livelli di contesto

Tre livelli di contesto per CLAUDE.md

Quando usare ciascuno

CLAUDE.md (progetto, condiviso)
- Comandi di test, convenzioni di codice, struttura del progetto
CLAUDE.local.md (progetto, personale)
- Percorsi locali, chiavi API, preferenze di flusso di lavoro
~/.claude/CLAUDE.md (globale, personale)
- Preferenze di stile su tutti i progetti
- Comportamenti predefiniti che vuoi sempre

Riepilogo Capitolo 1

/init e CLAUDE.md → Contesto di progetto persistente
Shift+Tab o /plan → Attiva/Disattiva la modalità Piano
think ... ultrathink → Ragionamento profondo (5 livelli)

Esercitiamoci!

Sviluppo software con Claude Code