I file di configurazione di un progetto che lavora con un agente AI invecchiano male. CLAUDE.md, AGENTS.md, le skill personalizzate e i prompt applicativi accumulano nel tempo istruzioni scritte per compensare i limiti di un modello che nel frattempo è stato sostituito due volte. Nessuno le rilegge: si stratificano.
Il comando /claude-api prompt-audit, aggiunto alla skill ufficiale claude-api distribuita con Claude Code, serve esattamente a questo: passa al setaccio quei file e propone di ripulirli.
Come si usa
Si lancia dentro Claude Code, dalla cartella del progetto:
/claude-api prompt-auditNon serve avere un'integrazione con l'API di Claude: il comando funziona anche su progetti che usano Claude Code e basta. L'analisi copre quello che trova nella directory di lavoro — sia il codice applicativo che chiama l'API, sia la configurazione dell'agente.
Cosa cerca
Gli anti-pattern segnalati sono quelli che i modelli di frontiera prendono alla lettera pagandoli in token e latenza:
- Rituali di verifica — «ricontrolla il tuo lavoro», «verifica due volte prima di rispondere». Il modello obbedisce: rilegge, ripete controlli, allunga la risposta senza migliorarla
- Booster di esaustività ed enfasi — «sii massimamente esaustivo», «CRITICO: DEVI SEMPRE…». Producono verbosità e chiamate a strumenti aggiuntive
- Forzature del ragionamento — «pensa passo per passo», «ragiona con attenzione»: inutili su modelli che ragionano di loro e decidono da soli quanto
- Workaround diventati obsoleti — istruzioni per aggirare limiti su immagini, grafici o formati che il modello attuale gestisce nativamente
Cosa restituisce
Il risultato è un report più un diff proposto: si vede riga per riga cosa verrebbe tolto e perché, e si decide cosa accettare. Non è una riscrittura silenziosa del progetto, ed è la ragione per cui vale la pena lanciarlo anche solo per curiosità su un repository maturo — spesso l'elenco è più lungo del previsto.
Il momento naturale per usarlo è la migrazione a un modello nuovo. Chi è passato a Opus 5.5 o a Fable 5.1 si porta dietro istruzioni scritte per la generazione precedente: l'audit è il modo più rapido per accorgersene.
Cosa aspettarsi in pratica
| Effetto | Perché |
|---|---|
| Risposte più rapide | Spariscono i cicli di verifica richiesti esplicitamente |
| Meno token consumati | Meno verbosità difensiva e meno chiamate a strumenti superflue |
| Istruzioni più leggibili | Il file resta con le regole che descrivono il progetto, non il modello |
| Nessun cambiamento imposto | Il comando propone un diff, l'applicazione resta una scelta |
Una regola che ne discende
Il criterio da tenere quando si scrive un CLAUDE.md è quello: il file deve contenere ciò che è vero del progetto — convenzioni, percorsi, stack, vincoli, comandi di build — non istruzioni su come il modello deve pensare. La prima categoria resta valida per anni, la seconda scade a ogni rilascio.