Две режима, без кода

Для реализации маршрутизации идеально подходят AiKA Modes в Portal от Spotify. Режим — это декларативный агент, работающий на эфемерном runtime (как AWS Lambda, но для агентов). Определяются инструкции, выбирается модель, устанавливаются параметры вроде temperature и привязываются MCP инструменты. Portal берёт остальное на себя. Никакой инфраструктуры, никаких API ключей, никаких long-running серверов. Режимы вызываются из Portal CLI или API. Могут быть публичными (доступны всей компании) или приватными.

Для работы этого маршрутизатора создано два режима. Оба используют Gemini 2.5 Flash как рабочую модель, но поле model принимает любую модель, настроенную в Portal инстансе.

Режим 1: bulk-reader

Для случаев, когда Claude иначе читал бы несколько больших файлов просто для ответа на один вопрос.

name: bulk-reader

description: Bulk file reader for code analysis - delegates I/O from Claude Code
instructions: You are a precise code analyst. Read the provided files and answer the question concisely. Output structured bullets only. No greetings, no prose, no preambles. Lead every bullet with the exact name, type, or line number. Use nested bullets for details. Skip anything the caller did not ask for.

visibility: public

model: gemini-2.5-flash

resourceLimits:
  temperature: 0.2

tags:
  - coding
  - delegation

Режим 2: code-writer

Для тестов, конфигов, type stubs — всего, где output предсказуем из существующих паттернов.

name: code-writer

description: Boilerplate code generator - delegates output-heavy work from Claude Code

instructions: You generate code files based on a spec and reference files. Match the existing patterns, conventions, naming, and style exactly. Output only the code — no explanations, no markdown fences unless asked. If the spec is ambiguous, make reasonable choices that match the reference code's patterns.

visibility: public

model: gemini-2.5-flash

resourceLimits:
  temperature: 0.2

tags:
  - coding
  - delegation

Инструкция «output only the code» критична. Без неё модель оборачивает всё в markdown fences и пояснительный текст, который Claude потом должен парсить.

Маршрутизация

Первая версия — это блок правил в CLAUDE.md. Работала: Claude читал инструкции и самостоятельно маршрутизировал в Portal. Но были проблемы. Правила не обязательны — Claude мог их игнорировать. И каждый проект нуждался в своей копии инструкций.

Текущая версия — это Claude Code плагин shunt. Делегирование проходит через Portal CLI actions registry, поэтому плагин работает с любым Portal инстансом с включённым AiKA плагином.

Слой 1: Hooks

Claude Code hooks срабатывают перед каждым tool call. Shunt регистрирует два PreToolUse hook:

check-file-size срабатывает на каждом Read. Если файл превышает настраиваемый лимит строк (по умолчанию: 350), hook блокирует чтение и указывает Claude использовать /bulk-reader skill. Целевые чтения проходят — Claude уже знает нужное ему место.

check-bash-read ловит cat, head, tail, less и more на больших файлах. Piped команды (cat file | grep) проходят, так как это целевые чтения.

Лимит настраивается через переменную окружения SHUNT_MIN_LINES. Установить в профиль шелла или .claude/settings.json:

{
  "env": {
    "SHUNT_MIN_LINES": "500"       
  }
}

Слой 2: Scripts

Два bash скрипта оборачивают вызовы Portal CLI. Claude вызывает скрипт с именованными параметрами. Скрипты обрабатывают всё внутри: построение запроса, вызов actions, распаковка ошибок и отчёт об использовании токенов в stderr.

Режимы адресуются по имени и резолвятся Portal: case-insensitively, сначала ищутся личные, потом командные, потом публичные. Fork публичного bulk-reader в кастомизированную версию — твоя автоматически берёт приоритет, никакой конфигурации не нужно.

bulk-read оборачивает каждый файл в XML теги для чётких границ и отправляет их в bulk-reader режим с вопросом.

bulk-read --question "What does this service do?" --paths src/Service.java src/Handler.java

# Follow-up: ask again with the same paths

bulk-read --question "Which methods call the database?" --paths src/Service.java src/Handler.java

Каждая делегирование — одноразовое. Вызов эфемерный (ничего не хранится на сервере) и повторная отправка файлов бесплатна там, где это важно: corpus идёт рабочей модели и никогда не входит в контекст Claude.

code-write отправляет spec и reference файл в code-writer режим, убирает markdown fences из output и может писать прямо на диск. Claude никогда не видит сгенерированный код. Reference обязателен: без файла для match паттернов, worker генерировал бы контекст-free код, который никуда не подходит.

code-write --spec "Write tests for UserService" --reference tests/OrderTest.java --target tests/UserTest.java

# Output to stdout

code-write --spec "Generate a config stub" --reference config/existing.yaml

Слой 3: Skills

Два skill файла рассказывают Claude когда и как вызывать скрипты. Skills — это markdown файлы с описанием и примерами использования. Когда hook блокирует чтение, сообщение о блокировке указывает Claude на /bulk-reader skill, который показывает точный синтаксис вызова.

Такая слоистость означает graceful деградацию. Даже если Claude не прочитает description skill, hook всё равно заблокирует дорогое чтение. Skill просто делает редирект более гладким.

Бенчмарки

Тестирование на Java монорепо в четырёх сценариях, измеряя токены, которые Claude потреблял бы при прямом чтении файлов, против токенов bulk-reader summary или написания кода через code-writer. Среднее сохранение bulk-read — примерно 90%.

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

Что не работает

Нельзя делегировать редактирование. Summaries рабочей модели не включают надёжные номера строк. Если Claude нужно сделать правки на основе анализа, всё равно приходится читать конкретный раздел напрямую. Hooks позволяют целевые чтения (с offset/limit) именно для этого, поэтому делегирование экономит токены на понимание.

Нельзя делегировать reasoning. Рабочая модель нашла паттерны поверхностного уровня, но пропустила тонкий thread-safety баг при тестировании. Claude обнаружил его за секунды с нужным контекстом. Маршрутизация явно исключает debugging, архитектурные решения и safety-critical код.

Latency складывается. Каждое делегирование — сетевой round-trip: Claude Code → Portal backend → рабочая модель и обратно. Ответы обычно занимают 10–30 секунд, и Portal ограничивает single invocation 30 секундами, поэтому большие генерации нужно разбивать на меньшие вызовы. Приемлемо для больших чтений, но контрпродуктивно для маленьких. Лимит строк существует именно для этого — ниже него overhead делегирования превышает сбережения.

Сокращение токенов — только начало

Плагин — это Claude Code артефакт, но идея под ним — model routing через AiKA modes. Modes — это load-bearing piece:

  • Переиспользуемы. Один и тот же bulk-reader и code-writer режимы работают во всех проектах и с любым инструментом, что может shell out в Portal CLI.

  • Shareable. Оба режима публичны в AiKA. Любой может использовать их сегодня без создания своих.

  • Composable. Можно создать doc-writer режим для документации, reviewer режим для code review summaries, translator режим для i18n. Каждый — в нескольких кликах.

  • Decoupling решения по маршрутизации от worker. Плагин решает когда делегировать. Режим решает как ответить. Swap Gemini Flash на более дешевую модель, измени system prompt, добавь MCP инструменты — плагин не меняется.

Это реальная мощь AiKA modes: они превращают model routing из systems engineering проблемы в configuration проблему. Не нужно строить инфраструктуру. Описываешь, что хочешь, и называешь это.

Попробуй сам

  1. Установи оба плагина из spotify/portal-ai-plugins marketplace:

    1. claude plugin marketplace add spotify/portal-ai-plugins

    2. claude plugin install portal@portal

    3. claude plugin install shunt@portal

  2. Portal плагин предоставляет Portal CLI, через который shunt делегирует.

  3. В новой Claude Code сессии запусти /portal:setup для установки и аутентификации Portal CLI против твоего Portal инстанса.

  4. Готово, просто задай вопрос, что охватывает несколько файлов.

Режимы bulk-reader и code-writer уже публичны, поэтому создавать нечего. Если хочешь их кастомизировать — другую рабочую модель, другие инструкции — fork их в Portal и твоя версия автоматически берёт приоритет.

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