opencode agents позволяют назначить отдельным помощникам инструкции и права на инструменты, затем передать узкую задачу нужной роли. Например, агент для обзора кода читает файлы и описывает риски, а право менять проект остаётся у другого участника процесса. Такая схема полезна, когда команда заранее определила границы задачи и человека, который примет итог.
Разделение ролей
В OpenCode есть основные агенты и субагенты: основные ведут диалог, субагенты получают отдельные задачи. Для каждой роли можно задать собственную инструкцию и разрешения, согласно документации OpenCode.
Начните с карты работ, а затем дайте каждому агенту конкретный результат. Основной агент ведёт запрос разработчика: уточняет цель, собирает выводы и предлагает следующий шаг. Субагенту удобно поручить ограниченный обзор модуля или поиск точек изменения. Название роли служит меткой; доступы задают разрешения. Действия определяет конфигурация разрешений и среда, в которой запущен OpenCode.
Условный пример: в репозитории нужно понять, почему проверка заказа пропускает пустой адрес. Исследователь читает относящиеся к заказу файлы и возвращает список веток логики с путями к исходникам. Рецензент формулирует возможные причины и тестовые случаи. Исполнитель получает право править только после выбора подхода ответственным разработчиком. Здесь роли отделяют исследование от изменения, поэтому итог каждого шага легче проверить.
- Запишите результат роли как проверяемый артефакт: список файлов, гипотезы с источниками, патч или замечания к патчу.
- Опишите входные данные: каталог проекта, конкретный модуль, симптом ошибки и доступные тесты.
- Укажите предел действий: чтение, редактирование, команды оболочки и обращение к внешним источникам требуют разных решений.
Для общей схемы распределения работы между помощниками пригодится разбор ИИ-агентов в разработке. Здесь фокус уже: конфигурация ролей OpenCode и конкретная передача задания между ними.
Инструкции и права
OpenCode описывает роли в конфигурации проекта или в Markdown-файлах каталога .opencode/agents/. В файле роли укажите описание, режим primary либо subagent, а также разрешения. В теле файла напишите рабочую инструкцию: какие материалы читать, какой формат ответа вернуть, когда передать спорный вопрос человеку. Для командного репозитория проектное описание удобнее персонального: участники видят одну версию роли рядом с кодом.
| Роль | Задача | Граница доступа | Приёмка |
|---|---|---|---|
| Исследователь | Находит связанную логику и указывает файлы | Чтение разрешено, правки запрещены | Разработчик открывает указанные строки |
| Рецензент | Ищет риск в предложенном патче | Редактирование запрещено, команды требуют отдельного решения | Автор сверяет замечания с кодом и тестами |
| Исполнитель | Готовит согласованную правку | Доступ к записи в рабочей области | Человек смотрит diff и запускает проверки |
В конфигурации прав используйте поля permission, например read, edit, bash и task. Значения allow, ask и deny выражают разрешение, запрос подтверждения и запрет. По документации OpenCode, старое поле tools сохраняется, но для новых ролей предпочтительны разрешения: они дают более точную настройку. Сверяйте названия полей с актуальной документацией перед сохранением конфигурации.
Разрешения OpenCode полезны как интерфейс управления действиями агента. Для чувствительных файлов и обязательных подтверждений добавьте ограничения среды: права файловой системы, проверку учётной записи на сервере и серверный допуск к операции. Текст инструкции способен попросить агента остановиться, но техническую границу доступа задают настройки среды и сервер. Дополнительные принципы разбирает статья о правах и секретах ИИ-агентов.
Передача задачи
Перед вызовом субагента составьте короткое поручение с границами. Формулировка «проверь проект» оставляет слишком широкий выбор файлов и критериев. Рабочее поручение называет модуль, наблюдаемый симптом, допустимые действия и вид ответа. Основной агент может вызвать субагента для отдельной работы; пользователь также может обратиться к роли через упоминание @. Порядок вызова описан в документации OpenCode.
- Сформулируйте цель: найти ветку проверки адреса заказа и показать, где пустое значение проходит дальше.
- Передайте контекст: путь к модулю, наблюдаемый ввод, ожидаемое поведение и известный тест. Используйте обезличенные данные.
- Назначьте исследователю чтение нужного участка и формат ответа: путь, строка, объяснение, уверенность, открытый вопрос.
- Получите вывод и сами откройте названные файлы. После сверки решите, нужен ли патч и какая роль вправе его готовить.
Передача задачи работает лучше при ясной точке возврата. Попросите исследователя перечислить непроверенные предположения и остановиться после ответа. Если найдено несколько возможных причин, основной агент собирает их в отдельные гипотезы, а разработчик выбирает проверку. Модель помогает объяснить код и предложить версии; результаты тестов, фактическое поведение и права на изменение сверяет человек.
Внутри поручения отдельно укажите условие остановки: агент возвращает наблюдения и открытые вопросы, даже если причина пока выглядит очевидной. Так исследователь сохраняет границы роли, а исполнитель получает задачу после проверки фактов. Формат передачи можно закрепить в инструкции роли и повторять для новых модулей без расширения набора разрешений.
Когда агенту нужны дополнительные внешние инструменты, возникает отдельная задача доступа. Её границы разобраны в статье про OpenCode MCP. Здесь подключение серверов оставляем за рамками процесса: сначала проверьте передачу поручения между ролями на уже доступных файлах проекта.
Хотите разграничить роли агентов в своём репозитории?
Приёмка результата
Ответ субагента показывает его выводы, но принятие изменения требует независимой проверки. Откройте названные файлы, сравните объяснение с текущим кодом и убедитесь, что задача осталась внутри указанного модуля. Для патча просмотрите diff: какие строки поменялись, появились ли неожиданные файлы, затронуты ли обработка ошибок и соседние ветки. Затем запускайте подходящие проверки проекта в контролируемой среде.
Показатель качества для такого пилота привяжите к измеримому результату работы агента. Заранее зафиксируйте проверяемые критерии: все указанные пути существуют, причина воспроизводится, тест на пустой адрес падает до правки и проходит после неё, соседний сценарий сохраняет поведение. Эти проверки предложены как план будущего пилота; фактические результаты появятся только после выполнения работы на вашем коде.
- Подтвердите источники: путь, строку и актуальную версию файла для каждого существенного вывода.
- Отделите наблюдение от гипотезы: запись «условие допускает пустую строку» требует просмотра исходника, версия о причине сбоя требует проверки вводом.
- Сверьте границы изменения: патч должен отвечать согласованной задаче, побочные правки отправьте на отдельное рассмотрение.
- Сохраните решение человека: принято, возвращено на доработку или отклонено с конкретной причиной.
Для регулярной работы заведите журнал поручений: формулировка, имя роли, разрешения, ссылка на diff, результат проверок и решение ответственного. Такой журнал помогает понять, где инструкция оказалась расплывчатой или роль получила лишний инструмент. Подход к проверке сценариев и откату подробнее описан в материале о тестировании ИИ-агентов.
Пилот команды
Для первого пилота предложите небольшой участок кода с известным симптомом и ответственным разработчиком. Запишите две роли: исследователь только читает, исполнитель готовит правку после согласования. Передайте исследователю узкое поручение и сравните его вывод с исходником. Затем выдайте исполнителю подтверждённую задачу, проверьте diff и тесты. Такой пилот проверяет сразу две вещи: понятность инструкции и соответствие фактических действий заданным правам.
Если исследователь просит дополнительные действия, сначала разберите причину запроса. Возможно, ему хватает конкретного файла или результата уже запущенного теста. Если действительно нужен новый инструмент, добавьте его в разрешения осознанно и зафиксируйте владельца решения. Главная типичная ошибка здесь состоит в широком допуске ради удобства формулировки поручения: после этого трудно понять, какие действия действительно требовались роли.
После пробного задания сравните сформулированные права с журналом реальных вызовов. Если роль обращалась к лишним файлам, уточните область поручения. Если ответ содержал ссылки на устаревшие строки, добавьте в формат результата требование указывать текущую версию исходника. Затем повторите проверку на другой воспроизводимой ошибке, сохранив те же критерии приёмки.
Возьмите воспроизводимую ошибку, выпишите допустимые файлы и задайте исследователю формат ответа с путями к коду. Разработчик проверяет каждую ссылку на исходник до передачи задачи исполнителю. Успех пилота означает совпадение вывода с кодом и отсутствие действий за пределами согласованной роли.
Затраты на настройку зависят от структуры репозитория, числа ролей, действующих правил доступа и набора проверок. Тариф OpenCode и условия выбранной модели уточняйте на страницах соответствующих сервисов без переноса чужих цифр в смету команды. Если нужен процесс с ответственными, журналом решений и серверной проверкой допусков, напишите нам: состав работ и стоимость обсудим под вашу задачу на странице про ИИ-агентов для бизнеса.
Частые вопросы
Как создать агента в OpenCode?
.opencode/agents/. Укажите описание, режим, разрешения и инструкцию с проверяемым результатом. Синтаксис сверяйте с документацией OpenCode.Чем основной агент отличается от субагента?
Можно ли запретить агенту редактировать файлы?
permission.edit: deny. Дополнительно ограничьте доступ к файлам на уровне среды и проверяйте критические действия на сервере: права доступа обеспечивает среда, а критические операции проверяет сервер.