Sviluppare: il criterio di uscita è un set di valutazione

Nel ciclo di vita classico — sviluppare, rilasciare, esercire, mantenere — la fase di sviluppo di un’applicazione Claude ha un artefatto che altrove non esiste: il set di valutazione. Serve perché il componente centrale non è deterministico e non si fissa con un test di uguaglianza su una stringa. La documentazione suggerisce di strutturare le domande in modo da correggerle automaticamente (scelta multipla, confronto esatto, correzione via codice, correzione fatta da un modello) e di preferire molti casi con segnale più debole a pochi casi corretti a mano: sono più economici da rilanciare, e verranno rilanciati a ogni cambio di modello o di prompt.

La scelta del metodo di correzione è una decisione di progetto. Dove l’output è categoriale — una classificazione, un’estrazione — il confronto esatto vince perché non ha zone grigie. Dove il criterio è soggettivo (tono, aderenza al contesto) si usa un modello come giudice, e la documentazione avverte di usarne uno diverso da quello sotto esame. Il set di valutazione sopravvive a tutto il resto del ciclo: è lo stesso strumento della fase di manutenzione.

Rilasciare: cosa può cambiare sotto di te senza preavviso

Ogni richiesta porta l’header anthropic-version, e gli SDK lo impostano da soli. Il contratto della versione va letto con attenzione, perché non promette ciò che molti assumono. Per una data versione Anthropic conserva i parametri di input e di output esistenti, ma può aggiungere input opzionali, aggiungere valori all’output, cambiare le condizioni di specifici tipi di errore e aggiungere nuove varianti ai valori tipo enum — l’esempio citato nella documentazione sono proprio i tipi di evento dello streaming. La frase di sintesi è: «Generally, if you are using the API as documented in this reference, Anthropic will not break your usage.»

La conseguenza pratica è precisa: un parser con uno switch esaustivo sui tipi di evento o di blocco di contenuto, con un ramo di default che solleva un’eccezione, si romperà su un cambiamento perfettamente compatibile. Fai in modo che i consumatori registrino e ignorino le varianti sconosciute invece di trattarle come errore. È il difetto che si manifesta settimane dopo il rilascio, senza che tu abbia toccato nulla.

Esercire: identificatori di richiesta, errori tipizzati, spesa

In esercizio servono tre cose: sapere quale richiesta è andata storta, sapere se ha senso ritentare, sapere quanto stai spendendo.

Ogni risposta porta un header request-id, che ricompare come campo request_id nel corpo degli errori: è l’identificatore da mettere nei log e da allegare a un ticket. Gli SDK espongono eccezioni tipizzate, e la documentazione dice di intercettare quelle classi invece di fare match sulle stringhe dei messaggi. Le riprove sono già dentro: «The official SDKs automatically retry transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the retry-after header when present.»

Qui vive un errore di esercizio molto comune. Due risposte diverse condividono lo stesso codice 429 e lo stesso tipo rate_limit_error: il superamento di un limite di frequenza, che porta un header retry-after ed è temporaneo, e il raggiungimento del tetto di spesa mensile, che non lo porta e continuerà a fallire fino al mese successivo. Nel secondo caso le riprove automatiche bruciano tempo e non risolvono niente; a distinguerli è un campo del corpo:

{
  "error": {
    "type": "rate_limit_error",
    "details": { "error_code": "enforced_spend_limit_reached" }
  }
}

Allo stesso modo, un errore può arrivare dentro uno stream dopo che l’API ha già risposto 200: un client che controlla soltanto il codice HTTP registra come riuscita una generazione fallita.

Per la spesa non basta sommare i token delle risposte. La Usage & Cost Admin API espone il consumo in bucket da un minuto, un’ora o un giorno, con raggruppamento per modello, workspace, chiave API e service tier; «Usage and cost data typically appears within 5 minutes of API request completion, though delays may occasionally be longer». Richiede credenziali di amministrazione: una chiave legata a un singolo workspace non funziona.

Mantenere: modelli e parametri hanno una data di scadenza

La manutenzione di un’applicazione Claude ha una scadenza esplicita che il software tradizionale non ha. Il ciclo di vita di un modello ha quattro stati — Active, Legacy, Deprecated, Retired — e le richieste a un modello ritirato falliscono. Il preavviso è contrattualizzato: «Anthropic notifies customers with active deployments for models with upcoming retirements, providing at least 60 days’ notice before model retirement for publicly released models.» Le date valgono per le piattaforme gestite da Anthropic; Amazon Bedrock e Google Cloud fissano calendari propri, quindi un’applicazione multipiattaforma ha più di una scadenza da tenere.

Non scadono solo i modelli. Anche i parametri vengono deprecati: temperature, top_p e top_k restituiscono un errore 400 se impostati a un valore non predefinito sui modelli Claude 4.7 e successivi, e nell’SDK Python dalla versione 1.0 sono stati rimossi dai tipi, quindi passarli solleva un TypeError. Un aggiornamento di libreria può quindi rompere codice che il giorno prima compilava.

Il modo pratico di chiudere il cerchio: dalla pagina Usage della Console si esporta un CSV con il consumo per chiave API e per modello, che dice quali servizi chiamano ancora il modello in ritiro; poi si rilancia contro il sostitutivo il set di valutazione della prima fase. È quello che trasforma la migrazione da salto nel buio in una misura.