Теория: Практика с OpenCode

В этом уроке мы установим и научимся работать с OpenCode. Здесь будут самые основы, которые помогут стартовать, а более глубокая и подробная работа с разбором AGENTS.md, mcp и skills вас ждет в следующем курсе.

Установка

OpenCode можно использовать в нескольких режимах, но базовый и самый полезный для разработчика сценарий - работа через CLI в каталоге проекта. В этом режиме агент получает доступ к файловой системе и командам.

Конкретные команды установки могут меняться, потому что инструмент активно развивается. Поэтому в реальной жизни надежнее всего идти в официальный репозиторий или документацию OpenCode и брать оттуда актуальный способ установки. Для курса нам важнее сам принцип: OpenCode ставится как обычный консольный инструмент, после чего его можно запускать прямо из папки проекта.

Обычно старт выглядит так:

opencode

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

Команды

У OpenCode есть несколько режимов набора. Первый - обычный диалог на естественном языке. Второй - специальные команды, которые помогают точнее управлять сессией. Команды начинаются со специальных символов /, @ и других. Несколько ключевых:

• /models: с помощью этой команды выбирается модель. Если требуется подключить аккаунт вендора, то это происходит тут же.
• /new: с помощью этой команды создается новая сессия. Принцип работы такой же как с чатом в браузере. Если меняется тема разговора, то нужно сбрасывать контекст, иначе модель будет путаться.
• @ - после этого символа начинает работать нечеткий поиск (fuzzy search) файлов по папке проекта. Может появляться в любом месте вводимого текста.

Количество команд у агентов постоянно расширяется и уже приближается к нескольким десяткам. Имеет смысл регулярно просматривать их и интегрировать в свой рабочий процесс.

Агенты (Build/Plan)

У агентов различают как минимум два режима взаимодействия, которые, по сути, сами являются агентами (в OpenCode доступны по команде /agents или по shift + tab).

Plan - это режим, в котором вы просите агента сначала подумать и разложить задачу без немедленных изменений. Например: изучить участок проекта, объяснить текущую реализацию, найти возможные точки изменений, предложить несколько вариантов решения или составить пошаговый план. Такой подход особенно полезен, когда задача не до конца понятна, затрагивает много файлов или связана с риском что-то сломать.

Build - это режим, в котором вы уже поручаете агенту реальную работу: менять файлы, писать код, добавлять тесты, запускать команды и доводить задачу до проверяемого результата. Он хорошо подходит тогда, когда рамки задачи уже понятны и вы либо сами знаете, что именно нужно сделать, либо уже прошли через стадию планирования.

┌──────────────────────────────────────────────────────────┐
  │                                                          │
  │   ┌──────────┐    "изучи, как       ┌────────┐           │
  │   │  Plan    │     устроена     ──▶ │ Build  │           │
  │   │          │     авторизация,     │        │           │
  │   │ Изучить  │     предложи план"   │ Менять │           │
  │   │ Понять   │                      │ Писать │           │
  │   │ Спла-    │    "теперь внеси     │ Тести- │           │
  │   │ нировать │     изменения    ──▶ │ ровать │           │
  │   │          │     по плану"        │        │           │
  │   └──────────┘                      └────────┘           │
  │                                                          │
  └──────────────────────────────────────────────────────────┘

На практике самые удачные сессии часто выглядят как связка этих двух режимов. Сначала Plan: "разберись, как здесь устроена авторизация и предложи план правки". Потом Build: "теперь внеси изменения по этому плану и запусти тесты". Такое разделение помогает уменьшить количество хаотичных правок и делает поведение агента более предсказуемым.

Если задача маленькая и очевидная, можно идти сразу в Build, но есть тенденция, что чем опытнее инженер в работе с агентом, тем чаще он работает через планирование. Без него даже в простых задачах агент может чудить.

Почему вообще эти режимы существуют? До их появления, агент стремился начать делать правки сразу после того как ему что-то писали, даже если это был просто вопрос. Видимо это зашито где-то в системных промптах. Даже сейчас если вы попробуете в режиме Build его что-то спросить, то он легко сорвется и сразу пойдет править код. Получается что решить эту задачу пониманием намерения пользователя не получилось и все агенты внедрили режим планирования.

Рабочий процесс

Нужно ли стараться сделать с первого раза? Нет. Более того, ожидание, что агент сразу идеально решит задачу одним сообщением - один из самых частых источников разочарования. Работа с агентами обычно эффективнее устроена как итеративный процесс: сначала вы даете задачу, потом смотрите, как агент ее понял, после этого уточняете ограничения, просите упростить решение, добавить тесты или исправить конкретный промах.

Даже хороший инженер редко проектирует сложное изменение в голове абсолютно без черновиков и промежуточных проверок. С агентом логика та же самая: первый проход нужен, чтобы быстро сдвинуться с места, а следующие - чтобы довести результат до приемлемого качества.

Нужно ли использовать английский? Нет, необязательно. Современные модели нормально понимают русский язык, и для большинства повседневных задач этого вполне хватает. Можно писать по-русски, если так вам быстрее и естественнее формулировать запрос. Для старта это даже полезно: меньше лишней нагрузки и проще сосредоточиться на самой задаче, а не на переводе своих мыслей.

Базовый рабочий процесс в агенте выглядит так. Выбираем нужную модель, затем переходим в режим планирования и просим что-то сделать попутно указывая на нужные файлы через @, он сам их развернет в полные пути.

оптимизируй производительность функции isPrime в файле app/lib/math.ts

Дальше агент либо задаст уточняющие вопросы либо предложит план. Соглашаться с ним не обязательно, в процессе общения можно задавать уточняющие вопросы, просить показать примеры кода и так далее. Если вы решили полностью сменить тему, то лучше делать это в новой сессии через /new, чтобы очистить контекст. Если план вас устраивает, переходите в режим исполнения и говорите ему запускать план на выполнение.

Что если в процессе появились доп мысли? Пишите их сразу без остановки текущего процесса, агенты их складывают в очередь и регулярно считывают. Причем это может быть как в режиме планирования, так и в режиме исполнения. Если вы увидели что его понесло не туда, прямо сразу накидывайте правки. Либо если это слишком сильно не туда, вы можете остановить его нажав esc.