Модуль 4
Субагенты
Встроенные general и explore, свой ревьюер в .opencode/agents/reviewer.md, права родителя и потомка, явный вызов @reviewer и просьба в прозе.
Чему научишься
- вызывать встроенных субагентов @general и @explore из диалога с primary-агентом
- создавать своего агента в .opencode/agents/reviewer.md: description, mode, model, permissions
- рассчитывать, как складываются права родителя и потомка при запуске субагента
До этого момента ты работал с primary-агентами build и plan: с ними идёт диалог, build правит файлы, plan только анализирует, переключение через Shift+Tab, список через /agents. Субагент — специалист на один вызов. Он решает задачу со своим системным промптом и своими permissions в дочерней сессии и возвращает результат в общую сессию.
Дочерняя сессия получает свежий контекст: из диалога в неё уходит только поручение. Поиск по кодовой базе не засоряет основную сессию списком файлов, а ревьюер видит код без гипотез, накопившихся за час разговора.
Встроенные субагенты
Два встроенных субагента закрывают типовые задачи: explore ищет и читает код и веб-источники, файлы не меняет; general берёт многошаговую работу с широкими правами, но своих субагентов не запускает. Своего агента заводят одним markdown-файлом, этим займёмся ниже.
| Агент | mode | Что делает |
|---|---|---|
build | primary | основной агент сессии, правит файлы |
plan | primary | анализирует и планирует, файлы проекта не трогает |
general | subagent | многошаговые задачи, широкие права, без своих субагентов |
explore | subagent | поиск и чтение кода и веб-источников, без правок |
@explore найди в orders-api все места, где читается data/db.json, и скажи, кто пишет файл
Чтение и запись файла в src/db.ts: функции load и save. load вызывают src/routes/menu.ts, src/routes/orders.ts, src/routes/stats.ts и src/routes/legacy.ts; save — src/routes/orders.ts в POST и PATCH. Список файлов и строк возвращаю в сессию, сами чтения остались в моей дочерней сессии.
Свой агент-ревьюер в markdown-файле
Папку .opencode/agents/ создавай в корне репозитория. Имя файла задаёт идентификатор: reviewer.md превращается в @reviewer, вложенный путь team/reviewer.md даёт идентификатор team/reviewer. Агенты для всех проектов живут в ~/.config/opencode/agents/.
Frontmatter описывает агента: description виден в списке /agents и в перечне, по которому primary выбирает исполнителя, mode: subagent не даёт выбрать его как primary, permissions ограничивает действия по тем же правилам, что ты настраивал в модуле 3. Тело файла после frontmatter целиком становится системным промптом ревьюера.
Задачу адресуй явным @reviewer. Просьба в прозе без имени адресована primary, и он волен выбрать другого исполнителя: например, general с полными правами, тогда файлы поправит он. Read-only ревью получается только у ревьюера.
---
description: Код-ревьюер. Читает код, находит баги, предлагает правки текстом. Файлы не меняет.
mode: subagent
permissions:
- action: read
resource: "*"
effect: allow
- action: edit
resource: "*"
effect: deny
- action: shell
resource: "*"
effect: deny
---
Ты — код-ревьюер TypeScript-сервисов.
Правила:
- читай присланные файлы и смежные: роуты, сервисы, типы, фикстуры
- находи баги, дыры в валидации и расхождения между комментариями и кодом
- предлагай правки текстом: файл, место, что изменить и почему
- не изменяй и не создавай файлы: ты консультант
Формат ответа: нумерованный список замечаний по убыванию важности, в конце — что проверить руками.Поля frontmatter, которые пригодятся: description — по нему модель находит агента, пиши, что агент делает и чего не делает; mode — subagent, primary или all, у нового агента без mode будет primary; model — своя модель вида provider/model#variant, без поля субагент наследует модель родителя; steps — лимит шагов на вызов, обрывает зацикливание; permissions — правила агента, они добавляются после глобальных и проектных, при совпадении побеждает последнее.
Права родителя и потомка
При запуске субагента проверяются две стороны. Родитель: permission subagent решает, кого вообще можно запускать, правило deny прячет агента от родителя. Потомок: работает по своим правилам, у ревьюера edit: deny — запись не пройдёт, кто бы ни просил. Отдельные права агента задаются и в конфиге, в agents.<id>.permissions.
Права ревьюера связывают только его самого, проект они не защищают: primary рядом продолжает править файлы сам. Read-only ревьюер — это контракт вызова «прочитай и посоветуй»; границы для всего проекта ставят правилами в opencode.jsonc из модуля 3.
{
"agents": {
"build": {
"permissions": [
{ "action": "subagent", "resource": "*", "effect": "deny" },
{ "action": "subagent", "resource": "reviewer", "effect": "allow" }
]
}
}
}Запуск синхронный: пока ревьюер читает файлы, primary ждёт результата. Встроенные general и explore своих субагентов не запускают; свой субагент запустит вложенного, только если его permissions разрешают subagent. Субагенты окупаются, когда нужно изолировать шумный поиск, прогнать типовую проверку с узкими правами или раздавать пакетные задачи параллельно. Точечная правка — работа самого build: вызов субагента — это новый контекст и новый прогон модели.
@reviewer сделай ревью src/routes/orders.ts и src/services/pricing.ts перед мерджем
Прочитал оба файла, смежные src/db.ts и data/db.json. Замечания по убыванию важности: 1) src/services/pricing.ts — TODO про скидку 10% при заказе от 1000 ₽ не реализован, заказ ord-003 на 1740 ₽ уходит без скидки; 2) POST /api/orders не проверяет menuId: на неизвестной позиции orderTotal бросает исключение, оно не перехвачено, клиент получит 500 вместо 400; 3) на src/routes/orders.ts нет тестов, в tests/ лежит только pricing.test.ts; 4) PATCH /api/orders/:id/status принимает статусы в любом порядке, done можно откатить в new. Файлы не менял, права read-only. Руками проверь замечание 2: POST с несуществующим menuId сейчас вернёт 500.
@reviewer примени замечание 1: реализуй скидку в src/services/pricing.ts
Менять файлы мне нельзя: edit запрещён permissions, попытка записи отклонится. Как применить замечание 1: в src/services/pricing.ts после подсчёта orderTotal добавь скидку 10% для заказов от 1000 ₽ — или позови build, правки его работа.
curl -X POST http://localhost:3000/api/orders -H "Content-Type: application/json" -d "{\"customer\":\"Тест\",\"items\":[{\"menuId\":\"nope\",\"quantity\":1}]}"Практика модуля
--- description: Код-ревьюер. Читает код, находит баги, предлагает правки текстом. Файлы не меняет. mode: subagent permissions: - action: read resource: "*" effect: allow - action: edit resource: "*" effect: deny - action: shell resource: "*" effect: deny --- Ты — код-ревьюер TypeScript-сервисов. Правила: - читай присланные файлы и смежные: роуты, сервисы, типы, фикстуры - находи баги, дыры в валидации и расхождения между комментариями и кодом - предлагай правки текстом: файл, место, что изменить и почему - не изменяй и не создавай файлы: ты консультант Формат ответа: нумерованный список замечаний по убыванию важности, в конце — что проверить руками./agents@reviewer сделай ревью src/routes/orders.ts и src/services/pricing.ts перед мерджем@reviewer примени замечание 1: реализуй скидку в src/services/pricing.tsЧерез агента reviewer исправь замечание 1: реализуй скидку в src/services/pricing.ts@explore найди все места, где читается и пишется data/db.json
Отмечено 0 из 6
Проверь себя
Вопрос 1 из 4
Шпаргалка модуля
Свои агенты
- .opencode/agents/reviewer.md
- тело файла — системный промпт, frontmatter — описание и права
- mode: subagent|primary|all
- где живёт агент; без поля новый агент становится primary
- model: provider/model#variant
- своя модель агента; без поля наследуется модель родителя
- team/reviewer.md → @team/reviewer
- вложенный путь входит в идентификатор агента
Встроенные
- @explore
- поиск и чтение кода и веб-источников, без правок
- @general
- многошаговые задачи с широкими правами, без своих субагентов
- build и plan
- primary-агенты, переключение Shift+Tab, список /agents
Права и вызов
- @reviewer
- явный адрес задачи; проза без имени — выбор за primary
- permission subagent у родителя
- кого можно запускать; deny прячет агента от родителя
- права потомка
- действуют в его дочерней сессии, проект они не защищают