Chi finanzia una piattaforma di sviluppo assistito non compra «più righe di codice»: compra un ciclo che si chiude da solo e un modo per ricostruire che cosa è successo quando non si chiude.

Il ciclo di verifica viene prima di ogni altra cosa

Le buone pratiche di Claude Code poggiano tutte su un vincolo unico — «LLM performance degrades as context fills» — ma la frase che pesa sul piano operativo è un’altra: «Claude stops when the work looks done». Senza un controllo che l’agente possa eseguire da solo, «sembra fatto» resta l’unico segnale disponibile e il verificatore sei tu: ogni errore aspetta che sia una persona ad accorgersene.

La documentazione mette in scala quattro modi di chiudere il cerchio, e si sceglie in base a quanta attenzione umana ti puoi permettere. Il controllo chiesto dentro lo stesso prompt funziona oggi ma non garantisce nulla. Una condizione di sessione posta con /goal viene rivalutata da un valutatore separato dopo ogni turno. Uno Stop hook esegue il tuo script e impedisce al turno di chiudersi finché non passa. Un subagent avversariale rilegge il diff in un contesto pulito, senza il ragionamento che lo ha prodotto. Solo le ultime due reggono una sessione non presidiata.

Stessa logica per le regole di progetto: CLAUDE.md è consiglio, mentre «hooks are deterministic and guarantee the action happens». Ciò che deve valere sempre — segreti, cartelle intoccabili, lint obbligatorio — si scrive come hook o come regola di permesso, anche perché un CLAUDE.md troppo lungo fa perdere nel rumore proprio le regole a cui tieni.

Automatizzare senza cedere il controllo

La pagina sull’uso non interattivo si intitola «Run Claude Code programmatically»: si integra in pipeline e script come un qualsiasi comando Unix.

git diff main | claude -p "elenca i refusi come file:riga" --output-format json
claude --bare -p "Riassumi README.md" --allowedTools "Read"

Due scelte da difendere in riunione. La prima: in CI si usa --bare, perché senza di esso una sessione con il flag di stampa carica hook, plugin e server MCP del repository anche in una cartella mai dichiarata attendibile; la doc lo definisce «the recommended mode for scripted and SDK calls». La seconda: il permesso di partenza, che qui è manuale su tutti i piani. dontAsk nega tutto ciò che non è coperto da una regola di allow o dai comandi di sola lettura: è la scelta per una pipeline chiusa.

Code Review analizza la PR con più agenti in parallelo e un passo di verifica che filtra i falsi positivi, e marca i rilievi come Important, Nit o Pre-existing. Il fatto architetturale è che «The check run always completes with a neutral conclusion so it never blocks merging through branch protection rules»: se vuoi un cancello sul merge lo costruisci tu, leggendo dal check run il conteggio per severità. Il costo medio dichiarato è di 15-25 dollari per revisione e la leva sulla spesa è il trigger per repository: una volta all’apertura, a ogni push, oppure manuale. In locale, /code-review a effort basso o medio riporta solo i rilievi di cui è più sicuro.

Quando è la configurazione a mentire

Se una funzione configurata non compare, «the cause is usually that the file didn’t load, it loaded from a different location than you expected, or another file overrode it». La sequenza è ordinata: /context per vedere che cosa è entrato davvero nella finestra, poi /hooks, /mcp, /permissions e /status, poi /doctor, poi la bisezione con claude --safe-mode, che disattiva ogni personalizzazione. Un sintomo da saper leggere:

Autocompact is thrashing: the context refilled to the limit...

Non è un capriccio del modello: la compattazione è riuscita e un output enorme ha subito riempito di nuovo la finestra. La correzione è di progettazione: leggere il file a pezzi, o spostare il lavoro pesante in un subagent con la propria finestra.

Errori dell’API e turni di reperibilità

Il runbook parte dalla tassonomia: 400 invalid_request_error, 401, 403, 429 rate_limit_error, 500 api_error, 504 timeout_error, 529 «The API is temporarily overloaded.». Alle tre di notte conta la riprovabilità, non il numero: i 500 si ritentano con backoff esponenziale, un 429 da tetto di spesa no, perché non è una strozzatura temporanea. Claude Code ritenta già più volte prima di mostrare l’errore, con profondità configurabile per le sessioni non presidiate. In ogni ticket va incollato: «Every API response includes a unique request-id header.» Sopra i dieci minuti la doc indirizza su streaming o Batch.

Osservabilità, e il limite da dichiarare

L’SDK non produce telemetria propria: la esporta il processo CLI, in tre segnali indipendenti — metriche, log events e tracce (beta) — verso qualunque backend OTLP. Le tracce danno la gerarchia:

claude_code.interaction
  claude_code.llm_request
  claude_code.tool
    claude_code.tool.execution

Si correla per session.id e, sul lato eventi, per l’identificativo del prompt, che lega le chiamate nate da una stessa richiesta. Sulla privacy vale la riga «The content your agent reads and writes is not recorded by default»: i contenuti si aggiungono solo con variabili opt-in. La trappola per il runbook è invece «The CLI fails silently on export errors by default», quindi un backend muto non prova che l’agente stia bene.

Il limite va detto: la documentazione Anthropic copre telemetria, retry, permessi e conservazione dei dati, ma non definisce SLA contrattuali né una metodologia di A/B testing. Si promette ciò che è strumentato, non ciò che suona bene.