Claude per Developer

La maggior parte delle guide su come usare l'AI nel coding ti insegna a scrivere prompt più lunghi. Questa no. Ti insegna a ragionare sul contesto, su cosa dare a Claude e come, su dove risparmia token senza perdere qualità. È scritta da chi usa Claude ogni giorno su progetti reali.

🧱​ FONDAMENTA — Come ragiona Claude. Quello che ti serve sapere.

Prima di ottimizzare i prompt, devi capire il modello mentale. Claude non "legge" una conversazione come la leggi tu. Ogni messaggio viene elaborato insieme all'intera storia della chat, dal primo all'ultimo token. Questo ha conseguenze precise sul tuo workflow.

Il context window è la risorsa scarsa. Claude Sonnet 4.6 ha un context window ampio, ma non infinito. Più conversazione c'è, più token vengono consumati per ogni risposta. Una chat lunga su un codebase complesso può diventare cara e lenta. Capire questo è il primo passo per lavorare bene.

Quattro principi da interiorizzare:

01 — Claude non ricorda nulla tra chat diverse. Ogni nuova conversazione parte da zero. La memoria di progetto va esplicitata ogni volta — o meglio, va messa in file permanenti.

02 — Più contesto = risposte migliori. Il codice senza vincoli architetturali, senza tech stack, senza convenzioni di naming produce output plausibile ma culturalmente sbagliato.

03 — Claude ragiona meglio se gli spieghi perché. "Refactor questa funzione perché deve gestire concorrenza" produce un output migliore di "refactor questa funzione".

04 — L'ambiguità genera output mediano. Se il prompt è vago, Claude ottimizza per la risposta più probabile, non per la più utile al tuo contesto specifico.

🗃️​ FILE DI PROGETTO — Il file che cambia tutto: CLAUDE.md

Il modo più efficiente per lavorare con Claude su un progetto reale non è scrivere prompt migliori. È avere un file di contesto permanente che carichi all'inizio di ogni sessione. Claude chiama questo file CLAUDE.md (usato nativamente da Claude Code), ma il concetto funziona anche manualmente copiandolo in chat.

Questo file ha un costo token una tantum per sessione, ma ti risparmia dover rispiegare il progetto ogni volta — e produce output molto più coerente.

Struttura consigliata — CLAUDE.md:

Pro tip: Mantieni il CLAUDE.md in versione controllata nel repo. Diventa documentazione viva del progetto che beneficia tutto il team, non solo chi usa Claude.

Altri file di contesto utili:

• .cursorrules o system_prompt.txt — Per editor con supporto AI: regole di stile, dipendenze vietate, pattern da non usare.
• docs/architecture.md — Diagramma testuale dei bounded context, flussi principali, decision log. Claude lo usa per non proporre soluzioni che contraddicono l'architettura esistente.
• docs/api-contracts.md — Endpoint, schema request/response, codici errore. Evita che Claude inventi payload API.
• docs/golden-path.md — Un esempio end-to-end commentato di come si fa "una cosa nuova" nel progetto. È il reference che Claude imita per produrre codice stilisticamente coerente.

⌨️​ PROMPT ENGINEERING — Il prompt perfetto non esiste. Questa struttura sì.

Non esiste una formula magica, ma esiste una struttura che funziona consistentemente su task tecnici complessi. La chiamiamo CRVE: Contesto, Richiesta, Vincoli, Esempio.

❌ Prompt debole:

Scrivi una funzione che valida un form di registrazione con nome, email e password.

✓ Prompt CRVE:

Contesto: Sto usando React 19 + Zod + React Hook Form. Il form è in /components/auth/RegisterForm.tsx.

Richiesta: Crea lo schema Zod per la validazione.

Vincoli: Password min 8 caratteri, almeno 1 numero. Email lowercase. Non usare yup. Errori in italiano.

Esempio atteso: Lo schema deve poter essere riutilizzato nell'API backend (è già definito in /shared/schemas/auth.ts).

La differenza non è la lunghezza. È la densità informativa. Il secondo prompt elimina interi gradi di libertà che Claude altrimenti usa per fare scelte che tu poi devi correggere.

Quando chiedere spiegazioni prima del codice

Su task ad alta complessità o impatto, c'è un pattern che vale quasi sempre: chiedi prima il piano, poi il codice.

Attenzione: Su refactoring di sistema o migrazioni, non saltare questo step. Claude può produrre codice corretto localmente ma sbagliato nel contesto del tuo sistema. Rendere visibile il ragionamento ti permette di intercettare questi errori prima che siano nel codice.

🫰​ TOKEN ECONOMY — Risparmio token: dove conta davvero.

I token sono soldi (se usi l'API) o velocità (se usi il piano). In entrambi i casi, spenderli bene è una skill.

🔴​ Spreco alto — da evitare sempre

Incollare tutto il file per chiedere di una singola funzione. Manda solo la funzione più la signature delle dipendenze dirette. Il resto è rumore che consuma context window senza migliorare la risposta.

Tenere chat lunghissime su un bug. Dopo 15-20 scambi su uno stesso problema, apri una nuova chat con il contesto sintetizzato. Le chat lunghe degradano: Claude porta con sé tutti i tentativi falliti precedenti e le correzioni, e questo inquina le risposte successive.

Chiedere a Claude di "leggere il progetto" senza filtro. Non mandare 10 file sperando che capisca da solo cosa è rilevante. Seleziona tu i file pertinenti al task specifico e mandali con una riga di introduzione.

🟡​ Spreco medio — vale la pena ottimizzare

Usare Opus per task meccanici. Boilerplate, regex, rinominare variabili, convertire formati: Haiku è sufficiente e costa una frazione. Opus serve per ragionamento architetturale profondo, non per generare un migration file.

Ripetere il contesto di progetto a ogni messaggio. Mettilo nel primo messaggio della sessione, una volta sola. Se lavori con Claude Code, sta tutto nel CLAUDE.md. Se lavori in chat, incollalo all'inizio e basta.

Chiedere documentazione verbosa per tutto. Specifica il livello: "aggiungi solo i JSDoc mancanti, non riscrivere quelli esistenti" oppure "commenta solo le parti non ovvie". Altrimenti Claude documenta anche const x = 1.

🟢​ Spreco basso — ma vale saperlo

Chiedere test per funzioni già coperte. Specifica: "scrivi solo unit test per i casi edge non ancora coperti da useCart.test.ts". Senza questo, Claude riscrive test che esistono già.

Chiedere risposte con spiegazioni quando non ti servono. Se sai già cosa stai chiedendo, aggiungi "scrivi solo il codice, senza spiegazioni". Taglia il 30-40% dei token in output su task semplici.

✅​ TASK SPECIFICI — I pattern che usiamo ogni settimana.

Code review assistita

Claude è un reviewer eccellente se gli dai il frame giusto. Non "cosa ne pensi di questo codice?" ma una review strutturata:

Debugging sistematico

Per i bug complessi, il modo migliore non è chiedere "cosa c'è di sbagliato" — è fare lavorare Claude come un debugger strutturato:

Architettura e decisioni tecniche

Questo è il task dove Claude dà il massimo, e anche quello dove è più facile fare danni se usato male. La chiave: non chiedere "qual è la soluzione migliore" ma "analizza questi trade-off nel mio contesto".

❌ "Qual è il modo migliore per gestire l'autenticazione in una SPA React?"

✓ "Ho una SPA React con Elixir backend. Attualmente uso JWT con refresh token in localStorage. Devo gestire sessioni su più tab e logout sicuro. Analizza cookie httpOnly vs localStorage nel mio contesto, considerando che ho già un API gateway che potrei usare per gestire i cookie server-side."

Generazione di test

Claude genera test di buona qualità se specifichi esattamente cosa vuoi testare. Altrimenti tende all'happy path:

🔃​ WORKFLOW — Come integrare Claude nel tuo flusso reale.

La regola del "checkpoint cognitivo"

Prima di accettare qualsiasi output di Claude che tocchi più di 50 righe di codice, fai mentalmente questo check:

→ Capisco ogni riga di questo codice? Se no, non accettarlo — chiedi spiegazioni.

→ Questo codice è coerente con il pattern già esistente nel progetto?

→ So dove si potrebbe rompere? Ho pensato ai failure mode?

→ Il test copre i casi che mi preoccupano davvero, non solo quelli ovvi?

→ Se lo dovessi revisionare tra 6 mesi, capirei le scelte fatte?

Non stai verificando se Claude ha sbagliato. Stai verificando se tu hai ancora il contesto. È una skill diversa, e più importante.

Cicli brevi vs sessioni lunghe

Le sessioni lunghe su un singolo task tendono a degradare. Claude inizia bene, poi dopo molti scambi le risposte diventano meno coerenti perché il context window è pieno di tentativi precedenti e correzioni.

Il pattern migliore per task complessi:

→ Sessione 1: Esplora il problema, chiedi analisi e piano. Non chiedere codice.

→ Sessione 2: Nuova chat con solo il piano confermato come contesto. Chiedi implementazione a pezzi.

→ Sessione 3: Nuova chat con il codice prodotto. Chiedi review e test.

Sembra più lento. È più veloce perché eviti il loop di correzioni in chat degradate.

Il sistema delle annotazioni

Quando Claude produce codice che accetti, prendi l'abitudine di annotare nel codice stesso cosa ha fatto e perché. Non per documentare Claude — per documentare la decisione.

❌​ ERRORI DA EVITARE — Le trappole in cui cadono i developer.

Il "vibe check" come code review

Guardare il codice di Claude e dire "sembra giusto" non è una review. È il pattern più pericoloso. Il codice generato da AI tende a sembrare corretto — usa naming sensato, struttura pulita, commenti coerenti. Ma può avere bug di logica sottili che non si vedono senza leggere davvero.

Il prompt che cambia a metà

Iniziare con "crea una API REST" e poi aggiungere "ah ma deve supportare anche WebSocket" e poi "e in realtà il modello è diverso da così" in 10 messaggi. Ogni correzione costa token e degrada la coerenza. Specifica prima, chiedi dopo.

Usare Claude come oracolo su librerie nuove

Claude ha un cutoff di conoscenza. Su librerie aggiornate frequentemente (React Query, Prisma, tRPC nelle ultime versioni), può dare risposte basate su API vecchie. Verifica sempre sulla documentazione ufficiale quando usi funzionalità recenti.

Dimenticare che Claude non conosce il tuo business

Claude non sa che nella tua piattaforma "utente premium" ha una semantica specifica, che certi clienti hanno contratti speciali, che quella feature di export va disabilitata per motivi legali in tre paesi. Questo contesto di dominio non sta nel codice — va esplicitato nel prompt.

Regola pratica: Ogni volta che pensi "Claude non saprebbe questo", sei nel territorio dove il contesto fa tutta la differenza. Queste sono le cose da mettere nel CLAUDE.md.

😎​ CHEATSHEET — Il riferimento rapido.

Frasi che migliorano qualsiasi prompt tecnico:

→ "Prima dimmi cosa toccheresti, poi aspetta la mia conferma"

→ "Dammi 2-3 approcci con i rispettivi trade-off, poi sceglierò"

→ "Non riscrivere il codice esistente che funziona, modifica solo [X]"

→ "Usa il pattern già presente in [file], non inventarne uno nuovo"

→ "Se non hai abbastanza contesto per rispondere bene, dimmi cosa ti serve"

→ "Segnalami se stai facendo assunzioni che potrebbero essere sbagliate"

→ "Scrivi solo il codice, senza spiegazioni — so già cosa fa"

→ "Rispondimi solo con la modifica diff, non l'intero file"

Template di sessione per nuova feature (copia-incolla):

Conclusione

Claude non è un tool per scrivere più codice. È un tool per prendere decisioni migliori più velocemente. La differenza sta nel come lo usi: come generatore di output o come interlocutore tecnico con il contesto del tuo progetto.

Il secondo richiede più setup iniziale. Ripaga ogni giorno.