Глава 00 · Обзор и введение

Как превратить OpenCode в полноценный слой проекта, а не просто CLI

Этот сайт объясняет, как оформить репозиторий так, чтобы OpenCode понимал структуру проекта, опирался на реальные правила команды, читал спецификации рядом с кодом, использовал role-based subagents и не делал лишнего без продуманной политики разрешений. Основа гайда: официальная документация OpenCode и репозиторий-пример github.com/ivanshamaev/ai-agent-codex.

Начать чтение Быстрый старт Анатомия проекта MCP и интеграции Best Practices Development Process

Дополнительные материалы

YouTube

Видеообзор интерфейса OpenCode

TUI и десктоп, подключение провайдеров через API-ключи, управление подписками Claude Code и GPT-Codex, Google-интеграции и демонстрация лендинга, который автор собрал на OpenCode + GLM 4.7.

YouTube

Расширенный туториал

Установка OpenCode, настройка MCP, добавление skills и rules, подключение нейросетей (бесплатный GPT и Minimax), генерация промптов, запуск проектов с нуля, десктоп и расширения для IDE.

Гайд

Claude Skills Guide

Русскоязычное руководство по проектированию и поддержке skills: структура файлов, контроль версий и лучшие практики адаптации под OpenCode.

Где искать готовые skills и MCP

Каталог

cursor.directory

Подборка skills и MCP с фильтрами по назначению и языкам; быстрый референс без копания в GitHub.

MCP

MCP Market

Маркетплейс Model Context Protocol серверов: документация, DevOps и корпоративные API с описаниями авторов.

Каталог

skills.sh

Онлайн-редактор с превью, тегами и примерами промптов — удобно копировать структуру skills.

Каталог

SkillHub

Сообщество с регулярными подборками skills и инструкциями по их адаптации в OpenCode.

Marketplace

skillsmp

Маркетплейс кастомных skills и rules с описанием сценариев и ценой поддержки.

GitHub

Skill Seekers

Коллекция готовых OpenCode skills и кейсов, в каких задачах их подключать.

GitHub

prompt-master

Набор шаблонов и tooling для поддержки skills и rules в актуальном состоянии.

GitHub

claude-skills

Подборка Claude-навыков, которые легко адаптировать под OpenCode.

GitHub

pm-skills

Skills для продуктовых задач: discovery, roadmap, требования — полезно для PM-ролей.

GitHub

awesome-agent-skills

Консолидированный список агентных skills, включая OpenCode-совместимые шаблоны.

Зачем вообще нужен отдельный гайд по настройке OpenCode-проекта

Почти любой AI coding tool можно установить за несколько минут. Но разница между «CLI запускается» и «агент стабильно помогает всей команде» огромная. Во втором случае нужен отдельный слой проектной настройки: что агент считает обязательными правилами, где он читает требования, как он понимает архитектуру репозитория, когда он вызывает специальные роли и какие действия он может выполнять автоматически.

Если этот слой не настроен, агент каждый раз начинает почти с нуля. Он вынужден угадывать, какие папки считаются canonical, где хранятся требования, что такое “правильный” способ внесения изменений и какие действия допустимы без лишних вопросов. Поэтому хороший OpenCode setup это не аксессуар, а часть инженерной инфраструктуры репозитория.

AGENTS.md как проектный контракт

opencode.json как control plane

.opencode/ как слой расширения

Что именно покрывает этот гайд

Введение (эта глава)

Рамка всего гайда: зачем существует OpenCode-слой, карта разделов и базовые принципы.

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

Установка, /connect, /init, первый AGENTS.md и первый opencode.json.

Анатомия проекта

Подробный разбор реального репозитория-примера: какие папки и файлы формируют OpenCode-слой.

Агенты и skills

Когда стоит создавать subagents, как описывать роли и как выносить повторяемые playbooks в skills.

Конфиг и разрешения

Как собрать opencode.json, подключить instructions и настроить разумные ограничения.

Командные процессы

Plan/build, specs-first работа, маршрутизация задач по ролям и типичные ошибки внедрения.

MCP и интеграции

Локальные и удаленные MCP-серверы, OAuth, управление контекстом и практические сценарии подключения.

Best Practices

Реальные паттерны: модельная стратегия, Plan/Build дисциплина, skills, cost-контроль и онбординг.

Development Process

Как вести сложный OpenCode-проект через delivery cycles, quality gates, review, infra-guardrails и repeatable operating model.

Step 1: Project Example

Практический blueprint: AGENTS.md, stage-based delivery, stage reports, prompts и большой online shop пример.

Step 2: Project Example

Готовая структура `/docs` для online shop: stage files, reports, ADR, runbooks и файловая дисциплина.

Репозиторий-пример, на котором построен гайд

Чтобы не объяснять OpenCode через абстрактные схемы, весь гайд опирается на реальный проект: github.com/ivanshamaev/ai-agent-codex. Это важно по двум причинам. Во-первых, можно говорить не «в теории вам стоит добавить agents», а показывать, какие агенты уже существуют в проекте. Во-вторых, такой пример лучше демонстрирует, как выглядит зрелая структура, где правила, спецификации, subagents и skills связаны между собой.

ai-agent-codex/
├─ AGENTS.md
├─ opencode.json
├─ .env.example
├─ docker-compose.yml
├─ pyproject.toml
├─ pyrightconfig.json
├─ README.md
├─ apps/
│  ├─ api/
│  └─ web/
├─ dags/
├─ src/
├─ dbt/
├─ sql/
├─ docs/
│  └─ specs/
├─ data/
├─ logs/
├─ plugins/
└─ .opencode/
   ├─ agents/
   └─ skills/

Полная структура целевого проекта OpenCode

Чтобы описывать OpenCode как систему, а не как CLI, полезно иметь эталонную структуру OpenCode-слоя. Ниже — абстрактный проект, где собраны только те директории и файлы, которые управляют поведением OpenCode.

opencode-project/
├─ AGENTS.md
├─ opencode.json
├─ instructions/
│  ├─ defaults.md
│  └─ safety.md
├─ docs/
│  └─ specs/
├─ .opencode/
│  ├─ agents/
│  ├─ skills/
│  ├─ patterns/
│  └─ templates/
├─ mcp/
│  ├─ local/
│  └─ remote/
└─ README.md

Расшифровка компонентов OpenCode-уровня:

Компонент	Назначение	Комментарий
`AGENTS.md`	Проектный контракт.	Структура репозитория, роли, роутинг задач, корпоративные правила и определение успеха.
`opencode.json`	Control plane OpenCode.	Определяет инструкции, доступные инструменты, MCP, токенные лимиты, разрешения и наследование.
`instructions/`	Базовые правила.	Сюда уносятся долгоживущие инструкции к проекту (defaults, security, style), которые подключаются через конфиг.
`.opencode/agents/`	Role-based subagents.	Файлы с профилями ролей (analyst, infra, architect). Каждый может подключать собственные инструменты и MCP.
`.opencode/skills/`	Playbooks.	Повторяемые стратегии мышления и workflow, которые агент подгружает по prompt-команде.
`.opencode/patterns/`	Контроль безопасности.	Опциональный слой с whitelist/blacklist инструкциями для инструментов и действий.
`.opencode/templates/`	Шаблоны ответов.	Готовые форматы для описания RCA, планов миграций, спеки задач и т.д.
`docs/specs/`	Durable спецификации.	Технические и продуктовые контракты, на которые агент должен ссылаться при работе.
`mcp/local/`	Локальные MCP-серверы.	Скрипты или описания процессов, которые запускаются рядом с проектом (поиск по документации, локальные БД).
`mcp/remote/`	Удалённые MCP.	Конфигурации и oauth-notes для внешних серверов (Context7, Sentry, корпоративные API).
`README.md`	Входная точка для команды.	Содержит ссылку на AGENTS.md, список skills и инструкции по запуску OpenCode.

Важная рамка

Этот гайд сознательно смотрит на OpenCode как на часть инженерной среды проекта. То есть не как на «чат в терминале», а как на систему, которую нужно встраивать в репозиторий, процессы и договоренности команды.