Portal by Spotify уводит чтение файлов из Claude Code

Автор поста в инженерном блоге Spotify от 4 сентября собрал для Claude Code плагин shunt. Плагин отдаёт чтение больших файлов и генерацию шаблонного кода дешёвой модели, а на чтении, по его замерам, экономит в среднем около 90% токенов.

Важнее всего здесь то, как устроена маршрутизация. Claude не просят по-хорошему делегировать работу: хук запрещает ему читать большой файл напрямую, а саму работу выполняет декларативный агент в Portal by Spotify, у которого есть имя, системный промпт и выбранная модель.

Исходная мысль автора простая: «Большая часть того, что агент для кодинга делает для меня, - не мышление. Это ввод-вывод». Он приводит примеры: прочитать пять файлов ради вопроса об одном методе, написать тестовый файл по тому же шаблону, что и двадцать соседних, обновить документацию после встречи. Тысячи токенов уходят на работу почти без рассуждений, причём её делает frontier-модель с огромным запасом квалификации. «Больно бьёт не лицензия, а токены», - пишет автор. По его словам, к 2028 году расходы на ИИ-разработку превысят среднюю зарплату разработчика, четверть руководителей инженерных команд уже тратит на токены 200-500 долларов в месяц на разработчика, а у некоторых выходит больше 2 000.

Что такое режим AiKA

AiKA Spotify начинала как ИИ-ассистента по внутренним знаниям для собственных команд, а затем сделала его чат-плагином для Portal, доступным любым инженерным организациям. Режим (mode) AiKA - декларативный агент, который запускается в эфемерной среде. Автор сравнивает его с AWS Lambda, только для агентов. Вы задаёте инструкции, выбираете модель, выставляете параметры вроде температуры и подключаете MCP-инструменты, а запуск берёт на себя Portal. Инфраструктуры, API-ключей и постоянно работающих серверов нет. Режим вызывается из Portal CLI или через API и бывает публичным, на всю компанию, или приватным.

Для маршрутизатора автор завёл два режима. Оба в примерах работают на Gemini 2.5 Flash с температурой 0,2, но в поле модели можно указать любую модель, настроенную в вашем экземпляре Portal.

• bulk-reader читает присланные файлы и отвечает на вопрос. Инструкция требует только структурированных пунктов, без приветствий, прозы и вступлений, и каждый пункт должен начинаться с точного имени, типа или номера строки.
• code-writer пишет тесты, заготовки конфигов, заглушки типов и всё, что предсказуемо выводится из существующих шаблонов. Ему велено точно повторять соглашения, именование и стиль референсного кода и выдавать только код.

Последнее требование автор отдельно объясняет: без него модель заворачивает результат в markdown-блоки и пояснения, которые Claude потом приходится разбирать.

Как shunt перехватывает чтение

Первая версия маршрутизации жила блоком правил в CLAUDE.md. Claude читал инструкции и сам отправлял задачи в Portal, но правила оставались рекомендацией: модель могла их проигнорировать, а в каждый проект приходилось копировать их заново. Нынешняя версия оформлена плагином и делегирует работу через реестр действий Portal CLI, поэтому работает с любым экземпляром Portal, где включён плагин AiKA. Слоёв у неё три.

Первый слой - хуки. По документации Claude Code, хук PreToolUse срабатывает на запрос вызова инструмента, получает его входные данные и может вернуть permissionDecision: "deny", после чего вызов не выполняется. Shunt регистрирует два таких хука. check-file-size срабатывает на каждый Read: если в файле больше строк, чем задано порогом (по умолчанию 350), чтение блокируется, и Claude получает указание воспользоваться навыком /bulk-reader. Точечные чтения с offset и limit проходят, ведь в этом случае Claude уже знает, какой фрагмент ему нужен. check-bash-read ловит cat, head, tail, less и more на больших файлах, а команды с пайпом вроде cat file | grep пропускает как точечные. Порог меняется переменной SHUNT_MIN_LINES в профиле шелла или в .claude/settings.json.

Второй слой - два bash-скрипта вокруг Portal CLI. Claude вызывает их с именованными аргументами, а скрипты сами собирают запрос, вызывают действие, разворачивают ошибки и пишут расход токенов в stderr. bulk-read оборачивает каждый файл в XML-теги, чтобы границы были явными, и отправляет их режиму вместе с вопросом. Каждый вызов одноразовый, на сервере ничего не сохраняется, и на уточняющий вопрос файлы отправляются заново. Для Claude это бесплатно: корпус уходит рабочей модели и в его контекст не попадает.

code-write отправляет режиму спецификацию и референсный файл, срезает из ответа markdown-обёртку и может сразу записать результат на диск, так что сгенерированного кода Claude не видит. Референс обязателен: без файла-образца, говорит автор, рабочая модель выдала бы код вне контекста, который ни к чему в проекте не подходит.

Режимы вызываются по имени, а Portal ищет их без учёта регистра: сначала ваш собственный, затем командный, затем публичный. Если форкнуть публичный bulk-reader и поправить его под себя, ваша версия автоматически получит приоритет без какой-либо настройки.

Третий слой - навыки, два markdown-файла с описанием и примерами вызова. Сообщение о блокировке отсылает Claude к /bulk-reader, где показан точный синтаксис. Если Claude не прочитает описание навыка, хук всё равно не пустит дорогое чтение, а навык лишь сглаживает переадресацию.

Откуда 90%

Замер шёл на Java-монорепозитории в четырёх сценариях: сравнивали, сколько токенов Claude потратил бы на прямое чтение файлов и сколько на сводку от bulk-reader или на работу через code-writer. Около 90% - это средняя экономия на чтении, причём всего по четырём сценариям на одном репозитории.

Для генерации кода автор числа не приводит и объясняет, почему её сложнее измерить в токенах. Без shunt Claude сначала читает референсные файлы, а потом пишет результат выходными токенами, а вывод в Claude Code стоит примерно в 5 раз дороже ввода, как разбирали в августе в блоге Anthropic. С shunt код уходит прямо на диск, и Claude его не видит.

Чего делегировать нельзя?

Редактирование. В сводках рабочей модели нет надёжных номеров строк, поэтому для правки Claude всё равно читает нужный фрагмент сам. Ради этого хуки и пропускают чтения с offset и limit, а экономия приходится на этап понимания кода.

Рассуждения. В тестах автора рабочая модель нашла поверхностные закономерности, но пропустила тонкую ошибку потокобезопасности, которую Claude заметил за секунды, когда получил нужный контекст. Поэтому отладка, архитектурные решения и код, критичный для безопасности, явно исключены из маршрутизации.

Задержки тоже копятся. Каждое делегирование - это сетевой круг от Claude Code до бэкенда Portal, рабочей модели и обратно. Ответ обычно приходит за 10-30 секунд, а один вызов Portal обрывает на 30 секундах, так что большие генерации приходится дробить на несколько вызовов. Для крупных чтений автор считает такую задержку приемлемой, для мелких она вредит, и порог по строкам введён именно поэтому: ниже него накладные расходы делегирования съедают экономию.

Плагин отдельно, режим отдельно

Shunt сделан под Claude Code, но несущая часть конструкции, по словам автора, - режимы. Те же bulk-reader и code-writer работают в любом проекте и с любым инструментом, который умеет вызвать Portal CLI из шелла. Плагин решает, когда делегировать, а режим решает, как отвечать. Можно заменить Gemini Flash на модель подешевле, переписать системный промпт или добавить MCP-инструменты, и плагин при этом не меняется. Автор предлагает по той же схеме завести режимы doc-writer для документации, reviewer для сводок код-ревью и translator для локализации. Главное он формулирует так: режимы «превращают маршрутизацию моделей из задачи системной инженерии в задачу конфигурации».

Оба режима уже публичные, создавать ничего не нужно. Плагины ставятся из маркетплейса командами claude plugin marketplace add spotify/portal-ai-plugins, claude plugin install portal@portal и claude plugin install shunt@portal. Плагин portal даёт Portal CLI, через который работает shunt. В новой сессии Claude Code команда /portal:setup настраивает CLI и проводит аутентификацию в вашем экземпляре Portal, а дальше остаётся задать вопрос, который затрагивает несколько файлов.