Арина Болонова

Когда я впервые начала использовать AI в работе, сценарий был довольно стандартным: открыть чат, вставить текст, сформулировать запрос, получить ответ. Это удобно, но возможности довольно быстро упираются в потолок. Модель не знает контекст ваших проектов, не видит документацию и код, не понимает принятые в команде правила и каждый раз требует заново объяснять, что именно вы от нее хотите. Следующим моим шагом стало собрать вокруг модели рабочую среду. В моем случае такой средой стал OpenCode. Хотя этот агент в первую очередь ассоциируется с разработкой, его можно использовать гораздо шире. По сути, это оболочка, в которой LLM получает доступ к файлам, инструкциям, локальным инструментам, API и MCP-серверам, а затем использует все это для решения задач конкретного пользователя. В этой статье я покажу не столько «как установить OpenCode», сколько как организовать вокруг него рабочее пространство, чтобы агент выдавал более стабильный результат и действительно снимал часть рутинной работы. Подключаем модель OpenCode поддерживает множество моделей от разных провайдеров. Для личных и pet-проектов можно подключить удобного внешнего провайдера. В OpenCode в настройках доступен список популярных провайдеров, для которых даже не надо ничего настраивать — просто скопируйте API ключ из вашего любимого сервиса и пользуйтесь. А вот для рабочих проектов стоит ориентироваться на правила вашей компании: какие модели разрешены, можно ли передавать код и внутреннюю документацию во внешние сервисы и какие данные считаются конфиденциальными. Если у вас в компании или на личной машине развернута локальная LLM, которая точно не передаст все ваши конфиденциальные данные злоумышленникам, то вы можете подключить ее в OpenCode. Для этого нажмите Настройки → Провайдеры → Выбрать провайдера → Подключить. Заполните поля: ID провайдера, Отображаемое имя, Базовый URL, Ключ API, Доступные модели. Дальнейшие настройки агента практически не зависят от конкретного провайдера или мощности модели. Цель первого этапа — подключить «мозги», куда дальше будут загружаться знания. Поэтому на этом шаге вы можете подключить любую удобную модель или даже использовать встроенные в OpenСode модели, коротким сообщением проверив, что агент отвечает и не выдает ошибку. Разделяем global config и настройки проекта Следующим шагом я рекомендую сразу разделить конфигурацию на два уровня. Global config Общие настройки пользователя: Сюда удобно вынести провайдеров и модели, общие разрешения (permissions), универсальные инструкции и skills, используемые во всех проектах. Пример opencode.json: Project config В репозитории или отдельном workspace остается то, что относится к конкретному проекту: Здесь прописываются архитектурные ограничения, команды сборки и тестирования, документация, инструкции по работе с репозиторием и project-specific skills. Такое разделение позволяет глобальной конфигурации не дублироваться между проектами, а проектным правилам — не превращаться в один огромный общий промт. AGENTS.md Файл AGENTS.md лучше использовать для правил, которые должны применяться почти всегда. К ним относятся требования не придумывать несуществующие факты, перед изменением существующего кода изучать связанные реализации, не выполнять commit, push и merge без разрешения, а при неоднозначности задачи — задавать уточняющие вопросы. Не стоит складывать сюда все инструкции проекта. Чем объемнее AGENTS.md, тем сложнее поддерживать его актуальность и понимать, какие правила действительно важны. Skills Если один и тот же алгоритм приходится регулярно объяснять агенту, его лучше вынести в skill. Например: Так, skill для code review может задавать последовательную проверку: сначала агент изучает измененные файлы, затем проверяет связанные вызовы, ищет возможные регрессии, контролирует обработку ошибок и наличие тестов, а в конце выводит найденные проблемы и рекомендации. Commands Commands удобны, когда важна не только инструкция, но и четкая последовательность действий. Например, команда /fix-bug может запускать следующий алгоритм: В результате не приходится каждый раз описывать один и тот же сценарий вручную. По одной простой команде агент уже сам понимает последовательность действий и начинает их выполнение. Разные агенты для разных задач Если конфигурация разрастается, полезно разделить роли, создав отдельных агентов, выполняющих ограниченный набор задач. Например, набор может выглядеть так: developer, reviewer, researcher и docs. У них будут отличаться доступные инструменты, модель, промпт, permissions и skills. Так, скажем, агент reviewer может работать только в режиме read-only, а developer — иметь доступ к изменению файлов. Это удобнее и безопаснее, чем давать одному универсальному агенту максимальные права. Источник. Подключаем документацию и рабочие системы До этого момента агент знает только то, что находится в его workspace. Но основная рабочая информация обычно распределена между таск-трекером, базой знаний, Git-репозиториями, API и внутренними сервисами. Можно каждый раз копировать данные вручную, но тогда значительная часть преимуществ агента теряется. Через MCP или API ему можно дать доступ к дополнительным источникам знаний, включая GitLab, GitHub, Jira, Confluence, внутренние API и сервисы документации. Тогда становится возможен сценарий вроде такого: На собственном опыте с GitLab я убедилась, почему не стоит строить всю архитектуру исключительно вокруг MCP. Сначала я пыталась подключить его через MCP-сервер. В моей конфигурации на момент настройки сервер запускался, но при получении списка инструментов (tools) возникала проблема: возвращаемая схема не соответствовала той, которую ожидал OpenCode. Я попробовала нормализовать ее через дополнительный wrapper, но это не сработало, и я решила, что уходить в долгую борьбу с MCP нет никакого смысла. К тому же штатный GitLab REST API уже закрывал все мои задачи: поиск проекта, чтение файлов, просмотр структуры репозитория и README, анализ маршрутов (routes), моделей и миграций. Вывод тут простой: если REST API или обычный локальный скрипт решает задачу быстрее и стабильнее, лучше использовать их и не усложнять систему на ровном месте. Код — тоже источник контекста Один из самых полезных сценариев работы с OpenCode лично для меня — возможность изучить реальную кодовую базу перед ответом. Например, агент может самостоятельно проверить существующие модели данных, используемые поля, валидации, API endpoints, обработку ошибок, существующие тесты и ограничения legacy-кода. Вместо запроса в формате «Вот DTO, вот контроллер, вот модель, а теперь скажи, как добавить новое поле» можно сформулировать задачу так: В таком случае код используется как источник фактов, на которые можно опираться при описании нового функционала. В следующей своей статье я как раз хочу подсчитать, насколько получилось ускорить и оптимизировать работу по анализу требований за счет активного использования агента. Спойлер: цифры получаются очень даже впечатляющими! Ограничения лучше задавать технически Самая важная часть настройки рабочего агента — ограничения. И здесь есть принципиальное различие: требование «не делай push» остается текстовой инструкцией, которую модель в целом может проигнорировать, тогда как технический запрет выполнять git push она обойти уже не сможет. Источник. Инструкцию LLM может нарушить: неправильно понять запрос, потерять часть контекста или выбрать неправильное действие. Поэтому я придерживаюсь принципа минимально необходимых прав: при необходимости читать GitLab или анализировать Jira — использовать токены и доступы read-only. Для редкого использования shell выставлять режим ask. А при отсутствии работы с файлами устанавливать deny (ниже будет приложен пример кода). Не храните токены в workspace Еще одно базовое правило безопасности: секреты нужно держать в отдельном файле или конфиге, а агент должен обращаться к ним только через переменные окружения. Например, в Windows настройка будет выглядеть так: После этого скрипты и интеграции используют имя переменной только при необходимости обращения к конкретному сервису. Но здесь тоже важно не поддаваться ложному ощущению безопасности: переменные окружения защищают ключи от случайного попадания в репозиторий, но не заменяют собой полноценное хранилище секретов. Любой процесс, у которого есть доступ к переменной, потенциально может ее прочитать. Поэтому в связке с переменными окружениями желательно использовать комплексную защиту: минимально необходимые права (scopes); отдельные токены для разных сервисов или агентов; доступ read-only везде, где нет необходимости для более высокого уровня прав; отсутствие секретов в логах; permissions самого OpenCode; правила вашей компании — учитывайте внутренние правила и политики безопасности. Только так возможно создать безопасный контур для работы агента и не попасть на радар бдительных коллег из отдела ИБ. Как я бы настраивала OpenCode с нуля сейчас Если вы раньше не работали с AI-агентами, лучше не начинать сразу с MCP, нескольких агентов и десятка skills. Соберите минимальную конфигурацию, проверьте ее на реальной задаче и только потом добавляйте инструменты. Шаг 1. Подключите LLM Сначала достаточно добиться простой цепочки: OpenCode → выбранная LLM → ответ. На этом этапе проверьте, что OpenCode видит текущий проект и может ответить, например: Шаг 2. Добавьте базовый global config Общие настройки OpenCode хранятся в: ~/.config/opencode/opencode.json. Для старта достаточно минимальной конфигурации: Так OpenCode будет спрашивать подтверждение перед изменением файлов и выполнением shell-команд, а автоматический sharing будет отключен. Если хотите сразу запретить потенциально опасные Git-команды, добавьте: Шаг 3. Создайте минимальный AGENTS.md В корне проекта добавьте файл AGENTS.md и дайте стартовую инструкцию: Этого уже достаточно, чтобы задать базовое поведение агента. Шаг 4. Проверьте агента на реальной задаче Не создавайте skills заранее. Сначала попробуйте несколько обычных запросов: Если один и тот же алгоритм приходится объяснять повторно — тогда его уже стоит вынести в skill. Шаг 5. Создайте первый skill Например, для code review создайте: И положите в SKILL.md: OpenCode автоматически обнаруживает skills в .opencode/skills/ /SKILL.md. Для skill нужны name и description, чтобы агент мог корректно определить, когда его использовать. Шаг 6. Подключите внешние источники Когда станет понятно, какой информации агенту не хватает, добавляйте конкретную интеграцию. Каждая система закрывает свой пласт знаний: Jira дает контекст по задачам, Confluence — по документации, а GitLab или GitHub открывают доступ к репозиторию. Если же агенту нужно дотянуться до внутренних сервисов компании, подтяните их через REST API или MCP. В итоге рабочая архитектура полноценного самостоятельного агента выглядит так: Этого уже достаточно, чтобы перейти от обычного чата с LLM к агенту, который знает правила проекта, умеет самостоятельно собирать локальный контекст и может выполнять повторяемые задачи. А в остальном пробуйте новые сценарии, ищите или пишите сами полезные скиллы и помните о безопасности, потому что искусственный интеллект даже проще обмануть, чем естественный!

Арина Болонова

Материалы автора

Как превратить чат с LLM в рабочего AI-агента с помощью OpenCode

Как разработчику и аналитику понимать друг друга при чтении ТЗ