Scaffolding Anthropic: otto lezioni di architettura agent dal leak del codice Claude Code

Il 31 marzo 2026 alle 00:21 UTC Anthropic ha pubblicato la versione 2.1.88 del pacchetto npm @anthropic-ai/claude-code. Per errore di configurazione del processo di build, il pacchetto includeva una source map da 59.8 MB con 512.000 righe di codice TypeScript non offuscato distribuite su 1.906 file: l'intero scaffolding lato client di Claude Code, il CLI agent che da fine 2024 ha definito il pattern dell'agentic coding tool. Il ricercatore Chaofan Shou ha scoperto e annunciato il leak nelle ore successive; Boris Cherny, engineer Anthropic, ha confermato pubblicamente l'incidente attribuendolo a "developer error, not tooling bug" e sottolineando che la cultura della responsabilità non individuale resta priorità del team. Anthropic ha emesso DMCA takedown su ~8.100 repository GitHub nelle 72 ore successive, ne ha ritirato la maggior parte dopo il backlash della community per scope eccessivamente largo, e ha mantenuto in takedown solo un repository più 96 fork.

Il leak non includeva i pesi del modello né l'architettura della rete neurale (quelle restano protette nel datacenter Anthropic), ma includeva scaffolding architetturale, permission engine, tool registry, feature flags, riferimenti a modelli unreleased e pattern di anti-distillation. Sul mio Hetzner CCX33 (8 vCPU AMD EPYC 9454P, 32 GB RAM DDR5) ho passato due settimane di aprile 2026 ad analizzare le parti pubblicamente leakate prima del takedown, focalizzandomi su quei pattern architetturali che una PMI italiana che costruisce agent interno (MCP server custom, copilot di dominio, automation pipeline) può legittimamente trasferire al proprio sistema senza violare alcuna IP. Le otto lezioni che racconto sotto sono il distillato di quella analisi, ognuna mappata su una scelta architetturale concreta che il consulente serio dovrebbe portare sul tavolo del cliente che sta progettando agent enterprise nel 2026.

Una nota legale preliminare per chiudere la cornice: secondo le dichiarazioni pubbliche di Anthropic, Claude Code è "circa 90% AI-generated", e la giurisprudenza US sulla protezione del copyright per opere AI-generated è ancora aperta (la Corte Suprema US ha rifiutato a marzo 2026 di rivisitare lo human authorship standard). I pattern architetturali generali sono per definizione non protetti da copyright (proteggi codice specifico, non idee), e quello che racconto è esclusivamente lettura dei pattern, non riproduzione di codice.

I tre componenti centrali del scaffolding rivelato

Prima delle otto lezioni operative, vale la pena descrivere i tre componenti centrali che la lettura del codice leakato ha esposto come architettura nucleare di Claude Code.

QueryEngine è l'orchestratore centrale che riceve le user request, costruisce il contesto, decide quali tool invocare, gestisce il loop con il modello backbone (Claude Opus per default ma configurabile), interpreta gli output del modello, applica le validation, ritorna alla user. È il punto di condensa di tutta la logica agentic, e la sua struttura modulare permette di sostituire singoli componenti (es. il selector dei tool) senza riprogettare il resto.

Tool Registry centralizza la dichiarazione dei 50+ tool che Claude Code può invocare (file read/write, bash execution, web fetch, edit incrementale, glob, grep, ecc). Ogni tool è dichiarato con schema input/output, descrizione, side effects, permission requirements. Il registry è interrogabile programmaticamente e permette estensione via plugin.

Permission Engine è il security layer che valida ogni tool invocation contro le policy configurate dall'utente o dal workspace. Permessi possibili: allow, allow with prompt, deny, deny with prompt. Le validation sono multi-layered: pattern matching su path, validation di comandi bash contro whitelist/blacklist, controllo di host network per web fetch, escalation a user per operazioni rischiose. È l'esempio operativo di "containment by design" che ho descritto in dettaglio nel pezzo sul confronto fra Claude Managed Agents e harness self-hosted.

Se costruisci agent interni e vuoi imparare dai pattern Anthropic

Nel mio hub dedicato all'AI per aziende, sezione sviluppo raccolgo articoli sui pattern architetturali per agent enterprise. Le otto lezioni sotto sono trasferibili a chi costruisce MCP server custom o copilot di dominio, e sono particolarmente preziose per il cliente PMI italiana che parte da zero senza riferimenti pubblici equivalenti.

Le otto lezioni architetturali distillate

Lezione uno: separa orchestrator e tool execution. QueryEngine non esegue mai direttamente i tool: delega al Tool Registry che a sua volta delega al Permission Engine. Questa separazione tre-livelli permette test indipendenti, debugging mirato, sostituzione di un singolo strato senza toccare gli altri. Per un MCP server interno la stessa pattern significa: layer di orchestrazione che parla con il modello, layer di tool dichiarati, layer di security/permission. Sono tre file diversi nel progetto, con interfacce esplicite.

Lezione due: prompt caching stratificato. Il codice di Claude Code mostra l'uso di breakpoint cache_control multipli per stratificare il prefix in zone immutabili (system prompt, tool definitions) e zone mutabili (conversation history). Ogni zona è marcata in modo da massimizzare il cache hit nelle chiamate successive. Per la pipeline propria, la lezione operativa è quella che ho già descritto in dettaglio nell'articolo sul prompt caching workspace-level: ordinare il prompt per stabilità decrescente, marcare i breakpoint nei punti giusti.

Lezione tre: feature flags progressivi. Il codice esposto contiene 44 unreleased feature flags con nomi come PROACTIVE, KAIROS, e altri. Anthropic usa feature flags non solo per A/B test ma per progressive rollout di capabilities: il codice è committato e shipped a tutti gli utenti, ma il flag controlla quali utenti vedono effettivamente la feature. Per una PMI che costruisce agent interno, il pattern significa: ogni nuova capability dell'agent è dietro un flag, attivabile per cliente specifico, sperimentabile su subset di traffico, rollback rapido se emergono problemi.

Lezione quattro: anti-distillation con tool fittizi. Il leak ha rivelato che Claude Code invia richieste con flag anti_distillation: ['fake_tools'] che inietta tool definitions decoy nel system prompt. L'obiettivo è avvelenare i dataset di chi tentasse di distillare il comportamento di Claude Code in un proprio modello. Per chi costruisce agent enterprise interno la lezione applicabile non è "imita questo per proteggerti", è "se lo Stack del modello che usi può iniettare segnali specifici, dichiara nel TOS del cliente che quei segnali sono parte dell'integrazione e non vanno usati per training". Soft-IP protection.

Lezione cinque: auto-compact della finestra di contesto. QueryEngine include logica di automatic compaction: quando la conversation cresce oltre soglia, viene compattata mantenendo i punti chiave (decisioni rilevanti, tool call cruciali, recent context) e droppando il rumore. Per un MCP server interno la stessa pattern è essenziale: senza compaction, le session lunghe esauriscono il context budget e degradano la qualità delle risposte. Implementation: middleware che monitora token count, quando si avvicina al threshold invia il contesto a un mini-modello (Sonnet o Haiku) per produrre summary, sostituisce le sezioni vecchie con il summary.

Lezione sei: KAIROS pattern per agent autonomo. Il flag PROACTIVE/KAIROS rivela un pattern di agent autonomo background che riceve heartbeat regolari ("anything worth doing right now?") ed evaluta in autonomia se agire o restare quieto. È un pattern interessante per task di monitoring e proactive maintenance, ma con un trade-off security significativo: un agent che agisce senza prompt esplicito è il modello più rischioso del framework OWASP ASI Top 10 (ASI10 Rogue Agents) di cui ho discusso nell'articolo sul framework OWASP ASI. Per la PMI italiana, applicare il pattern KAIROS richiede confidence stratosferica nel containment, e nei primi 12-18 mesi è meglio restare su pattern reactive con heartbeat solo per check di stato non operativi.

Lezione sette: tool registry estensibile via configurazione, non via codice. Il Tool Registry di Claude Code è progettato per registrare nuovi tool dichiarativamente: una nuova capability è una entry JSON con schema input/output e implementazione, non una modifica al core. Per una PMI che costruisce MCP server interno, lo stesso pattern significa: tool aggiungibili senza release, configurabili per workspace cliente, audit trail su chi ha aggiunto cosa.

Lezione otto: permission engine come security boundary, non come elemento di UX. Il Permission Engine non è un dialogo cosmetico al user: è il security boundary primary del sistema. Ogni tool invocation passa per validation strict, anche quando il user ha pre-autorizzato (es. flag --trust-all-tools, che il leak ha rivelato essere stato il vettore di compromise nel caso Amazon Q descritto nel pezzo su OWASP Top 10 for Agentic Applications come ASI02 Tool Misuse). Per un agent enterprise la lezione operativa è: niente trust-all bypass in produzione, anche se sembra un fastidio per i power user. Il fastidio operativo per gli utenti senior costa molto meno del costo aggregato di un singolo incident di compromissione su pipeline produzione.

Numeri concreti del leak che vale la pena tenere a mente

Per dare scala al fenomeno, e per il consulente che vuole portare il caso al cliente come esempio operativo, riporto qui i numeri specifici che caratterizzano il leak. Versione del pacchetto npm coinvolto: 2.1.88, pubblicato il 31 marzo 2026 alle 00:21 UTC, ritirato circa tre ore dopo (03:29 UTC) ma in quella finestra installato da numerosi sviluppatori che facevano upgrade routinario. Source map exposta: 59,8 MB. Codice sorgente decifrabile: 512.000 righe TypeScript. File esposti: 1.906. Tool nel registry: oltre 50, con dichiarazione esplicita di schema input/output. Feature flags rilevati: 44, di cui PROACTIVE e KAIROS sono i più discussi pubblicamente.

Concorrente ma non correlato direttamente al leak source map: un'attacco supply chain su npm nelle ore intorno alla finestra di pubblicazione, che ha distribuito versioni trojanizzate di Claude Code con backdoor (Vidar Stealer, GhostSocks, Rust-based dropper). Per gli sviluppatori che hanno fatto installazione fresh in quella finestra (00:21-03:29 UTC), la raccomandazione standard è downgrade alla versione safe più recente e rotation di tutti i secret presenti nel proprio environment al momento dell'installazione. È una raccomandazione che ho già visto applicare in due engagement consulenziali nel mese di aprile, e che vale la pena verificare proattivamente con qualunque cliente che usi Claude Code in pipeline CI/CD.

Cinque giorni prima del leak source map, il 26 marzo 2026, un'altra incidente Anthropic aveva esposto via misconfiguration di un CMS interno circa 3.000 documenti interni non pubblicati, incluso materiale dettagliato sul modello Claude Mythos (next-gen flagship). La concomitanza dei due eventi è documentata da Fortune e altri organi di stampa, e il consulente di security che lavora con clienti che usano Claude come backbone deve tenere traccia del pattern di incidenti Anthropic come parte del proprio threat model.

Pattern complessivo da adottare nel proprio MCP server interno

Le otto lezioni messe insieme producono un pattern architetturale concreto applicabile a un MCP server custom enterprise: tre layer separati (orchestrator, tool registry, permission), prompt caching stratificato sull'output dell'orchestrator, feature flags progressive controllate dal workspace owner, automatic context compaction quando si avvicina al threshold, audit trail strutturato su ogni tool invocation, niente bypass di security per power user. Costo di implementazione tipico per un MCP server interno enterprise greenfield è 60-120 giornate di engineering senior, distribuite su 4-6 mesi calendar; il vantaggio rispetto a costruire ad hoc senza framework è in robustezza, capacity di evolvere senza riprogettazione, audit-readiness verso il revisore interno o esterno e conformità anticipata ai requisiti AI Act in vigore dal 2 agosto 2026.

Cosa NON copiare dal leak

Per simmetria, vale la pena enumerare i pattern del leak che NON andrebbero copiati anche se architetturalmente affascinanti. Primo, il KAIROS heartbeat-driven autonomous mode: rappresenta un livello di autonomia che la PMI italiana media non sa contenere, e il rischio di rogue agent (ASI10) supera ampiamente il beneficio operativo per la maggior parte dei use case. Secondo, l'iniezione di anti-distillation fake_tools nei system prompt: è un meccanismo di IP protection che ha valore solo per provider AI che hanno modello e dataset proprietari da difendere; per una PMI che usa modello backbone di terze parti è codice complesso senza beneficio. Terzo, il pattern --trust-all-tools che bypassa permission engine per power user: è esattamente il pattern che ha permesso la compromissione del competitor Amazon Q (ASI02) e che andrebbe esplicitamente proibito nel design del proprio MCP server.

La regola di metodo è: copiare i pattern di robustezza e di cost optimization, evitare i pattern di autonomy aggressiva e di IP protection complessi che non sono adattati al perimetro operativo della PMI italiana media.

Per chiudere, c'è un punto di metodo che vale la pena sottolineare: leggere il codice di un competitor leakato è legalmente delicato (anche se i pattern architetturali sono safe), ed eticamente la community AI ha ricevuto il leak con sentimenti misti. Il pattern responsabile è leggere per imparare i pattern (legittimo), non riprodurre il codice (rischio IP). Questo articolo descrive il primo, non incoraggia il secondo. Se vuoi una conversazione tecnica per progettare il tuo MCP server interno applicando i pattern descritti, oppure un audit del tuo agent attuale alla luce delle otto lezioni che ho distillato dall'analisi del codice esposto, il modulo di preventivo gratuito è il punto da cui inquadrare la richiesta in due minuti, sette domande, prima del prossimo round di engineering della tua pipeline AI.