Subagentы

Subagentы — это специализированные AI-ассистенты, которые обрабатывают определённые типы задач внутри Qwen Code. Они позволяют делегировать целевую работу AI-агентам, настроенным с помощью специфичных для задачи промптов, инструментов и поведения.

Что такое Subagentы?

Subagentы — это независимые AI-ассистенты, которые:

• Специализируются на конкретных задачах — каждый Subagent настроен с фокусированным системным промптом для определённых типов работы
• Имеют собственный контекст — они ведут свою историю диалога, отдельную от основного чата
• Используют контролируемые инструменты — вы можете настроить, к каким инструментам у каждого Subagent есть доступ
• Работают автономно — получив задачу, они работают независимо до завершения или ошибки
• Предоставляют подробную обратную связь — вы видите их прогресс, использование инструментов и статистику выполнения в реальном времени

Субагенты Claude Code и Codex

Встроенные агенты claude-code и codex делегируют работу отдельно установленным нативным инструментам. Установите и аутентифицируйте Claude Code с помощью его адаптера claude-agent-acp или Codex с помощью его исполняемого файла codex, и сделайте исполняемый файл доступным в PATH. Эти агенты используют свои нативные настройки модели и аутентификации. Qwen Code не переключается на собственную модель, если исполняемый файл отсутствует.

Оба агента по умолчанию выполняются в переднем плане; установите run_in_background: true для получения фонового уведомления о завершении. Они требуют доверенного рабочего пространства и недоступны в безопасном режиме. Оба исполнителя поддерживают macOS/Linux (включая WSL); нативные запуски Windows отклоняются до запуска с указанием платформы.

Claude Code использует исполнитель ACP и поддерживает продолжение ввода, пока его сессия сохраняется. Codex использует эфемерный поток сервера приложений для одной задачи и возвращает окончательный ответ. Задачи Codex не могут получать сообщения или возобновляться; вместо этого запускайте новую задачу. Прогресс нативных инструментов, количество токенов и стоимость не отчитываются для Codex. Нативные сессии не могут быть восстановлены после перезапуска Qwen Code.

Для пользовательского агента Codex используйте существующий фронтматер executor:

---
name: codex-review
description: Review code with Codex
executor:
  kind: codex
  command: codex
background: false
---
 
Review the changes and report verified defects.

Пропуск executor.args запускает codex app-server --stdio; указанные аргументы заменяют это значение по умолчанию. Используйте kind: acp и command: claude-agent-acp для пользовательского агента Claude Code. Переопределения модели Qwen, списки инструментов, хуки субагентов, maxTurns, история форков, команды и рабочие процессы не поддерживаются для внешних исполнителей. Запуски в worktree используют существующий жизненный цикл изоляции Agent и запускают нативный процесс в выбранном worktree.

Codex выполняется без участия пользователя. Без переопределения агента сессии default, plan и auto используют песочницу только для чтения; классификатор AUTO Qwen не проверяет нативные команды. Промежуточные режимы субагентов Qwen не предоставляют нативный доступ во время вложенного делегирования. Явно выберите auto-edit в сессии или определении агента Codex, чтобы разрешить запись в рабочее пространство и команды рабочего пространства без участия пользователя, или yolo для полного доступа. Сессия уже в режиме auto-edit или yolo имеет приоритет над более строгим определением агента. Другие действующие режимы одобрения отклоняются. Нативные запросы на дополнительные разрешения или ввод пользователя отклоняются. Настроенный runConfig.max_time_minutes ограничивает выполнение. Исполнитель ожидает очистки процесса при отмене; общее фоновое уведомление об отмене может прийти раньше в соответствии с его пятисекундным фолбэком.

Fork Subagent

В дополнение к именованным subagent, Qwen Code поддерживает форкинг — явно выбираемый с помощью subagent_type: "fork". Форк наследует полный контекст диалога родителя и обычно работает отсоединённым в фоне. Форки работают как в интерактивных, так и в headless-сессиях; headless-форки всегда используют фоновый путь. Отсутствие subagent_type не создаёт форк; запускается subagent общего назначения. Именованные subagent верхнего уровня по умолчанию работают в фоне и доставляют свои результаты через уведомления о завершении. Установите run_in_background: false, когда текущий ход должен дождаться результата обычного subagent встроенно.

Контекст форка с fork_turns

Только subagent_type: "fork" принимает fork_turns:

• Пропуск параметра или использование all наследует полный диалог родителя.
• Положительная целая строка, например "3", наследует три последних реальных хода пользователя.

Ответы инструментов и чистые системные напоминания не считаются ходами пользователя. Обычные именованные subagent и участники команды агентов не принимают fork_turns; они сохраняют свой отдельный контекст диалога.

Ограничение выполнения инструментов форка с помощью fork_tools

Только subagent_type: "fork" принимает fork_tools. Массив может содержать точные канонические имена инструментов, такие как read_file и grep_search, или шаблоны серверов MCP, такие как mcp__github. Форк по-прежнему получает те же видимые для модели объявления инструментов, что и неограниченный форк, сохраняя префикс кэша промптов, но его промпт задачи идентифицирует ограничение, и вызов, не совпадающий с fork_tools, отклоняется до планирования или одобрения.

• Форки никогда не выполняют ask_user_question; когда требуется ввод пользователя, они сообщают о блокировке своему родительскому агенту.
• Пропуск fork_tools разрешает все остальные унаследованные инструменты.
• Пустой массив отклоняет каждый вызов инструмента.
• * не принимается; пропустите fork_tools, чтобы разрешить все иначе выполнимые унаследованные инструменты.
• Имена инструментов не могут иметь окружающие пробелы. Шаблоны принимаются только как mcp__* или как шаблон префикса инструмента MCP, например mcp__github__read_*.
• mcp__* намеренно разрешает все инструменты MCP, продолжая запрещать неуказанные встроенные инструменты.
• Шаблоны аргументов shell-команд не поддерживаются. Указание run_shell_command позволяет инструменту пройти через обычные проверки разрешений, но не одобряет заранее никакую команду.

Это ограничение на каждый вызов, предоставляемое вызывающей стороной. Оно сужает возможности дочернего форка, но не является security-песочницей, навязанной администратором, потому что вызывающая сторона может пропустить или расширить список.

Повторное использование ограничений форка с помощью fork_profile

Проект может сохранить именованное ограничение форка в .qwen/fork-profiles/<name>.md и выбрать его с помощью fork_profile. Это полезно, когда нескольким вызовам нужна одна и та же граница инструментов и рекомендации по задаче:

---
name: ro-research
tools:
  - read_file
  - grep_search
  - glob
  - mcp__search__*
promptHint: |
  Work read-only. Prefer targeted searches and cite file evidence.
---

Затем запустите форк с:

agent(description="Research", prompt="Inspect the retry path", subagent_type="fork", fork_profile="ro-research")

• fork_profile действителен только для форка и не может быть объединён с fork_tools или именованным участником команды.
• Профили в настоящее время только проектные. Запрошенное имя, имя файла и name во фронтматере должны совпадать точно. Профиль должен разрешаться в обычный файл внутри .qwen/fork-profiles/ и не может превышать 64 КиБ.
• tools обязателен и следует правилам fork_tools, включая поведение deny-all для пустого массива.
• promptHint необязателен и ограничен 200 символами. Он экранируется и оформляется как рекомендации от проекта после директивы форка и до авторитетного ограничения инструментов; он не изменяет унаследованную системную инструкцию или видимые для модели объявления инструментов. Файлы профилей содержат только фронтматер, поэтому непустой Markdown после закрывающего --- отклоняется вместо молчаливого игнорирования.
• Профиль разрешается один раз при запуске. Сохранённый форк продолжает работать с разрешённым снимком инструментов, даже если файл проекта впоследствии изменится.
• Проектные профили форков недоступны в safe mode и bare mode, которые отключают локальные настройки.

Как и fork_tools, профиль форка является ограничением, выбранным вызывающей стороной, а не административной песочницей. Его необязательные рекомендации по промпту — это контент, управляемый проектом.

Чем Fork отличается от именованных Subagent

Когда используется Fork

AI автоматически использует форк, когда ему нужно:

• Выполнять несколько исследовательских задач параллельно (например, «изучить модули A, B и C»)
• Выполнять фоновую работу, продолжая основной диалог
• Делегировать задачи, требующие понимания текущего контекста диалога

Совместное использование кэша промптов

Все форки используют точный префикс API-запроса родителя (системный промпт, инструменты, история диалога), что позволяет получать попадания в кэш промптов DashScope. Когда 3 форка работают параллельно, общий префикс кэшируется один раз и повторно используется — экономия более 80% затрат на токены по сравнению с независимыми subagent.

Предотвращение рекурсивного делегирования

Дочерние форки не могут создавать никаких дальнейших субагентов. Это обеспечивается во время выполнения — если форк вызывает инструмент Agent, он получает ошибку с инструкцией выполнять задачи напрямую.

Текущее ограничение

• Нет изоляции worktree: Форки используют рабочую директорию родителя. Одновременные изменения файлов из нескольких форков могут конфликтовать.

Ключевые преимущества

• Специализация задач: Создавайте агентов, оптимизированных для конкретных рабочих процессов (тестирование, документация, рефакторинг и т.д.)
• Изоляция контекста: Держите специализированную работу отдельно от основного диалога
• Наследование контекста: Форки subagent по умолчанию наследуют полный диалог и могут выбрать ограниченное количество последних ходов родителя
• Совместное использование кэша промптов: Форки subagent разделяют кэш-префикс родителя, снижая затраты на токены
• Многократное использование: Сохраняйте и повторно используйте конфигурации агентов в разных проектах и сессиях
• Контролируемый доступ: Ограничивайте, какие инструменты может использовать каждый агент, для безопасности и фокуса
• Видимость прогресса: Отслеживайте выполнение агента с обновлениями в реальном времени

Как работают Subagentы

1. Конфигурация: Вы создаёте конфигурации Subagent, которые определяют их поведение, инструменты и системные промпты
2. Делегирование: Основной AI может автоматически делегировать задачи подходящим Subagent — или форкать себя (subagent_type: "fork"), когда ему нужен контекст диалога родителя
3. Выполнение: Subagentы работают независимо, используя свои настроенные инструменты для выполнения задач
4. Результаты: Фоновые запуски отправляют уведомление о завершении с результатом в основной диалог; обычные subagent в переднем плане возвращают результаты встроенно
5. Продолжение: Основной AI может использовать list_agents для поиска фоновых агентов и send_message для продолжения работающего, приостановленного или завершённого агента

Продолжение фонового агента

Обычные subagent верхнего уровня по умолчанию работают в фоне. После завершения фонового агента Qwen Code сохраняет достаточно состояния для продолжения связанной работы без запуска дубликата агента:

• list_agents возвращает адресных фоновых агентов в текущей сессии, включая совместимых агентов, восстановленных с возобновлённой сессией. Каждая запись содержит task_id, статус и информацию о том, может ли она получать сообщения.
• send_message с этим task_id ставит в очередь сообщение для работающего агента, возобновляет приостановленного агента или продолжает завершённого агента. Продолженные агенты повторно используют свою резидентную среду выполнения, если она доступна, и иначе оживляются из сохранённого транскрипта.
• Продолженный агент сообщает свой следующий результат через ещё одно уведомление о завершении.

Когда сессия восстанавливается, совместимые фоновые агенты добавляются обратно в ростер сессии. Задача может быть видимой, но не продолжаемой, когда её сохранённое состояние отсутствует или несовместимо; list_agents сообщает причину в этом случае.

Используйте продолжение для связанной последующей работы. Запускайте новый агент, когда задача не связана или предыдущий агент не может быть возобновлён.

Очередь уведомлений

В интерактивном TUI и сессии ACP уведомления о завершении от фоновых агентов, оболочек, мониторов и рабочих процессов разделяют очередь, которая дренируется в ход модели, когда сессия простаивает. Эти очереди вмещают не более 20 уведомлений, чтобы шумный производитель не мог накопить неограниченный откат. Локальная очередь headless CLI не ограничивается этим правилом.

Когда приходит 21-е уведомление, Qwen Code сначала вытесняет промежуточный импульс монитора — следующий опрос монитора заменяет его — а в противном случае самое старое уведомление в очереди. Результаты агентов, результаты рабочих процессов и запланированные промпты никогда не вытесняются в интерактивном TUI; уведомление, которое вытеснило бы одно из них, отбрасывается вместо этого, как и прибывающий импульс, когда в очереди только терминальные результаты.

Отброшенные уведомления сообщаются, а не отбрасываются молча. Сводка появляется перед следующим уведомлением в живом транскрипте. ACP также добавляет её ко входу модели этого хода; TUI держит её припаркованной для следующей порции уведомлений, чтобы промпты cron по-прежнему проходили без изменений через предварительную обработку слеш-, shell- и @. Уведомление демона записывается до того, как оно будет подтверждено, поэтому после перезагрузки его долговечная запись может предшествовать более поздней сводке о переполнении. ACP может отбросить ожидающую сводку, если сессия очищена или переключена, или если клиент отменяет или вытесняет ход уведомления. Отбрасывание уведомления никогда не останавливает и не удаляет его задачу, а завершённые задачи сохраняют свои результаты; сводка указывает на /tasks и файлы вывода задач, когда есть задача для проверки. Отброшенный запланированный промпт никогда не доставлялся и не повторяется. Уведомление демона, которое было записано, но не могло быть доставлено вживую, остаётся доступным в транскрипте сессии и сообщается отдельно от потерянных уведомлений.

Рабочая директория агента

Для именованного обычного subagent working_dir привязывает агента к существующему git worktree текущего репозитория. Относительные пути разрешаются от текущей директории, и worktree должен быть уже зарегистрирован в git как связанный worktree этого репозитория.

working_dir нельзя комбинировать с subagent_type: "fork". Запуск с working_dir, принадлежащим вызывающему, выполняется в переднем плане, потому что Qwen Code не управляет жизненным циклом этого worktree: явный запрос run_in_background: true отклоняется, а настроенный фоновый режим по умолчанию (background: true в определении субагента) отклоняется на верхнем уровне и понижается до переднего плана при вложенности. Если указаны и working_dir, и isolation: "worktree", Qwen Code повторно использует worktree, принадлежащий вызывающей стороне, вместо создания нового. Скрипты рабочих процессов намеренно строже: вызов agent() в рабочем процессе, получающий и workingDir, и isolation, отклоняется, а не выполняется с игнорированием isolation.

Начало работы

Быстрый старт

1. Создайте своего первого Subagent:

   /agents create

   Следуйте пошаговому мастеру для создания специализированного агента.

2. Управляйте существующими агентами:

   /agents manage

   Просматривайте и управляйте настроенными Subagent.

3. Используйте Subagent автоматически: Просто попросите основной AI выполнить задачи, соответствующие специализациям ваших Subagent. AI автоматически делегирует подходящую работу.

Пример использования

Пользователь: «Пожалуйста, напиши всесторонние тесты для модуля аутентификации»
AI: Я передам это вашему специалисту по тестированию Subagent.
[Делегирует Subagent "testing-expert"]
[Показывает прогресс создания тестов в реальном времени]
[Возвращает готовые тестовые файлы и сводку выполнения]

Управление

Команды CLI

Subagent управляются через слэш-команду /agents и её подкоманды:

Использование: /agents create. Создаёт нового Subagent через пошаговый мастер.

Использование: /agents manage. Открывает интерактивный диалог управления для просмотра и управления существующими Subagent.

Места хранения

Subagent хранятся в виде Markdown-файлов в нескольких местах:

• На уровне проекта: .qwen/agents/ (наивысший приоритет)
• На уровне пользователя: ~/.qwen/agents/ (запасной вариант)
• На уровне расширений: Предоставляются установленными расширениями

Это позволяет иметь проектно-специфичные агенты, личные агенты, работающие во всех проектах, и агенты, предоставляемые расширениями, которые добавляют специализированные возможности.

Subagent расширений

Расширения могут предоставлять пользовательские subagent, которые становятся доступными при включении расширения. Эти агенты хранятся в каталоге agents/ расширения и следуют тому же формату, что и личные и проектные агенты.

Subagent расширений:

• Автоматически обнаруживаются при включении расширения
• Отображаются в диалоге /agents manage в разделе «Агенты расширений»
• Не могут быть отредактированы напрямую (вместо этого редактируйте исходный код расширения)
• Следуют тому же формату конфигурации, что и пользовательские агенты

Чтобы узнать, какие расширения предоставляют subagent, проверьте файл расширения qwen-extension.json на наличие поля agents.

Формат файла

Subagent настраиваются с помощью Markdown-файлов с YAML-фронтматером. Этот формат удобочитаем и легко редактируется в любом текстовом редакторе.

Базовая структура

---
name: agent-name
description: Краткое описание того, когда и как использовать этого агента
model: inherit   # Опционально: inherit, fast, modelId или authType:modelId
approvalMode: auto-edit   # Опционально: default, plan, auto-edit, yolo, bubble
tools:           # Опционально: белый список инструментов
  - tool1
  - tool2
disallowedTools: # Опционально: чёрный список инструментов
  - tool3
---

Содержимое системного промпта.
Поддерживаются несколько абзацев.

Выбор модели

Используйте опциональное поле model во фронтматере для управления тем, какую модель использует subagent:

• inherit: Использовать ту же модель, что и в основном диалоге.
• Пропустите поле: То же самое, что inherit.
• fast: Использовать настроенную fastModel. Если корректная быстрая модель не настроена, subagent переключается на inherit.
• glm-5: Использовать указанный ID модели. Qwen Code сначала проверяет тип аутентификации основного диалога; если модель там недоступна, он может разрешить модель у другого настроенного провайдера.
• openai:gpt-4o: Использовать явного провайдера и ID модели. Это полезно, когда subagent должен работать на модели, зарегистрированной под другим типом аутентификации, чем основной диалог.

Например:

---
name: fast-reviewer
description: Просматривает небольшие diff'ы с настроенной быстрой моделью
model: fast
tools:
  - read_file
  - grep_search
---

---
name: openai-researcher
description: Использует совместимого с OpenAI провайдера для исследовательских задач
model: openai:gpt-4o
tools:
  - read_file
  - grep_search
  - glob
---

Селектор fast использует ту же настройку fastModel, настроенную в settings.json или с помощью /model --fast. Эта настройка может сама ссылаться на модель под другим настроенным типом аутентификации, например openai:deepseek-v4-flash. Когда селектор разрешается в другой тип аутентификации, Qwen Code создаёт выделенного провайдера времени выполнения для этого запроса subagent и отправляет провайдеру только голый ID модели.

Встроенный агент Explore по умолчанию наследует модель основной сессии. Чтобы выбрать другую модель только для этого встроенного агента, настройте agents.builtin.exploreModel в settings.json и перезапустите Qwen Code:

В ранних версиях по умолчанию использовался fastModel для Explore. Чтобы сохранить это поведение, установите agents.builtin.exploreModel в fast.

{
  "agents": {
    "builtin": {
      "exploreModel": "fast"
    }
  }
}

Эта настройка принимает те же селекторы, что описаны выше. Она применяется только когда Qwen Code разрешает встроенное определение Explore; сессия, проект, пользователь или агент расширения с именем Explore сохраняет свою собственную настройку model.

Чтобы позволить модели выбирать из пользовательских грейдов без раскрытия конкретных ID моделей, настройте agents.modelGrades и при необходимости ограничьте их с помощью agents.allowedGrades:

{
  "agents": {
    "modelGrades": {
      "small": "fast",
      "high": "qwen-max"
    },
    "allowedGrades": ["small", "high"]
  }
}

Инструмент Agent затем принимает model: "small" или model: "high" для обычных subagent. Неизвестные, запрещённые, форк и именованные участники команды с выбором грейда отклоняются. Явная модель пользовательского агента по-прежнему имеет приоритет над грейдом.

Режим разрешений

Используйте опциональное поле approvalMode во фронтматере для управления тем, как одобряются вызовы инструментов subagent. Допустимые значения:

• default: Для инструментов требуется интерактивное одобрение (как и по умолчанию в основной сессии)
• plan: Только анализ — агент планирует, но не выполняет изменения
• auto-edit: Инструменты одобряются автоматически без запроса (рекомендуется для большинства агентов)
• yolo: Все инструменты одобряются автоматически, включая потенциально деструктивные
• bubble: Одобрения инструментов фонового агента отображаются в родительской сессии

Если вы опускаете это поле, режим разрешений subagent определяется автоматически:

• Если родительская сессия находится в режиме yolo или auto-edit, subagent наследует этот режим. Разрешительный родитель остаётся разрешительным.
• Если родительская сессия находится в режиме plan, subagent остаётся в режиме plan. Сессия только для анализа не может изменять файлы через делегированного агента.
• Если родительская сессия находится в режиме default (в доверенной папке), subagent получает auto-edit, чтобы он мог работать автономно.

Когда вы устанавливаете approvalMode, разрешительные режимы родителя по-прежнему имеют приоритет. Например, если родитель находится в режиме yolo, subagent с approvalMode: plan всё равно будет работать в режиме yolo.

---
name: cautious-reviewer
description: Просматривает код без внесения изменений
approvalMode: plan
tools:
  - read_file
  - grep_search
  - glob
---

Вы — ревьюер кода. Анализируйте код и сообщайте о результатах.
Не изменяйте никакие файлы.

Настройка инструментов

Используйте tools и disallowedTools для управления тем, к каким инструментам может обращаться subagent.

tools (белый список): При указании subagent может использовать только перечисленные инструменты. Если поле опущено, subagent наследует все доступные инструменты от родительской сессии.

---
name: reader
description: Агент только для чтения для исследования кода
tools:
  - read_file
  - grep_search
  - glob
  - web_fetch
---

disallowedTools (чёрный список): При указании перечисленные инструменты удаляются из пула инструментов subagent. Это полезно, когда нужно «всё, кроме X» без перечисления каждого разрешённого инструмента.

---
name: safe-worker
description: Агент, не могущий изменять файлы
disallowedTools:
  - write_file
  - edit
  - run_shell_command
---

Если указаны и tools, и disallowedTools, сначала применяется белый список, затем из этого набора удаляются инструменты из чёрного списка.

Инструменты MCP следуют тем же правилам. Если у subagent нет списка tools, он наследует все инструменты MCP от родительской сессии. Если у subagent есть явный список tools, он получает только те инструменты MCP, которые явно указаны в этом списке.

Поле disallowedTools поддерживает шаблоны на уровне сервера MCP:

• mcp__server__tool_name — блокирует конкретный инструмент MCP
• mcp__server — блокирует все инструменты с этого сервера MCP

---
name: no-slack
description: Агент без доступа к Slack
disallowedTools:
  - mcp__slack
---

Поля совместимости с Claude Code

Qwen Code принимает поля фронтматера Claude Code 2.1.168, перечисленные ниже, так что вы можете поместить файл агента CC в .qwen/agents/, и поддерживаемые поля будут парситься идентично. Опциональные поля с недопустимыми значениями молча отбрасываются во время парсинга, а не отвергаются — та же либеральная позиция, которую использует CC.

Пример со всем вышеперечисленным:

---
name: rigorous-reviewer
description: Глубокий ревью кода с ограничением ходов
permissionMode: plan
maxTurns: 50
color: cyan
tools:
  - read_file
  - grep_search
  - glob
mcpServers:
  filesystem:
    type: stdio
    command: node
    args: [/usr/local/lib/mcp-fs/server.js]
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: echo "review-agent about to run a shell command"
---

Вы — ревьюер кода. Тщательно анализируйте код и сообщайте о результатах,
упорядоченных по серьёзности.

Остальные поля фронтматера CC — effort, skills, initialPrompt, memory, isolation — документированы в дизайн-документе декларативных агентов и появятся в последующих PR, когда будет создана необходимая инфраструктура (effort требует параметра на уровне модели; memory требует подсистему памяти с областью видимости; флаг CLI --agent включает initialPrompt; и т.д.).

Ограничение v1 для hooks. Пока работает subagent, объявивший hooks, его записи хуков срабатывают для каждого подходящего события в сессии, а не только для вызовов инструментов этого subagent. Если два subagent с разными наборами хуков для каждого агента работают одновременно, оба набора срабатывают для обоих агентов. Фильтрация по области видимости агента во время срабатывания хука оставлена на будущее; для v1 предпочитайте хуки для каждого агента, которые безопасно срабатывают глобально на время выполнения агента (например, логирование), вместо хуков, которые изменяют поведение.

Пример использования

---
name: project-documenter
description: Создаёт документацию проекта и файлы README
---

Вы — специалист по документации.

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

Эффективное использование Subagent

Автоматическое делегирование

Qwen Code проактивно делегирует задачи на основе:

• Описания задачи в вашем запросе
• Поля description в конфигурациях Subagent
• Текущего контекста и доступных инструментов

Чтобы стимулировать более проактивное использование Subagent, включайте фразы типа «использовать ПРОАКТИВНО» или «ДОЛЖЕН БЫТЬ ИСПОЛЬЗОВАН» в поле description.

Явный вызов

Запросите конкретного Subagent, упомянув его в своей команде:

Пусть Subagent testing-expert создаст модульные тесты для модуля оплаты
Поручи Subagent documentation-writer обновить API-справочник
Пусть Subagent react-specialist оптимизирует производительность этого компонента

Примеры

Агенты для рабочего процесса разработки

Специалист по тестированию

Идеально подходит для всестороннего создания тестов и разработки через тестирование.

---
name: testing-expert
description: Пишет всесторонние модульные тесты, интеграционные тесты и управляет автоматизацией тестирования с лучшими практиками
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

Вы — специалист по тестированию, сосредоточенный на создании высококачественных, поддерживаемых тестов.

Ваша экспертиза включает:

- Модульное тестирование с соответствующим мокингом и изоляцией
- Интеграционное тестирование взаимодействия компонентов
- Практики разработки через тестирование
- Выявление граничных случаев и всестороннее покрытие
- Тестирование производительности и нагрузки, когда это уместно

Для каждой задачи тестирования:

1. Проанализируйте структуру кода и зависимости
2. Определите ключевую функциональность, граничные случаи и условия ошибок
3. Создайте всесторонние тестовые наборы с описательными именами
4. Включите правильную настройку/очистку и осмысленные утверждения
5. Добавьте комментарии, объясняющие сложные сценарии тестирования
6. Убедитесь, что тесты поддерживаемы и следуют принципам DRY

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

Варианты использования:

• «Напиши модульные тесты для сервиса аутентификации»
• «Создай интеграционные тесты для процесса обработки платежей»
• «Добавь тестовое покрытие для граничных случаев в модуле валидации данных»

Писатель документации

Специализируется на создании понятной, всеобъемлющей документации.

---
name: documentation-writer
description: Создаёт всестороннюю документацию, файлы README, API-документацию и руководства пользователя
tools:
  - read_file
  - write_file
  - read_many_files
---

Вы — специалист по технической документации.

Ваша роль — создавать понятную, всеобъемлющую документацию, которая служит как
разработчикам, так и конечным пользователям. Сосредоточьтесь на:

**Для API-документации:**

- Чёткие описания конечных точек с примерами
- Детали параметров с типами и ограничениями
- Документация формата ответов
- Объяснения кодов ошибок
- Требования аутентификации

**Для пользовательской документации:**

- Пошаговые инструкции со скриншотами, где это полезно
- Руководства по установке и настройке
- Параметры конфигурации и примеры
- Разделы по устранению неполадок для распространённых проблем
- Разделы FAQ на основе частых вопросов пользователей

**Для документации разработчика:**

- Обзоры архитектуры и дизайнерские решения
- Рабочие примеры кода
- Руководства по внесению вклада
- Настройка среды разработки

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

Варианты использования:

• «Создай API-документацию для конечных точек управления пользователями»
• «Напиши всесторонний README для этого проекта»
• «Документируй процесс развёртывания с шагами по устранению неполадок»

Ревьюер кода

Сосредоточен на качестве кода, безопасности и лучших практиках.

---
name: code-reviewer
description: Проверяет код на лучшие практики, проблемы безопасности, производительность и поддерживаемость
tools:
  - read_file
  - read_many_files
---

Вы — опытный ревьюер кода, сосредоточенный на качестве, безопасности и поддерживаемости.

Критерии проверки:

- **Структура кода**: Организация, модульность и разделение ответственности
- **Производительность**: Алгоритмическая эффективность и использование ресурсов
- **Безопасность**: Оценка уязвимостей и практики безопасного кодирования
- **Лучшие практики**: Соглашения, специфичные для языка/фреймворка
- **Обработка ошибок**: Правильная обработка исключений и покрытие граничных случаев
- **Читаемость**: Понятные имена, комментарии и организация кода
- **Тестирование**: Покрытие тестами и соображения тестируемости

Предоставляйте конструктивную обратную связь с:

1. **Критические проблемы**: Уязвимости безопасности, серьёзные ошибки
2. **Важные улучшения**: Проблемы производительности, проблемы дизайна
3. **Незначительные предложения**: Улучшения стиля, возможности рефакторинга
4. **Положительная обратная связь**: Хорошо реализованные паттерны и удачные практики

Сосредоточьтесь на действенной обратной связи с конкретными примерами и предлагаемыми решениями.
Приоритезируйте проблемы по степени влияния и предоставляйте обоснование для рекомендаций.

Варианты использования:

• «Проверьте эту реализацию аутентификации на наличие проблем безопасности»
• «Оцените влияние на производительность этой логики запросов к базе данных»
• «Проанализируйте структуру кода и предложите улучшения»

Предметно-ориентированные агенты

Специалист по React

Оптимизирован для разработки на React, хуков и паттернов компонентов.

---
name: react-specialist
description: Эксперт в разработке на React, хуках, паттернах компонентов и современных лучших практиках React
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

Вы — специалист по React с глубокой экспертизой в современной разработке на React.

Ваша экспертиза охватывает:

- **Дизайн компонентов**: Функциональные компоненты, пользовательские хуки, паттерны композиции
- **Управление состоянием**: useState, useReducer, Context API и внешние библиотеки
- **Производительность**: React.memo, useMemo, useCallback, разделение кода
- **Тестирование**: React Testing Library, Jest, стратегии тестирования компонентов
- **Интеграция TypeScript**: Правильная типизация для props, хуков и компонентов
- **Современные паттерны**: Suspense, Error Boundaries, параллельные возможности

Для задач React:

1. По умолчанию используйте функциональные компоненты и хуки
2. Реализуйте правильную типизацию TypeScript
3. Следуйте лучшим практикам и соглашениям React
4. Учитывайте влияние на производительность
5. Включайте соответствующую обработку ошибок
6. Пишите тестируемый, поддерживаемый код

Всегда следите за актуальными лучшими практиками React и избегайте устаревших паттернов.
Сосредоточьтесь на доступности и удобстве использования.

Варианты использования:

• «Создайте переиспользуемый компонент таблицы данных с сортировкой и фильтрацией»
• «Реализуйте кастомный хук для получения данных из API с кэшированием»
• «Перепишите этот классовый компонент, используя современные паттерны React»

Эксперт по Python

Специализируется на разработке на Python, фреймворках и лучших практиках.

---
name: python-expert
description: Эксперт в разработке на Python, фреймворках, тестировании и лучших практиках Python
tools:
  - read_file
  - write_file
  - read_many_files
  - run_shell_command
---

Вы — эксперт по Python с глубокими знаниями экосистемы Python.

Ваша экспертиза включает:

- **Основы Python**: Pythonic-паттерны, структуры данных, алгоритмы
- **Фреймворки**: Django, Flask, FastAPI, SQLAlchemy
- **Тестирование**: pytest, unittest, мокинг, разработка через тестирование
- **Data Science**: pandas, numpy, matplotlib, jupyter notebooks
- **Асинхронное программирование**: asyncio, паттерны async/await
- **Управление пакетами**: pip, poetry, виртуальные окружения
- **Качество кода**: PEP 8, type hints, линтинг с pylint/flake8

Для задач Python:

1. Следуйте руководствам по стилю PEP 8
2. Используйте type hints для лучшей документации кода
3. Реализуйте правильную обработку ошибок с конкретными исключениями
4. Пишите подробные docstrings
5. Учитывайте производительность и использование памяти
6. Включайте соответствующее логирование
7. Пишите тестируемый, модульный код

Сосредоточьтесь на написании чистого, поддерживаемого кода Python, соответствующего стандартам сообщества.

Варианты использования:

• «Создайте сервис FastAPI для аутентификации пользователей с JWT-токенами»
• «Реализуйте пайплайн обработки данных с pandas и обработкой ошибок»
• «Напишите CLI-инструмент с использованием argparse и подробной справкой»

Лучшие практики

Принципы проектирования

Принцип единственной ответственности

Каждый сабагент должен иметь чёткую и сфокусированную цель.

✅ Хорошо:

---
name: testing-expert
description: Пишет всесторонние модульные тесты и интеграционные тесты
---

❌ Избегайте:

---
name: general-helper
description: Помогает с тестированием, документацией, ревью кода и развёртыванием
---

Почему: Сфокусированные агенты дают лучшие результаты и их проще поддерживать.

Чёткая специализация

Определяйте конкретные области знаний, а не широкие возможности.

✅ Хорошо:

---
name: react-performance-optimizer
description: Оптимизирует приложения React для производительности с помощью профилирования и лучших практик
---

❌ Избегайте:

---
name: frontend-developer
description: Работает над задачами фронтенд-разработки
---

Почему: Конкретная экспертиза ведёт к более целенаправленной и эффективной помощи.

Действенные описания

Пишите описания, которые чётко указывают, когда использовать агента.

✅ Хорошо:

description: Проверяет код на уязвимости безопасности, проблемы производительности и проблемы поддерживаемости

❌ Избегайте:

description: Полезный ревьюер кода

Почему: Чёткие описания помогают основному ИИ выбрать правильного агента для каждой задачи.

Лучшие практики настройки

Рекомендации по системному промпту

Указывайте конкретные знания:

Вы — специалист по тестированию на Python с экспертизой в:

- фреймворк pytest и фикстуры
- Mock-объекты и внедрение зависимостей
- Практики разработки через тестирование
- Тестирование производительности с pytest-benchmark

Включайте пошаговые подходы:

Для каждой задачи тестирования:

1. Проанализируйте структуру кода и зависимости
2. Определите ключевую функциональность и граничные случаи
3. Создайте всесторонние тестовые наборы с понятными именами
4. Включите настройку/очистку и правильные утверждения
5. Добавьте комментарии, объясняющие сложные сценарии тестирования

Указывайте стандарты вывода:

Всегда следуйте этим стандартам:

- Используйте описательные имена тестов, объясняющие сценарий
- Включайте как позитивные, так и негативные тестовые случаи
- Добавляйте docstrings для сложных тестовых функций
- Убедитесь, что тесты независимы и могут выполняться в любом порядке

Вопросы безопасности

• Ограничения инструментов: Используйте tools, чтобы ограничить, к каким инструментам сабагент имеет доступ, или disallowedTools, чтобы заблокировать конкретные инструменты, наследуя все остальные.
• Режим разрешений: Сабагенты по умолчанию наследуют режим разрешений родителя. Сессии в режиме планирования не могут повысить свои права до auto-edit через делегированных агентов. Привилегированные режимы (auto-edit, yolo) заблокированы в ненадёжных папках.
• Выбор провайдера: Сабагент с model: authType:modelId или model: fast (где fastModel разрешается в другой тип аутентификации) отправляет запросы модели этого сабагента выбранному провайдеру. Убедитесь, что этот провайдер подходит для задачи и данных сабагента.
• Изоляция: Все выполнение инструментов следует той же модели безопасности, что и прямое использование инструментов.
• Журнал аудита: Все действия сабагентов логируются и отображаются в реальном времени.
• Контроль доступа: Разделение на уровне проекта и пользователя обеспечивает соответствующие границы.
• Конфиденциальная информация: Избегайте включения секретов или учётных данных в конфигурации агентов.
• Продуктивные среды: Рассмотрите возможность создания отдельных агентов для продуктивной и тестовой сред.

Ограничения

Следующие мягкие предупреждения применяются к конфигурациям сабагентов (жёсткие ограничения не накладываются):

• Поле описания: Предупреждение отображается для описаний, превышающих 1 000 символов.
• Системный промпт: Предупреждение отображается для системных промптов, превышающих 10 000 символов.