Быстрый старт

Эта глава нужна, чтобы за короткое время перевести репозиторий из состояния «OpenCode просто установлен» в состояние «у проекта уже есть первый нормальный OpenCode-слой». Речь не о финальной настройке, а о минимально зрелом старте.

Шаг 1. Установить OpenCode

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

curl -fsSL https://opencode.ai/install | bash

# альтернативный вариант
npm install -g opencode-ai

Если у вас есть внутренняя документация для команды, рядом имеет смысл сразу указать, какой метод считается canonical. Например: «используем install script на macOS/Linux, а npm — как fallback».

Шаг 2. Подключить провайдера

Дальше нужно связать OpenCode с модельным провайдером. В официальной документации основным user-facing способом является /connect внутри TUI. Это хороший старт, потому что избавляет от ручной возни с первичным провайдерским конфигом.

opencode
/connect

На этом этапе уже можно задавать вопросы по коду, но OpenCode пока ничего не знает о проектных договоренностях. Поэтому следующая задача — не «сразу просить реализацию фичи», а сделать проектную инициализацию.

Шаг 3. Открыть репозиторий и выполнить /init

Команда /init анализирует текущую кодовую базу и создает или обновляет AGENTS.md. Это первый шаг, который превращает OpenCode из просто инструмента в инструмент, знающий контекст проекта.

opencode /path/to/project
/init

Очень важно понимать: /init создает основу, но не финальную версию правил. Получившийся AGENTS.md почти всегда нужно редактировать вручную. Нельзя просто принять его как истину и забыть о нем.

Шаг 4. Превратить AGENTS.md в реальный проектный контракт

Хороший AGENTS.md должен объяснять агенту, как вообще мыслить об этом репозитории. Обычно в нем стоит описать:

• цель проекта и основные priorities;
• структуру репозитория и назначение ключевых директорий;
• архитектурные правила и layer responsibilities;
• какие роли или артефакты использовать для разных видов задач.

# Пример каркаса

## Primary Goal
Опишите, что делает проект и какую бизнес-цель он решает.

## Expected Repository Structure
- apps/
- src/
- docs/specs/
- .opencode/agents/
- .opencode/skills/

## Delivery Workflow
1. Уточнить задачу.
2. При необходимости обновить specs.
3. Реализовать минимальный рабочий slice.
4. Обновить сопутствующую документацию.

Шаг 5. Добавить первый opencode.json

Следующий обязательный шаг — проектный конфиг. Минимальная полезная версия должна хотя бы подключать инструкции. И здесь ключевой момент: полезно подключать не только AGENTS.md, но и docs/specs/*.md, чтобы в контекст модели попадали не только общие правила, но и проектные спецификации.

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENTS.md",
    "docs/specs/*.md"
  ]
}

Даже такой маленький конфиг уже делает поведение агента заметно лучше. Он начинает опираться не только на состояние файловой системы, но и на explicit project instructions.

Шаг 6. Сразу заложить минимальную файловую структуру

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

my-project/
├─ AGENTS.md
├─ opencode.json
├─ docs/
│  └─ specs/
│     └─ first-feature.md
└─ .opencode/
   ├─ agents/
   └─ skills/

Когда эти директории появляются с самого начала, проект намного легче масштабируется в сторону командного использования.

Шаг 7. Прогнать первую структурированную сессию

После этих действий правильнее не сразу просить у агента «сделай большую фичу», а проверить, что он действительно понимает проект. Для этого полезно прогнать короткий structured loop: сначала обзор структуры, затем пересказ правил, затем список пробелов в документации и только потом реализация.

Сначала кратко опиши структуру репозитория.
Потом объясни основные правила из @AGENTS.md.
Потом скажи, каких specs не хватает в docs/specs для уверенной дальнейшей разработки.

Такой запрос проверяет, что OpenCode действительно видит и понимает ваш проектный слой, а не просто блуждает по файлам.

Чеклист первых 30 минут

• OpenCode установлен
• Провайдер подключен через /connect
• Репозиторий инициализирован через /init
• AGENTS.md вручную дочищен
• opencode.json добавлен с instructions
• Создана папка docs/specs/
• Созданы .opencode/agents/ и .opencode/skills/

Типичные ошибки на этом этапе