Gli errori più comuni nel costruire app con Claude

Claude è il miglior modello general-purpose per costruire applicazioni reali nel 2026. Ma la maggior parte delle app Claude che analizziamo ripete gli stessi sette errori. Ognuno è semplice da sistemare. Nessuno è ovvio fino a quando sei già in produzione, la bolletta è triplicata, o un cliente ti ha estratto il system prompt.

Questa è la lista che condividiamo con ogni team in onboarding.

1. Trattare il context window come un secchio

Un context window da 200K non è spazio gratuito. Mano a mano che lo riempi, accuratezza e recall degradano. Anthropic chiama questo fenomeno context rot. L'errore è riversare tutto in contesto con il presupposto che più dati producano risposte migliori.

Tratta il contesto come una risorsa da curare, non un bidone in cui buttare. Tieni solo quello che serve al modello per lo step corrente. Per agenti con task multi-step, usa context editing o summary compaction prima che la finestra si riempia.

2. Assumere che il prompt caching funzioni

Il prompt caching può tagliare i costi fino al 90% su prompt stabili. Ma fallisce in silenzio. Se il tuo cache breakpoint finisce su un blocco che cambia tra le richieste (timestamp, variabili per utente, chiavi JSON ordinate casualmente negli schema dei tool), ottieni zero cache hit senza nessun avviso. La request passa. Il conto sale.

Logga cache_creation_input_tokens e cache_read_input_tokens da ogni risposta. Se restano entrambi a zero per una settimana, la cache non sta funzionando. Stabilizza l'ordine di tutto quello che precede il breakpoint. Sposta il contenuto dinamico dopo.

3. Ambiguità negli schema dei tool

Il tool use fallisce più spesso su tool sbagliato e parametri sbagliati. La causa tipica sono nomi e descrizioni dei tool troppo simili. notification-send-user e notification-send-channel sembrano entrambi giusti al modello quando l'utente dice "manda un messaggio".

Investi nelle descrizioni dei tool. Scrivile per uno stagista intelligente, non per te stesso. Testa con prompt al limite. Se due tool si possono confondere, consolidali o rinominali.

4. Trattare la prompt injection come un rischio teorico

La prompt injection è il principale rischio di sicurezza per gli agent AI nel 2026. Non è teorica. Gli attaccanti inseriscono istruzioni nei contenuti che il modello elabora: un issue GitHub, un PDF, un'email. Il modello non sa distinguere in modo affidabile istruzioni di sistema, contenuto utente e contenuto iniettato.

Difese: permessi dell'agent al minimo, esecuzione in sandbox, trattare ogni input non fidato come ostile, filtrare gli output, non rimandare mai contenuto grezzo non fidato nel prompt senza escaping. L'OWASP LLM Prompt Injection Prevention cheat sheet è un buon punto di partenza.

5. Far girare gli agent con troppi permessi

Non dare a un agent accesso Bash generalizzato, accesso al filesystem, o accesso di rete. Gli agent di produzione devono girare in container sandbox con il set allowed_tools più piccolo possibile per fare il lavoro. Usa permission callback. Usa PreToolUse hook per bloccare i path sensibili. Inietta le API key tramite un proxy così l'agent non le vede mai.

Il flag --dangerously-skip-permissions esiste per un motivo: è pericoloso. Non usarlo mai in produzione. Anche con il flag off, l'approval fatigue è reale: gli sviluppatori approvano decine di prompt a sessione e le azioni iniettate passano. Rendi le approvazioni rare e significative.

6. Nessun audit trail, nessun kill switch

Ogni azione di un agent in produzione va loggata: il tool chiamato, gli argomenti, il risultato, l'utente che ha triggerato, il correlation ID. Gli audit trail sono come scopri cosa è andato storto dopo che è andato storto. I kill switch sono come lo fermi mentre sta andando storto.

Se non sai rispondere a "cosa stava facendo l'agent X alle 14:14?" in meno di trenta secondi, non hai observability.

7. Nessuna strategia di versioning del modello

Anthropic rilascia nuove versioni del modello regolarmente. Se ti sei pinnato su claude-sonnet-4-5 e hai costruito i prompt intorno ai suoi difetti, passare all'ultimo Sonnet cambia il comportamento. Se usi l'alias latest, il modello sotto la tua app cambia senza che tu lo sappia.

Scegli una strategia esplicita. Pinna a un modello datato e imposta una schedule per testare le nuove versioni, oppure usa l'alias latest e fai girare una suite di regression test a ogni cambio di modello. Funzionano entrambe. Nessuna strategia no.

La lista breve

Cura il contesto. Verifica la cache. Disambigua i tool. Difenditi dalla prompt injection. Dai agli agent i permessi minimi di cui hanno bisogno. Logga tutto e costruisci un kill switch. Scegli una strategia di versioning.

Nessuno di questi è un difetto specifico di Claude. Sono errori che fa qualunque team costruendo con un large language model la prima volta. Li ripetiamo sui progetti nuovi finché non codifichiamo le regole. Questo post è la nostra lista codificata corrente.

Se stai costruendo qualcosa con Claude e vuoi un secondo paio di occhi sul tuo setup, scrivici.