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

## Veille

Post de ingeniería de **Spotify** publicado el **3 de septiembre de 2026** en engineering.atspotify.com (~1.600 palabras, nueve secciones, dos manifiestos YAML, cuatro ejemplos de línea de comandos), escrito por **Dimitri Mazmanov**, Principal Product Manager. Describe una configuración personal diseñada para sacar las tareas de E/S del contexto de **Claude Code**. La premisa planteada de entrada: *« Most of what an AI coding agent does for me isn't thinking. It's I/O »* — leer cinco archivos para responder a una pregunta sobre un único método, producir una prueba modelada sobre las otras veinte del directorio. **(A) Los modos.** **Portal by Spotify** expone *AiKA Modes*, agentes declarativos sobre un runtime efímero — instrucciones, modelo, temperatura, herramientas **MCP** — comparados con *« AWS Lambda, but for agents »*; dos modos públicos, `bulk-reader` y `code-writer`, se ejecutan aquí sobre **Gemini 2.5 Flash**. **(B) El enrutamiento.** Un plugin de Claude Code llamado `shunt` sustituye las reglas de `CLAUDE.md`, consideradas *« advisory, not enforced »*, por tres capas: hooks `PreToolUse` que bloquean cualquier lectura más allá de **350 líneas** (umbral ajustable mediante `SHUNT_MIN_LINES`), dos scripts bash que llaman a la CLI de Portal, dos skills que proporcionan la sintaxis de invocación. El corpus pasa al modelo secundario y **nunca entra en el contexto de Claude**. **(C) Mediciones y sus límites.** En un monorepo Java, cuatro escenarios, el ahorro medio declarado es de **~90%** en `bulk-read`; el autor señala que el escenario `code-write` es *« harder to measure »*, y enumera tres limitaciones — edición no delegable, razonamiento no delegable, **10 a 30 segundos** de latencia por llamada. Prolonga las cuestiones de presupuesto de [[gupta-token-budget-wars-marginal-token-utility-2026-05-28]] y la delegación examinada en [[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

**Perfil**: un relato de experiencia individual publicado en un blog de ingeniería corporativo, en primera persona, que es a la vez una promoción abiertamente reconocida de un producto interno. Público: usuarios avanzados de agentes de codificación y responsables de plataforma interna.

**Estilo**: el texto sigue una progresión de demostración técnica — problema cuantificado, solución, arquitectura por capas numeradas, mediciones, limitaciones, instrucciones de uso. Los artefactos se dan íntegros: dos manifiestos YAML completos, cuatro invocaciones de línea de comandos, la variable de entorno del umbral, los tres comandos de instalación. Los detalles de implementación se exponen en lugar de resumirse, incluidas microdecisiones y su justificación — la instrucción *« output only the code »* se justifica por los bloques markdown que Claude tendría que analizar de otro modo, el archivo de referencia obligatorio por el código fuera de contexto que un modelo produciría sin él.

**Posición epistémica**: el título muestra un resultado cuantificado, pero el cuerpo lo acota él mismo. Una sección entera, *« What doesn't work »*, enumera lo que la configuración no hace: sin edición delegada por falta de números de línea fiables, sin razonamiento delegado — un error de *thread-safety* pasado por alto por el modelo secundario, detectado por Claude —, y una sobrecarga de latencia que hace la delegación contraproducente por debajo del umbral. La medición en sí sigue siendo declarativa: cuatro escenarios sobre un monorepo Java, sin protocolo publicado, sin volúmenes absolutos, sin contabilizar el coste del modelo secundario. La sección final desplaza explícitamente el foco de la cifra a la reutilizabilidad de los modos, formulada como *« they turn model routing from a systems engineering problem into a configuration problem »*.

## Pense-betes

- **La intuición de partida es el reparto de carga, no la optimización de prompts.** Leer archivos y generar código repetitivo consume tokens sin requerir razonamiento; estas tareas van a un modelo barato, mientras que el modelo principal conserva los problemas que exigen juicio.
- **Lo que se ahorra no es solo el precio, es la ocupación del contexto.** El corpus que se lee se envía al modelo secundario y nunca entra en la ventana de Claude; una consulta posterior sobre los mismos archivos por tanto no recarga nada del lado principal. Mismo mecanismo que la delegación a subagentes en [[willison-fable-judgement-delegation-subagents-2026-07-03]].
- **Un modo = un agente declarativo**: nombre, descripción, instrucciones, modelo, `visibility`, `resourceLimits`, `tags`. Runtime efímero, nada almacenado en el servidor, ninguna clave de API que gestionar. Resolución por nombre, sin distinción de mayúsculas, con precedencia personal → equipo → público: basta con bifurcar un modo público para sobrescribirlo sin configuración.
- **Las reglas en `CLAUDE.md` no se sostuvieron.** Primera versión del enrutamiento: un bloque de instrucciones que Claude leía y a veces seguía. Dos fallos señalados — *advisory, not enforced*, y tener que copiarse en cada proyecto. Este es el argumento que impulsa el paso a hooks, puertas estrictas independientes de la decisión del modelo.
- **El umbral es el parámetro de ajuste central.** `check-file-size` bloquea las llamadas `Read` más allá de 350 líneas por defecto; `check-bash-read` intercepta `cat`, `head`, `tail`, `less`, `more`. Las lecturas puntuales (`offset`/`limit`) y los comandos encadenados pasan sin problema. Por debajo del umbral, la latencia de delegación cuesta más de lo que ahorra.
- **La degradación controlada es el punto arquitectónico.** Tres capas: el hook bloquea, el script ejecuta, el skill explica. Si Claude ignora el skill, el hook sigue bloqueando — el contrato no se confía al modelo.
- **Dos instrucciones de modo hacen la mayor parte del trabajo.** *Output only the code* evita los bloques markdown y la prosa que el modelo principal tendría que volver a analizar; un archivo de referencia obligatorio para `code-writer` evita el código fuera de contexto. Misma lógica de encuadre que los skills descritos en [[shihipar-claude-code-lessons-building-skills-2026-06-03]].
- ⚠️ **La cifra destacada es autodeclarada y no reproducible tal cual se presenta**: una media en cuatro escenarios sobre un monorepo Java, sin protocolo, sin volúmenes absolutos, sin comparación con un modelo principal usado con lecturas puntuales. El autor admite que el escenario `code-write` es más difícil de medir, y el coste del modelo secundario no se resta.
- **Las tres limitaciones reconocidas delimitan el alcance**: sin edición delegada (números de línea de los resúmenes poco fiables), sin razonamiento delegado (depuración, decisiones de arquitectura y código crítico explícitamente excluidos del enrutamiento), 10 a 30 s de latencia por ida y vuelta, con un límite de 30 s en Portal que obliga a dividir las generaciones grandes.
- **La conclusión operativa trata de los modos, no del plugin**: reutilizables entre proyectos, compartibles (ambos modos son públicos), componibles (`doc-writer`, `reviewer`, `translator` citados como posibles extensiones), y desacoplados del enrutamiento — cambiar el modelo de trabajo no cambia el plugin. Esta separación entre empaquetado y ejecución es la formalizada por [[google-agent-plugins-packaging-skills-mcp-2026-08-06]].
- **Instalación**: `claude plugin marketplace add spotify/portal-ai-plugins`, luego los plugins `portal` (la CLI) y `shunt` (enrutamiento), después `/portal:setup` para la autenticación contra una instancia de Portal. La configuración por tanto presupone una instancia de Portal con el plugin AiKA habilitado — no es trasladable tal cual fuera de una organización que lo ejecute.
- **Las cifras de contexto proceden de fuera del post y no están referenciadas**: costes de IA de codificación que superan el salario medio de un desarrollador en 2028, una cuarta parte de los responsables de ingeniería entre 200 y 500 dólares por desarrollador al mes, algunos por encima de 2.000. Deben tratarse como un orden de magnitud, que vale la pena comparar con las mediciones por equipo de [[patel-block-buzz-teams-tokens-benchmarks-2026-08-06]].

## RésuméDe400mots

Dimitri Mazmanov, Principal Product Manager en Spotify, publicó el 3 de septiembre de 2026 en el blog de ingeniería de la empresa un relato de una configuración que, según sus datos, reduce en un 90% su consumo de tokens en Claude Code. Su observación de partida: la mayor parte de lo que un agente de codificación hace por él no es razonamiento sino E/S — leer cinco archivos para responder a una pregunta sobre un método, generar un archivo de prueba idéntico a los veinte vecinos. Este trabajo se envía a un modelo de frontera sobrecualificado, cuando un modelo barato lo gestionaría igual de bien.

La solución se basa en los AiKA Modes de Portal by Spotify: agentes declarativos ejecutados en un runtime efímero, definidos por instrucciones, un modelo, parámetros y herramientas MCP, sin infraestructura ni claves de API que gestionar. El autor crea dos modos públicos que se ejecutan sobre Gemini 2.5 Flash. El primero, bulk-reader, lee un lote de archivos y responde en viñetas estructuradas. El segundo, code-writer, genera código a partir de una especificación y un archivo de referencia cuyas convenciones debe reproducir.

El enrutamiento lo gestiona un plugin de Claude Code llamado shunt, tras el fracaso de una primera versión basada en reglas escritas en CLAUDE.md, que el modelo podía ignorar y que había que copiar en cada proyecto. El plugin apila tres capas. Los hooks PreToolUse bloquean las lecturas de archivos más allá de un umbral de líneas configurable, así como los comandos cat, head o tail sobre archivos grandes; las lecturas puntuales pasan sin problema. Los scripts bash envuelven las llamadas a la CLI de Portal, construyen la solicitud y reportan el uso de tokens. Los archivos de skill indican a Claude cuándo y cómo llamar a estos scripts. El corpus se traslada al modelo secundario sin entrar nunca en el contexto de Claude, que tampoco ve nunca el código generado, escrito directamente en disco.

Las mediciones se presentan como un ahorro medio de alrededor del 90% en cuatro escenarios probados contra un monorepo Java, y el autor reconoce que el escenario de generación es difícil de medir. Una sección detalla lo que no funciona: la edición no es delegable por falta de números de línea fiables, tampoco lo es el razonamiento — el modelo secundario pasó por alto un error de thread-safety que Claude detectó de inmediato —, y cada delegación cuesta de diez a treinta segundos de latencia, lo que la hace contraproducente en archivos pequeños.

El autor concluye que el ahorro de tokens es solo un punto de partida: el valor real de los modos es convertir el enrutamiento de modelos en un problema de configuración en lugar de uno de ingeniería de sistemas.

## 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/es/fiches/mazmanov-portal-spotify-shunt-claude-code-tokens-2026-09-03/