OpenCode Best Practices

Раздел концентрирует практики, которые помогают удерживать OpenCode продуктивным, предсказуемым и дешёвым. Большая часть принципов опирается на гайд «OpenCode: Everything You Need to Know» и практику работы с репозиторием ai-agent-codex.

1. Модельная стратегия через Zen

Zen — реальный control-plane для моделей. Без явной стратегии команды сжигают бюджет на эксперименты. Рабочая схема:

1. Фиксируем baseline-модель (например, claude-sonnet-4.6) прямо в opencode.json.
2. Добавляем fallback-дешёвый профиль (например, qwen-2.5-coder) для задач «прочитай/объясни».
3. Включаем явные лимиты токенов на агентов.
4. Логируем стоимость с помощью opencode stats после каждого крупного цикла.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "claude-sonnet-4.6",
  "agent": {
    "build": {
      "model": "claude-sonnet-4.6",
      "max_tokens": 12000
    },
    "read-only": {
      "model": "qwen-2.5-coder",
      "max_tokens": 4000
    }
  }
}

Периодически сверяйте фактические траты с калькулятором opencode.ai/pricing. Это то, что советует и внешний гайд.

2. Plan/Build как обязательная дисциплина

Plan и Build — не просто режимы TUI. Это разные агенты. Лучшие практики:

• Любая работа начинается: [Plan] Сформулируй подход. Главное — фиксация стратегии в истории.
• Build запускается только после того, как Plan вернул шаги/риски. Никаких «сразу сделай».
• Длинные циклы разбивайте: Plan → Build → Plan (ревизия) → Build. Это особенно важно для больших миграций.
• Связывайте Plan с docs/specs: «Если меняются правила — обнови spec перед Build».

3. AGENTS.md и instructions как единый контроль

Внешний гайд подчёркивает важность правил. Практическая версия:

4. Skills ради повторяемости

Skills превращают «памятку» в команду. Минимальный стэк skill-ов:

• /review — чек-лист ревью кода (линейность, перф, security).
• /deploy — скрипт: тесты, build, деплой.
• /tdd — сценарий «напиши тест → сделай минимум для прохождения».
• /postmortem — формализованный шаблон RCA.

# .opencode/skills/review.md
---
name: "Review"
description: "Security-first code review"
tools: ["read", "ask"]
---

# Review Checklist
1. Security regressions?
2. Cost impact?
3. Tests updated?
4. Docs/specs обновлены?

Skill должен ссылаться на реальные файлы (spec, README). Тогда его смысл не размывается.

5. Cost и качество — измеряемые метрики

OpenCode позволяет управлять стоимостью и качеством прямо из TUI:

• !opencode stats --since 24h — обязательная команда перед ретроспективой.
• !git diff | /review — ревью по факту изменений, а не «примерно вот тут».
• Подключайте logs/ и scripts/tooling/ в AGENTS.md, чтобы агент имел право собирать метрики.
• Для каждодневных чеков делайте skill /healthcheck: проверка линтеров, тестов, opencode stats.

6. MCP и внешние инструменты — только по назначению

Лучшие практики из главы 06 плюс из внешнего гайда:

1. Каждый MCP-сервер описан в отдельном README (URL, auth, токены).
2. В opencode.json MCP глобально выключены, включаются на уровне агента.
3. Для OAuth всегда используйте opencode mcp auth, не храните секреты в JSON.
4. Регулярно удаляйте неиспользуемые MCP: opencode mcp list → disable.

Когда MCP реально нужен:

• Внутри репозитория нет данных, но вопрос повторяется (например, production-инциденты или внешние API specs).
• Интеграция используется чаще 3‑4 раз в неделю и вручную повторять шаги дороже.
• Доступ можно формализовать через один сервер (observability, knowledge base, корпоративные сервисы).
• Есть отдельный владелец MCP, который следит за обновлением токенов и схемы инструментов.

7. Team onboarding

Чтобы люди не учились с нуля:

• Добавьте в README блок «Как запускать OpenCode» и ссылку на этот гайд.
• Создайте skill /onboard, который выдаёт список команд/шагов.
• Week-by-week план (по мотивам внешнего гайда) держите в docs/specs/open-code-learning.md.
• Минимально требуемые команды: /connect, /init, Plan/Build, /review, /deploy.

8. Постановка задач и «вайбкодинг» без переделок

OpenCode хорошо справляется с vibe coding, если задача формализована. Схема «цель → ограничения → ресурсы» экономит токены и нервы.

• Цель: одна фраза «что меняется для пользователя/системы». Пример: «Дать аналитикам экспорт отчёта в CSV».
• Ограничения: перечислите 3‑5 условий (performance, security, сроки, затронутые сервисы).
• Ресурсы: ссылки на spec, existing PR, макеты. Без привязки к файлам агент тратит время на поиск.
• Декомпозиция: в Plan просите три уровня — «архитектурные шаги», «технические подшаги», «проверки». Это снижает шанс, что Build перепрыгнет проверки.
• Фиксация результата: требуйте от агента выводить финальный план действий в конце с пометкой «Done/Blocked». Это из внешних гайдов по OpenCode, и это реально сокращает переделки.

9. Когда подключать дополнительных агентов

По умолчанию Plan/Build хватает. Специализированные агенты нужны, когда задача выходит за рамки типового пайплайна:

• Безопасность/quality: security-reviewer с read-only правами проверяет Plan перед Build.
• Cost control: отдельный cost-analyst получает доступ к opencode stats и метрикам, чтобы не перегружать Build.
• Интеграции: MCP-heavy агент (например, context7-analyst) включается только когда запросы требуют внешнего поиска.
• Тяжёлые миграции: architect-agent фиксирует архитектурные решения и рерайтит AGENTS.md, до того как Build начинает менять код.

Критерий: если задача регулярно требует больше двух переключений Plan↔Build или вовлекает внешний источник, выделите агента. Иначе — держите всё в базовом цикле.

10. Насколько подробно описывать skills

Излишне абстрактные skills бесполезны, слишком детальные — превращаются в документацию. Баланс:

1. Триггер: одна строка «используй skill, когда нужен …».
2. Шаги: не более 5‑7 пунктов, каждый с конкретным действием (!npm test, «обнови docs/specs/feature.md»).
3. Критерии успеха: перечислите, что должно быть в ответе (логи, ссылка на коммит, список файлов).
4. Контекст: ссылка на spec или template, чтобы skill не дублировал информацию.
5. Формат: если нужен конкретный Markdown, пропишите его внутри skill (например, блок таблицы для RCA).

Skills можно делать каскадно: высокий уровень (/deploy) вызывает более мелкие (/test, /build). Так поддержка проще.