Агенты OpenCode: файлы, frontmatter и четыре готовых примера

Введение

Это сторона OpenCode материала «Создание ИИ-агентов»: точные файлы, поля и команды. Если вам нужна только ролевая модель triage, builder и reviewer, сначала прочитайте ту страницу. Здесь мы связываем их в .opencode/agents/, закрепляем бесплатную модель OpenCode, GPT 6 Luna или Claude Opus 5.5 за каждой ролью и доказываем, что роли действительно работают.

Куда класть агентов

Та же тройка моделей, что и у навыков, но здесь за каждой ролью закрепляется своя модель. Личные агенты идут в глобальный каталог, командные — в репозиторий и коммитятся.

Встроенные агенты, которые можно переопределить, переиспользовав id: build (основной программист, по умолчанию), plan (основной, без правок проекта), general (субагент для исследования), explore (субагент только для чтения). Скрытые title, summary, compaction занимаются обслуживанием и не могут быть выбраны. Полное дерево со ссылками — в разделе «Реальный скелет проекта».

Как собрать агента

Markdown-агент — это frontmatter плюс тело. Frontmatter принимает те же поля, что и JSON-карта. Тело становится системным промптом. Пример файла .opencode/agents/reviewer.md:

mkdir -p .opencode/agents

vi .opencode/agents/reviewer.md

--- description: Reviews changes for correctness and regressions mode: subagent model: opencode/claude-opus-5-5 steps: 8 color: "#ff6b6b" permissions: - action: edit resource: "*" effect: deny --- Review the current changes. List findings in severity order.

Поля, которые важны на практике:

JSON-форма для быстрых переопределений без файла агента, в opencode.jsonc в корне проекта:

vi opencode.jsonc

{ "$schema": "https://opencode.ai/config.json", "default_agent": "build", "agents": { "build": { "permissions": [ { "action": "shell", "resource": "git push *", "effect": "deny" } ] } } }

Следующие конфиги сливаются: скаляры заменяются, правила разрешений добавляются, поэтому глобальный allow плюс deny агента дают deny. Субагент использует свои разрешения, а не подмножество родителя. Управлять тем, каких детей может запускать родитель, можно в том же opencode.jsonc:

{ "agents": { "orchestrator": { "permissions": [ { "action": "subagent", "resource": "*", "effect": "deny" }, { "action": "subagent", "resource": "reviewer", "effect": "allow" } ] } } }

Реальный скелет проекта

Сторона агентов того же демо-проекта из раздела «Скелет проекта». Вывод tree, каждый элемент ссылается на главу, где он объяснён:

my-app/ ├── opencode.jsonc ├── .opencode/agents/ │ ├── reviewer.md │ ├── builder.md │ ├── triage.md │ └── team/orchestrator.md ├── .opencode/skills/ │ ├── api-review/ │ │ └── SKILL.md │ └── test-writer/ │ └── SKILL.md ├── .opencode/commands/ │ ├── review.md │ └── build-feature.md └── AGENTS.md

Читайте это как роли: reviewer — судья только для чтения на Opus, builder — ежедневный водитель на Luna, triage — сортировщик входящих на бесплатной модели, orchestrator раздаёт работу детям. Команды выбирают агента и модель одним нажатием. Навыки рядом дают чек-листы, которые загружает каждая роль.

Четыре готовых агента

Четыре файла, которые можно положить в .opencode/agents/ уже сегодня. Они повторяют разделение моделей из раздела «Модели, которые важны»: дешёвый triage, стандартная сборка, топовое ревью и один оркестратор, который связывает их вместе. Как они делят один проект с ограниченными навыками, показано в разделе «Три модели, один проект».

Пример 1 — ревьюер на Opus, только чтение. Файл .opencode/agents/reviewer.md, id reviewer. Финальный проход по staged-диффам, никогда не правит:

mkdir -p .opencode/agents

vi .opencode/agents/reviewer.md

--- description: Final correctness and security pass over staged diffs mode: subagent model: opencode/claude-opus-5-5 steps: 8 permissions: - action: edit resource: "*" effect: deny - action: shell resource: "*" effect: deny - action: skill resource: "*" effect: deny - action: skill resource: api-review effect: allow --- Review the staged diff. Load api-review first. Report bugs first in severity order with file and line. Verdict: ship, fix first, or block. Do not edit files.

Запуск: Use the reviewer subagent to review my staged changes. Он загружает только api-review, поэтому вывод остаётся в форме рубрики даже на больших диффах.

Пример 2 — builder на Luna, ежедневный водитель. Файл .opencode/agents/builder.md, id builder. Дешёвый, ровный, может править и тестировать, но никогда не пушит:

vi .opencode/agents/builder.md

--- description: Implements small features with tests on GPT 6 Luna mode: primary model: opencode/gpt-6-luna permissions: - action: shell resource: "*" effect: ask - action: shell resource: "git status *" effect: allow - action: shell resource: "git diff *" effect: allow - action: shell resource: "npm test *" effect: allow - action: shell resource: "git push *" effect: deny --- Implement the requested change in small steps. After each edit run the narrowest test command and show the diff. Stop after two failing attempts and report what is missing.

В паре с @test-writer для покрытия: With builder, add pagination to orders and cover it with test-writer.

Пример 3 — triage на бесплатной модели, сортировщик входящих. Файл .opencode/agents/triage.md, id triage. Бесплатный, быстрый, с ограничением шагов, объясняет код, не меняя его:

vi .opencode/agents/triage.md

--- description: Explains code and sorts small tasks without editing mode: primary model: opencode/deepseek-v4.1-flash-free steps: 6 permissions: - action: edit resource: "*" effect: deny - action: shell resource: "*" effect: deny --- Explain the relevant code with short examples. Sort the request into docs, small fix, or needs-build. Propose the next agent: builder for fixes, plan for features. Do not edit files. Never handle secrets.

Начинайте каждое утро с triage, повышайте только то, чему нужны инструменты: With triage, explain src/auth.ts login flow and route the refresh bug. Приватность бесплатного тарифа остаётся в безопасности, потому что он никогда не трогает файлы .env.

Пример 4 — оркестратор, который раздаёт работу. Файл .opencode/agents/team/orchestrator.md, id team/orchestrator. Планирует на Luna, отдаёт ревью Opus, исследование — general:

mkdir -p .opencode/agents/team

vi .opencode/agents/team/orchestrator.md

--- description: Plans a feature then fans out to builder and reviewer mode: primary model: opencode/gpt-6-luna permissions: - action: subagent resource: "*" effect: deny - action: subagent resource: "builder" effect: allow - action: subagent resource: "reviewer" effect: allow - action: subagent resource: "explore" effect: allow --- Plan the feature in three bullets: files, schema, tests. Then ask explore to map unknowns and builder to implement step one. Finish by asking reviewer for a verdict. Report the three results.

Запуск: With team/orchestrator, plan cursor pagination for orders. Родитель остаётся доступным, пока фоновые дети работают, а результаты возвращаются в родительскую сессию.

Команды, которые выбирают агентов

Файл .opencode/commands/review.md закрепляет ревью на Opus в фоне, файл .opencode/commands/build-feature.md закрепляет сборку на Luna в текущей сессии:

--- description: Review staged changes on Opus agent: reviewer model: opencode/claude-opus-5-5 subagent: true --- Review this diff for bugs, security and missing tests: !`git diff --cached`

--- description: Build one feature step on Luna agent: builder model: opencode/gpt-6-luna subagent: false --- Build $ARGUMENTS in one small step with tests. Show the diff and stop for review.

Запуск: /review и /build-feature cursor pagination for orders. Модель команды главнее модели агента, а модель агента главнее модели сессии, поэтому явные закрепления всегда выигрывают.

Заставить агентов работать

Правильный файл агента сам по себе ничего не делает. Должны произойти ещё две вещи: ассистент должен загрузить конфиг проекта, а человек или команда должен выбрать роль. Большинство заявок «агентов создали, агенты не используются» — это одно из двух, либо id модели, который перестал разрешаться.

Разрешения — ловушка, которая выглядит как сломанная модель: правила упорядочены, побеждает последнее совпадение. Агент, которому запретили единственный нужный инструмент, отвечает извинением вместо ошибки, а винят модель. Перечитайте правила перед первым замером.

Цикл агента

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

Логируйте каждую итерацию. Когда агент ведёт себя странно, трасса за секунды говорит, что сломалось: планировщик, инструмент или инструкции. Пример промпта-трассы, который работает на всех трёх моделях: Find where request timeouts are configured, change the default to 30 seconds, run the relevant tests — обычно это grep, read, edit, shell именно в таком порядке.

Инструменты делают агента

Модель с пятью острыми инструментами бьёт более умную модель с одним тупым. Проектируйте инструменты как API для младшего коллеги: одна цель на инструмент, строгая проверка входа и сообщения об ошибках, которые говорят, что попробовать дальше. В OpenCode фиксированное ядро — read, glob, grep, edit, write, shell, webfetch, websearch, question, skill, subagent, execute плюс инструменты MCP с именем server_tool.

Ограничивайте их по ролям. Пример тройки: triage запрещает edit и shell; builder разрешает git status, git diff и тестовую команду, спрашивает про остальное, запрещает git push; reviewer запрещает edit и shell и загружает один навык ревью. Полный каталог и подключение MCP — в материале «MCP: настоящие инструменты для ИИ-ассистентов».

Решение проблем

Автор статьи: Клавдия Кондакова

Изображение баннера