ИИ‑агенты для разработчиков: от простых команд до оркестрации субагентов

Привет, Хабр! В процессе работы как-то так получилось, что я занимаюсь просвещением коллег по работе с ИИ-агентами. Помогаю наладить процессы, сценарии использования, помогаю оптимизировать, пишу внутренний тулинг для агентской инфраструктуры. Накопил некоторый опыт об основных сложностях, которые испытывают мои коллеги при начале работы с Claude Code и другими агентами.

Статья ориентирована на разработчиков, но базовые принципы универсальны. Будет полезна тем, кто ещё не работает с агентами или только начал.

Данная статья написана без использования ИИ (какая ирония). Сгенерированных картинок не будет. Только ламповые мемы. И то чуть-чуть.

Давайте для начала определимся с терминологией, чтобы не путаться.

Агент — ИИ ассистент для разработки. Claude Code, OpenCode, Gemini CLI etc.
Сущности — общее название для команд, навыков(skills) и субагентов. Потому что инструменты(tools) это немного другое.

Я разделил статью на 3 части.

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

Начнём.

Основные сущности

Первая проблема, это когда человек начинает пользоваться агентом и пытается выстраивать свой процесс. У него нет понимания, что, когда и как использовать. Обычно с таким лицом:

Хмм... Тут мне нужна команда или скилл? — Хмм… Тут мне нужна команда или скилл?

Поэтому давайте разберёмся, что к чему. По состоянию на сегодня у агентов есть три основные сущности (да, есть ещё хуки, MCP, LSP, ACP и прочие, но эти три 80% потребностей закроют).

Команды (Commands)
Навыки (Skills)
Субагенты (Subagents)

Для меня на первых порах было тоже непонятно, когда мне нужен skill, а когда не нужен. Зачем субагенты, если вот же всё работает в основной сессии! Давайте теперь я детально расскажу про каждый.

Команды (Commands)

Команды — это явные, переиспользуемые промпты, которые вы вызываете по необходимости. Это сущности с минимальным количеством магии. Команда представляет собой Markdown файл. Для создания команды достаточно создать markdown файла в установленном агентом формате и месте. Команды могут быть глобальные и локальные. Куда положить решать вам в зависимости от контекста и задач. Тут логика предельно простая, команда нужна в большинстве сессий — в глобальное пространство, если нет в локальную папку. У разных агентов может быть по-разному. Но в каскадный подход к конфигурации, как в Linux.

Команда состоит из заголовка и тела. Заголовок содержит описание другие опции, которые могут варьироваться от агента к агенту. Описание служит для отображения в интерфейсе как подсказка. Помимо описания в заголовке есть поля, которые позволяют контролировать различные параметры. К примеру, в OpenCode можно задать модель, которая будет обрабатывать команду и субагента. Выбор модели поможет сохранить драгоценные лимиты. Нет никакого смысла запускать тесты, используя Opus 4.7, с этим справиться Haiku или локально запущенная модель. А обновление большого объёма документации можно поручить моделям с большим контекстным окном, вроде Gemini. Пример заголовка из документации OpenCode:

---description: Run tests with coverageagent: buildmodel: anthropic/claude-3-5-sonnet-20241022---

Тело команды — это непосредственно промпт. Тут всё максимально прямолинейно. Описываете, что должен сделать ваш агент.

Команды могут принимать аргументы через специальные переменные $ARGUMENTS, $1, $2, что делает их удобными для повторяемых процессов разработки. Для примера покажу встроенную команду /review из OpenCode:

You are a code reviewer. Your job is to review code changes and provide actionable feedback.---Input: $ARGUMENTS---## Determining What to ReviewBased on the input provided, determine which type of review to perform:1. **No arguments (default)**: Review all uncommitted changes   - Run: `git diff` for unstaged changes   - Run: `git diff --cached` for staged changes   - Run: `git status --short` to identify untracked (net new) files2. **Commit hash** (40-char SHA or short hash): Review that specific commit   - Run: `git show $ARGUMENTS`3. **Branch name**: Compare current branch to the specified branch   - Run: `git diff $ARGUMENTS...HEAD`4. **PR URL or number** (contains "github.com" or "pull" or looks like a PR number): Review the pull request   - Run: `gh pr view $ARGUMENTS` to get PR context   - Run: `gh pr diff $ARGUMENTS` to get the diffUse best judgement when processing input.---...

Практический совет: группируйте команды по назначению, например, Git, тестирование, генерация кода или начальная настройка проекта, чтобы список команд оставался удобным для навигации. Это достигается путём группировки в папки. Группу команд для работы с Golang можно поместить в папку golang и вызывать, используя разделитель, например, /go:performance-review

Важный момент: команду можно вызвать только вручную. (Не за что, ваш Кэп)

Лучшие практики для команд простые. Опираемся на Single Responsibility. Команда должна делать что-то одно. Например, сделать ревью кода, коммит или проверить уровень покрытия тестами.
Как понять, что нужна команда:

Вы вводите один и тот же промпт постоянно
Вам не надо, чтобы агент мог вызвать эту функциональность самостоятельно
Вам не нужны дополнительные файлы, всё помещается в один markdown файл

Скиллы

Skills — это переиспользуемые модули инструкций, определяемые через файлы SKILL.md и загружаемые по требованию, когда агенту нужны специализированные знания или поведение. И тут обычно у людей появляются вопросики. «Стопэ, а команды разве не про то же самое?». Нет. Команда — это то, что пользователь запускает явно, а Skill — это то, что агент может запустить сам, когда задача того требует. Простыми словами, вы пишите агенту «братюнь, сделай ревью и задеплой» и, при наличии нужных скиллов, он запустит ревью, а потом и деплой.

Для того, чтобы это стало возможным, давайте посмотрим, из чего состоит скилл. Как и в случае с командой это markdown файл SKILL.md. В отличие от команды каждый скилл лежит в своей папке, и для этого есть причины. Скилл помимо основного файла может содержать дополнительный контент. Это могут быть скрипты, шалблоны, изображения, другие markdown файлы. Скилл состоит из заголовка и тела, так же как и команда имеет дополнительные опции для конфигурирования. OpenCode и Claude Code позволяют настраивать права на запись, запуск инструментов, использование других скилов и т. д. Тут нам всем поможет RTFM к выбранному инструменту.

Теперь немного о том, как агент понимает, какой скилл ему вызвать и какую цену мы за это платим. В заголовках файла SKILL.md есть поле description. Это поле загружается в контекст каждой сессии. Когда агента попросили сделать деплой и в списке скиллов находится скилл с примерно таким описанием, то с большой долей вероятности модель вызовет его.

---name: deploy-to-proddescription: Deploy latest tag to productionallowed-tools: Bash---## Check before executionIf today is Friday - REJECT!!!11!1!## What to do- Take latest tag from master barnch- Run !deploy.py {last_tag}...

И всё вроде бы круто, но есть нюанс. Так как никто не мешает нам добавить 100500 скиллов нашему агенту (были случаи), то появляется проблема, при которой агент начинает в них путаться. Что может привести, в лучшем случае, к потере времени, а в худшем к потере данных. Плюс, как мы узнали выше, все описания скиллов загружаются в контекст, а это значит, что мы только открыли сессию, а в контексте уже куча дополнительной информации. Поэтому я не разделяю взгляд прогрессивной общественности в лице Claude Code, которая пушит в сторону скиллов. Вот тут небольшая сноска про этот потрясающий ход.

Как понять, что нужен скилл:

Вам нужно, что бы агент мог запустить его самостоятельно
Для работы нужны дополнительные файлы, шаблоны, картинки и т.д.

Хорошая новость в том, что Anthropic продвигает формат скиллов как универсальный. То есть написав один раз скилл, вы сможете его использовать с разными агентами. В отличие от команд, у которых набор опций отличается от агента к агенту.

Субагенты

Вот перевод определения субагентов с сайта Claude Code:

Субагенты — это специализированные ИИ-ассистенты, которые выполняют конкретные типы задач. Используйте их, когда побочная задача может перегрузить основной диалог результатами поиска, логами или содержимым файлов, к которым вы больше не будете возвращаться: подагент выполняет эту работу в собственном контексте и возвращает только итоговое резюме. Создавайте собственного подагента, если вы регулярно запускаете один и тот же тип исполнителя с одинаковыми инструкциями.

По сути, субагент это такой же markdown-файл с заголовком и телом, как и предыдущие два. Основная задача, которую решает субагент — это изоляция и сохранение контекста. Я сразу объясню на практике. У вас идёт сессия с агентом, где вы пишите код. По мере работы контекст наполняется, а чем больше нерелевантной информации в контексте, тем хуже начинает работать модель и хуже писать код. В процессе работы вам время от времени надо запускать тесты. Если вы будете это делать в основном контексте, то вся эта простыня вывода тестов будет в основном контексте и достаточно быстро ваш контекст забьётся и начнётся деградация. Хотя нам то надо лишь понять там ок или не ок. Если не ок, то нужны только детали упавшего теста. Тут нам и помогут субагенты. При запуске теста субагентом создаётся отдельный контекст, который запустит тесты и вернёт результат.

На этом простом принципе сейчас строятся все модные фреймворки с шизанутым неймингом этих самых субагентов (на тебя смотрю oh-my-opencode). Есть центральный агент-оркестратор, который делегирует работу разным субагентам. Один пишет код, другой тестирует, третий документацию правит и тд.

Просто подытожу. Используйте, когда вам задачу можно\нужно делегировать. Наверное, самая распространённая ментальная модель это относится к ним как к исполнителям. Это видно по тому, как люди называют своих субагентов. Coder, Tester, Manager и тд.

Как создавать свои сущности

Самый лучший способ создать команду, скилл или субагента — это использовать вашего агента для этого. Claude Code в своём маркетплейсе имеет скилл для создания скиллов и команду для создания агентов. Если у вашего агента нет такой функциональности, то попросите его написать её. Без шуток. Напишите скилл для создания скиллов и пишите свои скиллы.

Рабочий процесс (Workflow)

Вторая проблема — это рабочий процесс. Большинство из нас прошло путь копировать\вставить в ChatGPT. Потом был Copilot, который делал автокомплит и Tab-Tab-Tab Driven Development. Потом появился Cursor и я пробовал писать там на Java (ну такое). И вот сейчас у нас агентские системы. Claude Code появился год назад, но многие по привычке общаются с ним как с чатом. Иногда это нормально, если вы хотите погрумить с ЛЛМкой какую нибудь таску. Но когда дело доходит до кода, это не работает. Выглядит это примерно так:

Программист пишет промпт или копирует таску из джиры в чат агенту и почему-то ждёт, что сейчас он всё ему напишет как надо.
Агент собирает в контекст половину проекта, лопатит это 10 минут и выдаёт результат. Иногда даже норм, но часто не очень.
Программист просит переделать то, потом это, потом пятое и десятое. Всё это в одной сессии. Контекст забит битком. И с каждым запросом качество работы модели падает. Именно так появился пласт людей «фигня ваш ИИ».

TLDR: Агенту нужна очень точная спецификация и чётко поставленные задачи. Тогда он работает намного лучше. (Прям как кожаные мешки)

В интернете сейчас каждый встречный поперечный форсит свой фреймворк для работы с агентскими системами. Зачастую они переусложнены. Авторы этих фреймворков выглядят вот так, когда рассказываю, как они работают:

Далее я расскажу, как собрать простой workflow, который создаст чёткую спецификацию и план работ для агента.

Шаг 1: Мозговой штурм (Brainstorm)

Цель данного шага — понять пространство проблемы до того, как принимать решение о конкретной реализации. В разных фреймворках называется по-разному. В speckit от GitHub данный шаг называется specify, например. Но все плюс-минус пришли к необходимости данного шага.

Необходим только для сложных комплексных задач

Наша задача как можно чётче сформулировать запрос к агенту. Агент исследует кодовую базу, определяет затронутые области, выстраивает зависимости и выявляет неизвестные факторы, которые могут повлиять на реализацию. На этом этапе важны вопросы как от нас к агенту, так и от агента к нам. Чем точнее сформулирована задача, тем качественнее будет последующий план. Тут мы больше обсуждаем архитектуру решения и функциональные требования.

Из своего опыта могу сказать, что очень полезно сохранять результат. Это будет артефактом вашей работы с агентом, который потом можно сохранит рядом с проектом. Пусть будет DESIGN.md. Своего рода ADR на минималках, он нам пригодятся для следующего шага. Хотя можно и в той же сессии продолжить. Смотрите по ситуации.

В репозитории Superpowers есть неплохой скилл. Также посмотрите на очень компактный скилл от Matt Pocock. Для ознакомления достаточно.

Шаг 2: Планирование (Planning)

Цель данного шага — превратить понимание задачи в структурированный план выполнения (внезапно).

Необходим в большинстве задач кроме совсем тривиальных

Задача агента — разбить работу на последовательность конкретных шагов с понятными контрольными точками. По сути, это чек лист, по которому дальше будет идти выполнение. На этом этапе критически важно проверить план до начала реализации. Это точка, где мы либо экономим ресурсы, либо сжигаем их впустую. Для планирования лучше использовать модель поумнее, и уровень размышлений(thinking) поставить повыше.

Я лично использую модели уровня Opus или Sonnet, они делают настолько детальный план, что потом его может выпольнить с первого раза даже Haiku.

Результатом должен быть либо сохранённый план, либо утверждённый список шагов, готовый к выполнению. Я рекомендую сохранять такие планы рядом с проектом, имя в простейшем варианте будет PLAN.md. Во-первых, вы всегда сможете поправить его руками. Во-вторых, при имплементации плана вы просто ссылаетесь на него и просите выполнить его шаг за шагом, отмечая выполненные шаги в процессе. Это наш второй артефакт, с которым можем работать независимо. Вплоть до того, что начать разработку одним агентом и закончить другим. Плюс без этих артефактов будет достаточно трудно держать контекст чистым. Но об этом чуть позже.

Этот этап — это ваша страховка. Если вы его пропускаете, вы просто играете в лотерею с ресурсами и временем.

Шаг 3: Имплементация (Build)

Цель данного шага — реализовать утверждённый план и получить рабочий результат. Используется после того, как план согласован и понятен

Задача агента — выполнить реализацию, запускать инструменты, проверять результат и сделать ещё одну итерацию, если что-то пошло не так. По сути, это этап, где план превращается в код и изменения в проекте.

На этом этапе степень участия человека может отличаться. Тут у нас два стула варианта. Мы можем контролировать каждый шаг и направлять агента либо дать больше автономии, если доверяете процессу и задача достаточно понятная. Давайте я расскажу с деталями про каждый.

«Сопровождаемый»

У нас есть команда, например, /implement:task. Мы передаём этой команде файл с планом через @. Команда читает план, берет первую невыполненную таску и выполняет её. В процессе у нас перед глазами идёт процесс работы, агент спрашивает у вас подтверждения. Мгновенная обратная связь. Вы можете корректировать агента. После выполнения таски вы делаете ревью глазами или с помощью другой команды, скилла, субагента. Когда всё готово, агент помечает таску выполненной, и мы переходим к следующей.

Так как у нас есть артефакты (DESIGN.md и PLAN.md) мы имеем возможность очистить контекст. Повторюсь, чистый контекст — залог производительной работы модели. Поэтому я делаю /clear и потом /implement:task @CREATE_SONNET_5_MAKE_NO_MISTAKE.md

В самом печальном случае вы можете отменить всю работу и пересмотреть свой план. У вас полный контроль.

«Автопилот»

Создаём команду, назовём её /implement:plan. Она сделает из основного агента оркестратор, который должен прочитать план и шаг за шагом его выполнять, запуская субагентов и передавая им таски. Оркестратор следит за выполнением и трекингом состояния плана. Основной контекст чистый за счёт того, что работа происходит в субагентах. Звучит красиво, но на деле есть нюансы. Начиная от того, что модель может пойти не туда (хотя с детальным планом редко такое бывает), заканчиваю бесконечными циклами. Я как-то не проверил зависимость, которая у меня была в плане и Claude Code бедный пыхтел и так и сяк пытаясь выкрутиться и сделать хоть что-нибудь, лишь бы gradle build прошел. Заменить это сложно, если не поглядывать постоянно. Теперь у меня в этом в оркестраторе стоит лимит на 3 попытки фикса, если не выходит починить, то цикл прекращается.

Это флоу покрывает 80% потребностей в разработке, и большая часть фреймворков на этом базируется. Дальше полёт фантазии. Можно добавлять дополнительные шаги. Обязательное ревью кода. Red Green подход из TDD (посмотрите, как сделал Саша Раковский). Валидация плана другой моделью. Океан возможностей. Дерзайте.

Работа с контекстом

Чтобы эффективно расходовать токены, надо знать, когда нужно очищать сессию, а когда не надо.

Когда надо очищать контекст

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

Когда НЕ надо очищать контекс

Вы работаете над задачей, и в контексте много информации, которая модель собрала и всё идёт нормально. В данном случае при очистке контекста модели придётся опять всё собирать, читать файлы, ходить в веб и т. д. А это трата лимитов, токенов, времени.

Существует заблуждение, что частая очистка контекста экономит токены, но это не всегда так. Да, в сессии может быть много данных, но провайдеры давно научились кешировать контекст, и вы не тратите значительно больше токенов при заполненном контексте.

Если выхода нет и нужно очистить контекст, то попросите модель выгрузить основную информацию о сессии в markdown файл и переиспользуйте его в новой. Это простейший рабочий вариант. Так же сейчас полно инструментария для реализации внешней памяти для моделей. Ищете в гугле «coding agent external memory», вагон и телега решений на любой вкус.

Заключение

Сейчас нет индустриального стандарта того, как должна выглядеть работа с агентом. Мы все сейчас ищем лучшее решение. Поэтому мой самый главный совет — экспериментируйте. Не стоит сразу кидаться устанавливать развесистые фреймворки. Современные агентские приложения и так больше походят на космолёт. Сомневаюсь, что я использую и 20% их функциональности, а тут ещё и фреймворк сверху накинем. Не усложняйте. Начните с минимального процесса, который реально закрывает потребности, а затем заимствуйте идеи из фреймворков только там, где они действительно экономят усилия.

И ещё, если вы думаете, что вы не успели на этот поезд, то вы зря переживаете. Запрыгивайте. Этоn поезд летит с первой космической скоростью. Машинисты меняются на ходу. Остановок не предвидится.

Полезные ссылки

ссылка на оригинал статьи https://habr.com/ru/articles/1033136/