Чат с LLM быстро упирается в потолок: модель не знает контекст проекта, не видит код проекта и каждый раз требует заново объяснять, что от неё нужно. Аналитик из Selectel Арина описывает OpenCode как оболочку, в которой модель получает доступ к файлам, инструкциям, локальным инструментам и MCP-серверам. Ниже её рекомендация: не собирать «всё и сразу», а пройти шесть шагов и на каждом проверить, что агент реально работает.
Сначала подключите модель, а уже потом правила
Цель первого шага — добиться связки OpenCode → выбранная LLM → ответ. Для личных задач подойдёт внешний провайдер из списка, для рабочих — то, что разрешено в компании. Если развёрнута локальная модель, её можно подключить как провайдер: указать ID, имя, базовый URL, ключ и доступные модели. Проверка простая: попросите агента прочитать README текущего проекта и кратко объяснить, что делает сервис.
Общие настройки отдельно от проекта
Автор советует сразу разделить конфигурацию на два уровня. В ~/.config/opencode/ лежат общие настройки пользователя: провайдеры, разрешения, универсальные инструкции и навыки, которые используются во всех проектах. В корне репозитория или в отдельной рабочей папке находится то, что относится к конкретному проекту: архитектурные ограничения, команды сборки и тестов, документация и навыки для конкретного проекта. Так общие правила не дублируются между проектами, а проектные не превращаются в один огромный промпт.
Минимальный AGENTS.md: только то, что нужно почти всегда
Файл AGENTS.md стоит держать коротким. Туда уходят правила, которые должны работать почти всегда: не придумывать отсутствующие факты, перед изменением кода изучать связанные реализации, при неоднозначности задавать уточняющие вопросы, не выполнять коммит, пуш и слияние без явного разрешения. Чем больше файл, тем сложнее его поддерживать и тем легче в нём запутаться.
Skills только под повторяемые сценарии
Навык — это инструкция-сценарий, которую OpenCode подключает по описанию. Если один и тот же алгоритм приходится объяснять агенту снова и снова, его пора вынести в skill. Например, code-review: изучить изменённые файлы, проверить связанные вызовы, найти регрессии, проконтролировать обработку ошибок и наличие тестов, вывести найденные проблемы. Для навыка нужен файл .opencode/skills/<name>/SKILL.md с полями name и description. По ним агент решает, когда skill применять.
Разные агенты, разные права
Когда конфигурация разрастается, полезно разделить роли: developer, reviewer, researcher, docs. У них отличаются доступные инструменты, модель, промпт, разрешения и навыки. Агент-ревьюер может работать только в режиме чтения, разработчик имеет доступ к изменению файлов. Это безопаснее, чем давать одному универсальному агенту максимальные права.
Внешние источники только когда видно, чего не хватает
Подключать Jira, Confluence, GitLab, GitHub и внутренние API через MCP или REST имеет смысл тогда, когда понятен конкретный пробел. У автора именно с MCP возникла проблема: схема инструментов от GitLab-сервера не совпадала с тем, что ожидал OpenCode, и дополнительная обёртка не помогла. При этом штатный GitLab REST API закрыл все задачи: поиск проекта, чтение файлов, маршруты, модели, миграции. Вывод простой: если REST API или локальный скрипт решает задачу стабильнее, лучше использовать его и не усложнять систему на ровном месте.
Ограничения технические, а не текстовые
Это отдельный акцент в статье. Инструкцию «не делай пуш» модель может проигнорировать: неправильно понять запрос, потерять часть контекста. Технический запрет обойти уже не получится. Поэтому принцип минимально необходимых прав: токены только для чтения там, где не нужно писать; режим запроса для редкого использования командной строки; запрет там, где работа с файлами не нужна. Секреты держать в отдельном файле настроек, а агенту отдавать только через переменные окружения. Переменные защищают от случайного попадания в репозиторий, но не заменяют полноценное хранилище секретов.
Как применить
- Подключите LLM и проверьте связь простым запросом про README текущего проекта.
- Сделайте минимальный
~/.config/opencode/opencode.json:edit: запрос,bash: запрос,share: отключено. Этого хватит для первого запуска. - В корне проекта заведите короткий AGENTS.md: не придумывать факты, изучать код до правок, уточнять неоднозначное, не делать коммит и пуш без разрешения, после изменений перечислять риски.
- Проверьте агента на нескольких обычных запросах про реальный код проекта. Не создавайте навыки заранее, пусть они появятся из повторяющихся сценариев.
- Первый навык заведите под самую частую задачу, например code-review: изучить изменения, проверить вызовы и регрессии, найти проблемы, не предлагать правок мимо задачи.
- Ограничения задавайте технически:
git push *: запрет,git commit *: запрет,bash *: запрос, токены read-only и через переменные окружения, не в workspace.