💡 О чём гайд
Когда AI-агент растёт, его системный промпт становится толстым (400+ строк), инструменты — лишние, эвалы падают. Рефакторинг через три столпа — skills вместо промпта, базовые инструменты вместо кастомных, и редкие sub-agenty — снижает код до 15 строк и повышает успешность с 62% до 92%. Hill climbing по эвалам — единственный способ измерить улучшение.
Когда AI-агент растёт (как Stock Pilot — система управления складом), он неизбежно сталкивается с типовыми проблемами роста:
Системный промпт разбухает до 400+ строк — каждый новый бизнес-процесс добавляется прямо в контекст
Инструментов становится 12 штук, из них 3 — это просто обёртки над отдельными агентами
Успешность эвалов падает: с ожидаемых 92% до реальных 62–83%
Примеры провалов эвалов
Анализ failures показывает три класса проблем:
F1 (ежедневная проверка остатков). Агент достигает цели, но идёт извилистым, неэффективным путём с множеством лишних запросов
F2 (обработка заказов на продажу). Разрыв коммуникации между оркестратором и sub-agent'ом — информация теряется или неправильно парсится
R8 (прогноз спроса на промо-месяц). Конфликт политик в разных секциях промпта: агент использует множитель 1,35 вместо правильного 3,1× — противоречивые инструкции в одном большом тексте
Важно: Проблема не в самом Claude — он работает правильно. Виноват дизайн: слишком много информации в системном промпте, без разделения ответственности.
Метод: Hill Climbing по эвалам
Систематический путь к улучшению архитектуры:
Запустите эвалы — зафиксируйте базовую метрику (например, 62% успешности)
Проанализируйте failures — Claude поможет найти корневую причину в каждом провале (промпт, инструменты, оркестрация)
Перезапустите эвалы — измерьте метрику улучшения (например, 75%, потом 85%)
Повторяйте — цикл продолжается, пока не достигнете целевых показателей
Совет: Эвалы — это компас. Без них вы гадаете. Каждое изменение архитектуры должно быть валидировано эвалами, а не субъективным ощущением «выглядит лучше».
Три столпа модернизации архитектуры
1. Skills вместо гигантского промпта
Что такое skill? Это упакованная, переиспользуемая единица информации, которую Claude подгружает в контекст только когда она нужна для конкретной задачи.
Проблема сейчас: Все бизнес-процессы (политики, процедуры, правила) запекаются в системный промпт. Это загрязняет контекст постоянно, даже когда информация не нужна.
Решение: Вынесите специфичную логику (например, правила прогноза спроса, ценообразования, утверждения заказов) в отдельные skills. Системный промпт оставляет только то, что нужно всегда.
Результат в Stock Pilot:
Промпт сократился с ~400 до ~50 строк
Каждый skill — отдельный файл, легко обновлять и версионировать
При обращении к конкретной задаче (например, прогноз) агент получает только релевантный skill
Философия: Дайте агенту те же примитивы, которые есть у человека за компьютером.
Вместо создания десятка специальных инструментов (parse_csv, query_inventory, generate_report) агент получает три базовых:
bash — выполнение команд, вызовы API, обработка данных
file I/O — чтение и запись файлов
web search — поиск информации (если необходимо)
Пример из Stock Pilot: Вместо инструмента analyze_csv_by_category агент теперь сам пишет Python-скрипты для анализа CSV. Это:
Сократило использование токенов с >200K до минимума
Снизило стоимость
Повысило гибкость (агент может анализировать данные так, как нужно конкретно сейчас)
Когда добавлять кастомный инструмент? Только когда примитивы недостаточны. Например, если агенту нужно вызвать закрытый API с auth, не очень удобно делать в bash — тогда создавайте инструмент.
MCP note: MCP-сервер подключайте только если инструментарий общий для многих агентов/клиентов. Часто код через bash гибче и дешевле.
3. Conscious Sub-agents (осознанное использование агентов-помощников)
Sub-agents нужны в двух случаях:
Параллелизация. Когда у вас много независимых тяжёлых задач и нужно бросить много инстансов Claude на решение одновременно (например, глубокий анализ или code review множества файлов)
Разделение ответственности. Когда полезно разделить создание и проверку (один агент пишет, другой критически разбирает) — это даёт свежий взгляд
Проблемы sub-agents: Сложная оркестрация, логирование и observability, синхронизация, дополнительные затраты на токены.
CMA (Claude Managed Agents) спасает положение: Native callable agents дают централизованный observability и управление жизненным циклом.
В Stock Pilot: Оставлен только один sub-agent для прогнозирования спроса — он изолирован в своём контексте, что позволило чистой изолировать эту сложную логику от основного агента.
Избегайте: Создавать sub-agents для каждой мелкой операции — это усложнит систему без выигрыша. Используйте их разумно.
Оркестратор на Claude Managed Agents (никакой инфраструктуры, масштабирование на платформе Anthropic)
Инструменты: 3 примитива (bash, read, write)
Системный промпт: 15 строк
Бизнес-логика: перенесена в skills
Успешность эвалов: 92%
Ключевые улучшения
Сокращение кода: 400 → 15 строк в промпте (26× меньше)
Уменьшение инструментов: 12 → 3 (4× проще)
Рост качества: 62–83% → 92% (стабильный, предсказуемый результат)
Снижение токенов и стоимости: Меньше контекста = меньше токенов = дешевле
Проще поддержка: Когда требование меняется, обновляете skill или промпт, а не переделываете весь агент
Выше продуктивность: Агент работает эффективнее, меньше витков, проще гарантировать результат
Результат достигнут: Stock Pilot из медленного, ненадёжного монолита превратился в стройную, расширяемую систему — и это возможно для любого агента, который перерос свою архитектуру.
Практический путеводитель по рефакторингу
Признаки, что ваш агент пора рефакторить
Системный промпт превышает 100 строк — начинается накопление технического долга
Эвалы показывают деградацию: успешность падает с версии на версию
Агент требует 5+ витков для решения простой задачи
Сложно добавить новую функцию без риска сломать старую
Токен-юз неожиданно вырос, хотя логика не менялась
Пошаговый план действий
Запишите эвалы. Сегодня запустите текущие эвалы, зафиксируйте базовую метрику — это ваш нулевой килограмм
Выделите skills. Проходите промпт, отмечайте блоки логики (политики, процедуры), вынесите их в отдельные skill-файлы
Упростите инструменты. Замените custom tools на bash/read/write где возможно
Переделайте sub-agents. Оставьте только те, которые дают параллелизацию или чистое разделение ответственности
Перезапустите эвалы. Проверьте улучшение — должна быть положительная дельта
Iterate. Если улучшение есть, но не целевое — снова анализируйте failures и повторяйте
Инструмент помощи: Claude в режиме analysis может помочь вам разобраться в failures эвалов и предложить, какой именно skill создать или какой инструмент упростить. Дайте ему failure-сценарий и промпт агента — он найдёт узкие места.
Понравился разбор?
В канале «ИИ для чайников» — новый гайд каждый день
Bloated agents are inevitable as requirements grow, but they're fixable. Use skills to keep prompts lean, start with primitives and add tools only when needed, and deploy subagents consciously. Most importantly, write evals and use hill climbing to measure every improvement. Claude Managed Agents removes infrastructure burden so you can focus on agent design itself.
Часто задаваемые вопросы
Когда системный промпт превышает 100 строк, вы накапливаете технический долг. Если эвалы показывают падение успешности или агент требует множества витков для простых задач, пора рефакторить. Используйте эвалы для измерения деградации и hill climbing для итеративного улучшения.
Используйте skills для бизнес-логики, политик и процедур, которые нужны не всегда. Системный промпт должен быть лёгким — только для кор-поведения агента. Это сокращает загрязнение контекста и снижает затраты на токены на 60%.
Sub-agenty нужны для параллелизации независимых задач или разделения ответственности (один создаёт, другой проверяет). Для простых одношаговых операций используйте инструменты. Sub-agenty добавляют оркестрационные сложности, избегайте их для несложных задач.
Запустите эвалы до и после рефакторинга. Отслеживайте success rate, token usage и latency. Hill climbing — это цикл: измерь → анализируй → улучшай → перемеряй. Эвалы — единственный источник истины, не полагайтесь на субъективные впечатления.
Скачать гайд
Полная версия с примерами и подробными инструкциями.
