# mazmanov-portal-spotify-shunt-claude-code-tokens-2026-09-03

## Veille

Post di ingegneria di **Spotify** pubblicato il **3 settembre 2026** su engineering.atspotify.com (~1.600 parole, nove sezioni, due manifest YAML, quattro esempi da riga di comando), a firma di **Dimitri Mazmanov**, Principal Product Manager. Descrive una configurazione personale progettata per spostare i task di I/O fuori dal contesto di **Claude Code**. La premessa dichiarata in apertura: *« Most of what an AI coding agent does for me isn't thinking. It's I/O »* — leggere cinque file per rispondere a una domanda su un singolo metodo, produrre un test modellato sugli altri venti della directory. **(A) Le modalità.** **Portal by Spotify** espone *AiKA Modes*, agenti dichiarativi su un runtime effimero — istruzioni, modello, temperatura, strumenti **MCP** — paragonati a *« AWS Lambda, but for agents »*; due modalità pubbliche, `bulk-reader` e `code-writer`, girano qui su **Gemini 2.5 Flash**. **(B) Il routing.** Un plugin per Claude Code chiamato `shunt` sostituisce le regole in `CLAUDE.md` ritenute *« advisory, not enforced »* con tre livelli: hook `PreToolUse` che bloccano qualsiasi lettura oltre le **350 righe** (soglia regolabile via `SHUNT_MIN_LINES`), due script bash che richiamano la Portal CLI, due skill che forniscono la sintassi di invocazione. Il corpus passa al modello secondario e **non entra mai nel contesto di Claude**. **(C) Misurazioni e i loro limiti.** Su un monorepo Java, quattro scenari, il risparmio medio riportato è di **~90%** su `bulk-read`; l'autore nota che lo scenario `code-write` è *« harder to measure »*, ed elenca tre limiti — editing non delegabile, ragionamento non delegabile, **10-30 secondi** di latenza per chiamata. Estende le questioni di budget affrontate in [[gupta-token-budget-wars-marginal-token-utility-2026-05-28]] e la delega esaminata in [[willison-fable-judgement-delegation-subagents-2026-07-03]].

## Titre Article

Portal by Spotify cut my Claude Code token usage by 90%

## Date

2026-09-03

## URL

https://engineering.atspotify.com/2026/9/portal-by-spotify-cut-my-claude-code-token-usage-by-90

## Keywords

Portal by Spotify, AiKA Modes, shunt, Claude Code plugin, model routing, secondary model, I/O delegation, Gemini 2.5 Flash, bulk-reader, code-writer, PreToolUse hooks, read blocking, line threshold, SHUNT_MIN_LINES, skills, Portal CLI, ephemeral runtime, declarative agent, MCP, token budget, cost per developer, output tokens, agent context, Java monorepo, delegation latency, plugin marketplace, spotify/portal-ai-plugins, Backstage, AI FinOps

## Authors

Dimitri Mazmanov (Principal Product Manager, Spotify), sur le blog d'ingénierie engineering.atspotify.com.

## Ton

**Profilo**: un resoconto di esperienza individuale pubblicato su un blog di ingegneria aziendale, in prima persona, che funge anche da promozione apertamente dichiarata di un prodotto interno. Pubblico: utenti avanzati di agenti di coding e responsabili di piattaforme interne.

**Stile**: il testo segue una progressione da dimostrazione tecnica — problema quantificato, soluzione, architettura a livelli numerati, misurazioni, limiti, istruzioni d'uso. Gli artefatti sono forniti per intero: due manifest YAML completi, quattro invocazioni da riga di comando, la variabile d'ambiente della soglia, i tre comandi di installazione. I dettagli implementativi sono esposti piuttosto che riassunti, comprese le micro-decisioni e la loro motivazione — l'istruzione *« output only the code »* è giustificata dai blocchi markdown che Claude dovrebbe altrimenti parsare, il file di riferimento obbligatorio dal codice fuori contesto che un modello produrrebbe senza di esso.

**Posizione epistemica**: il titolo mostra un risultato quantificato, ma il corpo del testo lo delimita da sé. Un'intera sezione, *« What doesn't work »*, elenca ciò che la configurazione non fa: nessun editing delegato per mancanza di numeri di riga affidabili, nessun ragionamento delegato — un bug di *thread-safety* mancato dal modello secondario, colto da Claude —, e un sovraccarico di latenza che rende la delega controproducente sotto la soglia. La misurazione stessa resta dichiarativa: quattro scenari su un monorepo Java, senza protocollo pubblicato, senza volumi assoluti, senza conteggio del costo del modello secondario. La sezione finale sposta esplicitamente la posta in gioco dalla cifra alla riutilizzabilità delle modalità, formulata come *« they turn model routing from a systems engineering problem into a configuration problem »*.

## Pense-betes

- **L'intuizione di partenza è la ripartizione del carico, non l'ottimizzazione del prompt.** Leggere file e generare codice ripetitivo consuma token senza richiedere ragionamento; questi task vanno a un modello economico, mentre il modello primario mantiene i problemi che richiedono giudizio.
- **Ciò che si risparmia non è solo il costo, è l'occupazione del contesto.** Il corpus letto viene inviato al modello secondario e non entra mai nella finestra di Claude; una query successiva sugli stessi file quindi non ricarica nulla sul lato primario. Stesso meccanismo della delega ai subagent in [[willison-fable-judgement-delegation-subagents-2026-07-03]].
- **Una mode = un agente dichiarativo**: nome, descrizione, istruzioni, modello, `visibility`, `resourceLimits`, `tags`. Runtime effimero, nulla memorizzato lato server, nessuna chiave API da gestire. Risoluzione per nome, case-insensitive, con precedenza personale → team → pubblico: fare il fork di una mode pubblica basta per sovrascriverla senza configurazione.
- **Le regole in `CLAUDE.md` non hanno retto.** Prima versione del routing: un blocco di istruzioni che Claude leggeva e talvolta seguiva. Due difetti nominati — *advisory, not enforced*, e il dover essere copiate in ogni progetto. È l'argomento che guida il passaggio agli hook, gate rigidi indipendenti dalla decisione del modello.
- **La soglia è il parametro di tuning centrale.** `check-file-size` blocca le chiamate `Read` oltre le 350 righe di default; `check-bash-read` intercetta `cat`, `head`, `tail`, `less`, `more`. Le letture mirate (`offset`/`limit`) e i comandi con pipe passano. Sotto la soglia, la latenza della delega costa più di quanto faccia risparmiare.
- **Il degrado controllato è il punto architetturale centrale.** Tre livelli: l'hook blocca, lo script esegue, la skill spiega. Se Claude ignora la skill, l'hook blocca comunque — il contratto non è affidato al modello.
- **Due istruzioni della mode fanno gran parte del lavoro.** *Output only the code* evita i blocchi markdown e la prosa che il modello primario dovrebbe poi riparsare; un file di riferimento obbligatorio per `code-writer` evita codice fuori contesto. Stessa logica di inquadramento delle skill descritte in [[shihipar-claude-code-lessons-building-skills-2026-06-03]].
- ⚠️ **La cifra di punta è autodichiarata e non riproducibile come presentata**: una media su quattro scenari su un monorepo Java, senza protocollo, senza volumi assoluti, senza confronto con un modello primario usato con letture mirate. L'autore ammette che lo scenario `code-write` è più difficile da misurare, e il costo del modello secondario non viene sottratto.
- **I tre limiti dichiarati delimitano l'ambito**: nessun editing delegato (numeri di riga nei riassunti inaffidabili), nessun ragionamento delegato (debugging, decisioni architetturali e codice critico esplicitamente esclusi dal routing), 10-30 s di latenza per andata e ritorno, con un tetto di 30 s di Portal che costringe a suddividere le generazioni ampie.
- **La conclusione operativa riguarda le modalità, non il plugin**: riutilizzabili tra progetti, condivisibili (entrambe le modalità sono pubbliche), componibili (`doc-writer`, `reviewer`, `translator` citati come possibili estensioni), e disaccoppiate dal routing — cambiare il modello di lavoro non cambia il plugin. Questa separazione packaging/esecuzione è quella formalizzata da [[google-agent-plugins-packaging-skills-mcp-2026-08-06]].
- **Installazione**: `claude plugin marketplace add spotify/portal-ai-plugins`, poi i plugin `portal` (la CLI) e `shunt` (routing), quindi `/portal:setup` per l'autenticazione contro un'istanza Portal. La configurazione presuppone quindi un'istanza Portal con il plugin AiKA abilitato — non è trasferibile così com'è al di fuori di un'organizzazione che la gestisce.
- **Le cifre di inquadramento provengono dall'esterno del post e non sono sourciate**: costi dell'IA per il coding che superano lo stipendio medio di uno sviluppatore entro il 2028, un quarto dei responsabili di ingegneria tra 200 e 500 dollari per sviluppatore al mese, alcuni sopra i 2.000. Da trattare come ordine di grandezza, da confrontare con le misurazioni per team in [[patel-block-buzz-teams-tokens-benchmarks-2026-08-06]].

## RésuméDe400mots

Dimitri Mazmanov, Principal Product Manager presso Spotify, ha pubblicato il 3 settembre 2026 sul blog di ingegneria dell'azienda il resoconto di una configurazione che, secondo quanto riferito, taglia del 90% il consumo di token in Claude Code. L'osservazione di partenza: la maggior parte di ciò che un agente di coding fa per lui non è ragionamento ma I/O — leggere cinque file per rispondere a una domanda su un metodo, generare un file di test identico agli altri venti adiacenti. Questo lavoro viene inviato a un modello frontier sovradimensionato, quando un modello economico se la caverebbe altrettanto bene.

La soluzione si basa su AiKA Modes di Portal by Spotify: agenti dichiarativi eseguiti su un runtime effimero, definiti da istruzioni, un modello, parametri e strumenti MCP, senza infrastruttura né chiavi API da gestire. L'autore crea due modalità pubbliche eseguite su Gemini 2.5 Flash. La prima, bulk-reader, legge un lotto di file e risponde con punti elenco strutturati. La seconda, code-writer, genera codice a partire da una specifica e da un file di riferimento di cui deve riprodurre le convenzioni.

Il routing è gestito da un plugin per Claude Code chiamato shunt, dopo il fallimento di una prima versione basata su regole scritte in CLAUDE.md, che il modello poteva ignorare e che andavano copiate in ogni progetto. Il plugin impila tre livelli. Gli hook PreToolUse bloccano le letture di file oltre una soglia di righe configurabile, così come i comandi cat, head o tail su file di grandi dimensioni; le letture mirate passano. Gli script bash incapsulano le chiamate alla Portal CLI, costruiscono la richiesta e riportano indietro l'utilizzo dei token. I file di skill dicono a Claude quando e come chiamare questi script. Il corpus si sposta verso il modello secondario senza mai entrare nel contesto di Claude, che inoltre non vede mai il codice generato, scritto direttamente su disco.

Le misurazioni sono presentate come un risparmio medio di circa il 90% su quattro scenari testati su un monorepo Java, con l'autore che riconosce come lo scenario di generazione sia difficile da misurare. Una sezione dettaglia ciò che non funziona: l'editing non è delegabile per mancanza di numeri di riga affidabili, né lo è il ragionamento — il modello secondario non ha colto un bug di thread-safety che Claude ha individuato immediatamente — e ogni delega costa da dieci a trenta secondi di latenza, il che la rende controproducente su file piccoli.

L'autore conclude che il risparmio di token è solo un punto di partenza: il vero valore delle modalità sta nel trasformare il routing dei modelli in un problema di configurazione piuttosto che di ingegneria dei sistemi.

## GrapheDeConnaissance

- Dimitri Mazmanov —travaille_chez→ Spotify (ORGANISATION, 0.97)
- Dimitri Mazmanov —a_créé→ shunt (TECHNOLOGIE, 0.95)
- Dimitri Mazmanov —affirme_que→ "Most of what an AI coding agent does for me isn't thinking. It's I/O" (CITATION, 0.96)
- Dimitri Mazmanov —affirme_que→ les coûts de codage IA dépasseront le salaire moyen d'un développeur d'ici 2028 (AFFIRMATION, 0.85)
- Dimitri Mazmanov —mesure→ un quart des responsables d'ingénierie dépensent 200-500 $ par développeur et par mois en tokens (MESURE, 0.82)
- Spotify —a_créé→ Portal by Spotify (TECHNOLOGIE, 0.95)
- Portal by Spotify —permet→ AiKA Modes (TECHNOLOGIE, 0.95)
- AiKA Modes —est_instance_de→ agent déclaratif sur runtime éphémère (CONCEPT, 0.92)
- AiKA Modes —utilise→ MCP (TECHNOLOGIE, 0.9)
- AiKA Modes —permet→ routage de modèles (CONCEPT, 0.93)
- routage de modèles —réduit→ consommation de tokens du modèle principal (CONCEPT, 0.92)
- shunt —fait_partie_de→ Claude Code (TECHNOLOGIE, 0.94)
- shunt —utilise→ Portal by Spotify (TECHNOLOGIE, 0.94)
- shunt —utilise→ hooks (TECHNOLOGIE, 0.95)
- shunt —remplace→ règles de routage écrites dans CLAUDE.md (CONCEPT, 0.93)
- Dimitri Mazmanov —affirme_que→ "The rules were advisory, not enforced" (CITATION, 0.93)
- hooks —permet→ blocage des lectures au-delà de 350 lignes par défaut (AFFIRMATION, 0.93)
- bulk-reader —est_instance_de→ AiKA Modes (TECHNOLOGIE, 0.94)
- code-writer —est_instance_de→ AiKA Modes (TECHNOLOGIE, 0.94)
- bulk-reader —utilise→ Gemini 2.5 Flash (TECHNOLOGIE, 0.93)
- code-writer —utilise→ Gemini 2.5 Flash (TECHNOLOGIE, 0.93)
- shunt —mesure→ économie moyenne de ~90 % de tokens sur le scénario bulk-read, monorepo Java, quatre scénarios (MESURE, 0.85)
- shunt —réduit→ occupation de la fenêtre de contexte du modèle principal (CONCEPT, 0.91)
- Dimitri Mazmanov —affirme_que→ le gain sur le scénario code-write est difficile à mesurer en tokens (AFFIRMATION, 0.9)
- routage de modèles —s_oppose_à→ délégation de l'édition de code et du raisonnement (AFFIRMATION, 0.9)
- Gemini 2.5 Flash —s_oppose_à→ détection d'un bug de thread-safety trouvé par Claude Code (AFFIRMATION, 0.86)
- shunt —mesure→ latence de 10 à 30 secondes par délégation, plafond Portal de 30 secondes (MESURE, 0.91)
- Dimitri Mazmanov —recommande→ exclure du routage le débogage, les décisions d'architecture et le code critique (AFFIRMATION, 0.93)
- Dimitri Mazmanov —affirme_que→ "They turn model routing from a systems engineering problem into a configuration problem" (CITATION, 0.93)
- spotify/portal-ai-plugins —publie→ shunt (TECHNOLOGIE, 0.92)

---
Canonical: https://www.thekb.eu/it/fiches/mazmanov-portal-spotify-shunt-claude-code-tokens-2026-09-03/