Spotify ha sviluppato un sistema per ridurre il consumo di token di Claude Code delegando a modelli più economici le attività che richiedono molta elaborazione di input e output ma poco ragionamento avanzato. L’approccio nasce dall’osservazione che una parte significativa del lavoro svolto dagli agenti di coding consiste nella lettura di file molto grandi, nell’analisi di più documenti per ricavare poche informazioni rilevanti o nella generazione di codice ripetitivo basato su pattern già presenti nel repository. In questi casi l’utilizzo diretto di un frontier model comporta il caricamento di grandi quantità di contesto senza un beneficio proporzionato nelle capacità di ragionamento. Nei test condotti da Spotify su un monorepo Java, la delega delle operazioni di lettura massiva ha prodotto una riduzione media del consumo di token di Claude di circa il 90%.
Il sistema utilizza AiKA Modes, una funzionalità di Portal by Spotify che permette di definire agenti dichiarativi eseguiti all’interno di runtime effimeri. Ogni Mode contiene istruzioni, il modello da utilizzare, parametri come la temperature ed eventuali strumenti MCP, mentre Portal gestisce l’infrastruttura necessaria all’esecuzione senza richiedere server persistenti o la gestione diretta delle API key. I Mode possono essere richiamati attraverso la CLI o le API di Portal e possono essere privati oppure condivisi con l’intera organizzazione. Nell’implementazione descritta da Spotify sono stati creati due Mode principali, bulk-reader e code-writer, entrambi configurati negli esempi con Gemini 2.5 Flash, anche se il sistema permette di utilizzare qualsiasi modello disponibile nell’istanza Portal.
Bulk-reader viene utilizzato quando Claude Code dovrebbe leggere più file di grandi dimensioni semplicemente per rispondere a una domanda circoscritta. Invece di inserire l’intero contenuto dei file nel contesto del modello principale, il sistema invia i documenti al worker model insieme alla domanda dell’utente e restituisce a Claude soltanto una sintesi strutturata delle informazioni necessarie. Il secondo Mode, code-writer, è destinato invece alla generazione di file caratterizzati da strutture ripetitive, come test, boilerplate o implementazioni basate su file di riferimento già esistenti. Il codice prodotto può essere scritto direttamente su disco dal worker senza essere prima generato come output nel contesto di Claude, evitando quindi sia i token necessari per leggere il materiale di riferimento sia quelli che il modello principale avrebbe utilizzato per produrre il nuovo file.
La prima versione del sistema utilizzava regole inserite nel file CLAUDE.md per indicare a Claude quando delegare determinate attività, ma Spotify ha abbandonato questa soluzione perché le istruzioni erano soltanto consultive: il modello poteva ignorarle e ogni progetto doveva mantenere una propria copia delle regole. Il meccanismo attuale è stato quindi trasformato in un plugin per Claude Code chiamato shunt, che forza il routing attraverso il registro delle azioni della Portal CLI. Il plugin utilizza due hook PreToolUse eseguiti prima delle chiamate agli strumenti. Il primo, check-file-size, intercetta ogni operazione Read e blocca automaticamente la lettura quando il file supera una soglia configurabile, impostata di default a 350 righe, invitando Claude a utilizzare bulk-reader. Le letture mirate di una specifica sezione possono invece procedere normalmente.
Il secondo hook, check-bash-read, intercetta i tentativi di leggere file di grandi dimensioni attraverso comandi shell come cat, head, tail, less e more. Anche in questo caso il sistema evita che il contenuto completo entri direttamente nel contesto del modello principale, mentre lascia passare i comandi che effettuano selezioni mirate, per esempio una pipeline che utilizza grep. La soglia dei 350 linee non è fissa e può essere modificata attraverso la variabile d’ambiente SHUNT_MIN_LINES, anche all’interno del file .claude/settings.json. La distinzione tra letture massive e mirate serve a mantenere il vantaggio economico della delega senza introdurre inutilmente latenza nelle attività di piccole dimensioni.
L’esecuzione pratica viene gestita anche attraverso due script Bash che incapsulano le chiamate alla Portal CLI. Claude passa agli script argomenti nominati, mentre questi ultimi costruiscono la richiesta, invocano il Mode corretto, gestiscono gli errori e riportano separatamente il consumo dei token. Nel caso di bulk-read, ogni file viene racchiuso in tag XML per mantenere chiari i confini tra i diversi contenuti prima di essere inviato al worker insieme alla domanda. I Mode vengono risolti da Portal per nome senza distinzione tra maiuscole e minuscole, dando priorità alla versione personale dell’utente, poi a quella del team e infine a quella pubblica. È quindi possibile creare una variante personalizzata di bulk-reader o code-writer senza modificare il plugin che effettua il routing.
Spotify ha misurato il sistema su quattro scenari all’interno di un monorepo Java, confrontando i token che Claude avrebbe utilizzato leggendo direttamente i file con quelli necessari per elaborare le sintesi restituite da bulk-reader o per coordinare il lavoro di code-writer. Nei test di lettura massiva il risparmio medio è risultato vicino al 90%. Il caso della generazione di codice è più difficile da quantificare direttamente perché, senza delega, Claude deve sia leggere i file di riferimento sia generare il nuovo contenuto utilizzando token di output costosi, mentre con shunt il worker può produrre il codice e scriverlo direttamente su disco senza che il modello principale lo debba ricevere integralmente.
La delega presenta però limiti precisi. Le operazioni di editing non possono essere affidate completamente al worker perché le sintesi prodotte non contengono riferimenti di riga sufficientemente affidabili per effettuare modifiche puntuali; quando Claude deve intervenire sul codice, deve quindi leggere direttamente la specifica porzione interessata attraverso offset e limit. Anche il ragionamento complesso rimane escluso dal routing: durante i test il modello worker riusciva a individuare pattern superficiali ma non ha riconosciuto un problema sottile di thread safety, identificato invece rapidamente da Claude una volta ricevuto il contesto necessario. Per questo motivo debugging, decisioni architetturali e codice safety-critical vengono mantenuti deliberatamente sul modello più potente.
Un altro limite è la latenza. Ogni delega comporta un passaggio da Claude Code al backend Portal, quindi al worker model e infine nuovamente a Claude, con tempi tipici compresi tra 10 e 30 secondi. Portal impone inoltre un limite di 30 secondi per una singola invocazione, per cui le generazioni molto grandi devono essere suddivise in più richieste. La delega risulta quindi vantaggiosa soprattutto per file voluminosi e attività ripetitive, mentre sui file piccoli il costo aggiuntivo della chiamata può superare il beneficio ottenuto dalla riduzione dei token. La soglia configurabile utilizzata dagli hook serve precisamente a separare questi due casi.
L’architettura non è limitata ai due Mode realizzati inizialmente. Lo stesso meccanismo può essere utilizzato per creare agenti specializzati nella documentazione, nelle traduzioni, nella sintesi delle code review o in altre attività caratterizzate da grandi quantità di input ma requisiti di ragionamento relativamente ridotti. La decisione su quando delegare rimane separata dal modello incaricato di eseguire il lavoro: il plugin shunt stabilisce quando effettuare il routing, mentre il Mode definisce come elaborare il compito. È quindi possibile sostituire Gemini 2.5 Flash con un altro modello, modificare le istruzioni o aggiungere nuovi strumenti MCP senza cambiare la logica del plugin. Bulk-reader e code-writer sono già disponibili come Mode pubblici e il plugin shunt fa parte del marketplace spotify/portal-ai-plugins.
Il sistema può essere installato aggiungendo il marketplace spotify/portal-ai-plugins a Claude Code e installando i plugin portal e shunt. Il plugin Portal fornisce la CLI utilizzata per eseguire la delega, mentre shunt applica automaticamente le regole di routing. Una volta configurata e autenticata la CLI attraverso Portal, le richieste che coinvolgono file sufficientemente grandi vengono intercettate automaticamente e indirizzate al Mode appropriato. Il principio utilizzato da Spotify consiste quindi nel mantenere Claude Code come agente principale per pianificazione, comprensione e ragionamento complesso, spostando invece lettura massiva e generazione ripetitiva su worker più economici per ridurre il volume di contesto elaborato dal modello frontier.
Questo articolo è stato redatto con il supporto di strumenti di intelligenza artificiale (AI)