Командные процессы
Настроить файлы мало. Чтобы OpenCode действительно начал приносить пользу, команде нужен понятный operating model: когда работать в plan, когда в build, когда обновлять specs, кого вызывать из subagents и какие ошибки не допускать в ежедневной работе.
Базовый цикл: Plan → Spec → Build → Verify
Для большинства нетривиальных задач хорошо работает один и тот же каркас. Сначала задача анализируется в безопасном режиме, затем при необходимости фиксируется в спецификациях, потом реализуется минимальный рабочий slice и только после этого проходит через верификацию. Этот цикл важен тем, что отделяет intent от implementation.
- Открыть задачу в plan и прояснить решение.
- Если меняется контракт, архитектура или продуктовый сценарий — обновить
docs/specs. - Переключиться в build и сделать минимальный рабочий slice.
- Проверить diff, тесты, поведение и сопутствующую документацию.
Почему это работает
Когда intent сначала формализуется отдельно, агент меньше импровизирует во время самой реализации. Это снижает число лишних ходов и повышает предсказуемость результата.
Когда оставаться в plan
| Ситуация | Почему не стоит сразу идти в build |
|---|---|
| Архитектура неясна | Нужно сначала понять, в каком слое должно жить изменение. |
| Задача затрагивает новые контракты | Нужно сформировать assumptions и acceptance criteria до правок кода. |
| Планируется широкий рефакторинг | Есть риск начать не с того места и разнести лишние изменения по кодовой базе. |
Если команда привыкает использовать plan только как “режим для новичков”, то она теряет один из самых полезных инструментов OpenCode. На практике именно senior-задачи чаще всего требуют этого режима.
Как должна ощущаться маршрутизация по ролям
Routing не должен превращаться в сложную церемонию. Идея в том, чтобы у проекта были понятные дорожки для разных типов задач. Если меняется data contract, первым делом нужен один тип мышления. Если меняется frontend-facing API, нужен другой. В этом и помогает слой .opencode/agents.
Изменение требований
Сначала system-analyst или project-manager, потом уже инженерная реализация. Это уменьшает риск “закодировать неопределенность”.
Работа с пайплайном и данными
data-engineer как главный исполнитель, при необходимости с подключением соответствующих skills по SQL, dbt и ETL.
Specs-first development с OpenCode
Очень полезная привычка — не держать значимые проектные решения только в переписке с агентом. Если задача меняет продуктовый контракт, интерфейсный сценарий, схему данных или архитектурную ответственность слоя, это должно попадать в docs/specs. Тогда OpenCode может учитывать это решение и в следующих сессиях.
- Меняется API contract — обновите spec.
- Меняется data flow или grain данных — обновите spec.
- Появляется новый продуктовый сценарий — обновите spec.
- Исправляется локальный баг без изменения intent — spec чаще всего не нужен.
Что должен получать новый инженер в первый день
Если вы внедряете OpenCode командно, самый сильный эффект достигается не “магическими промптами”, а качественным onboarding package.
- Репозиторий с уже закоммиченными
AGENTS.mdиopencode.json. - Короткая инструкция: как запустить
opencode, где лежат specs и как работаетplanvsbuild. - Список project subagents и краткое объяснение, кого и когда использовать.
- Набор типовых промптов или custom commands для самых частых сценариев.
Модель зрелости внедрения
| Стадия | Что уже есть |
|---|---|
| Stage 1 | /init и базовый AGENTS.md |
| Stage 2 | opencode.json, instructions и docs/specs |
| Stage 3 | Project-specific agents в .opencode/agents |
| Stage 4 | Curated skills и явная permission policy |
| Stage 5 | Повторяемые командные процессы, onboarding и устойчивый operating model |
Антипаттерны, которых стоит избегать
Антипаттерн
Один гигантский prompt на всё
Когда весь интеллект проекта запихивают в один файл и не используют силу отдельных layers: specs, skills, commands и role-based agents.
Антипаттерн
Никакой маршрутизации
Когда любые задачи идут в один и тот же build-agent без role clarity и без task guardrails.
Антипаттерн
Полное доверие build-mode
Когда команда почти не пользуется plan и оформляет intent уже постфактум, после правок кода.
Антипаттерн
Сверхусложнение в первый день
Когда создают десятки агентов и skills до того, как стало понятно, какие из них реально нужны в работе.
Финальный вывод
Коротко
Сильный OpenCode-проект — это не набор красивых файлов, а договоренность о способе работы. Где хранится intent, как агент получает инструкции, какие роли доступны, что считается безопасным действием и как команда движется от анализа задачи к проверенному изменению.