Development Process для сложных OpenCode-проектов

Эта глава показывает, как использовать OpenCode не как "магическую кнопку написать весь проект", а как управляемую инженерную среду. Основа процесса: короткие циклы поставки, явные роли, проверяемые acceptance criteria, отдельный review-проход и строгие guardrails для инфраструктуры и risky-команд.

Главный принцип

Сложный проект не должен развиваться как один бесконечный прогон генерации кода. Гораздо устойчивее подход, где OpenCode работает внутри понятного контура: сначала исследование и план, затем ограниченный по scope инкремент, после этого верификация, review и только потом фиксация результата.

• Планирование фиксирует intent и риски до правок кода.
• Реализация ограничивается согласованным scope, а не расползается по всему репозиторию.
• Верификация подтверждает результат командами и наблюдаемым поведением.
• Review ищет риски, которые легко пропустить в процессе реализации.
• Stage notes делают этап завершенным и передаваемым следующему циклу.

Когда OpenCode подходит лучше всего

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

• Нужно развивать существующую кодовую базу, а не одноразовый прототип.
• Важно работать в терминале с файлами, git, тестами, линтерами и сборкой.
• Нужны repeatable instructions, которые должны переживать отдельные сессии.
• Полезно разделять режимы работы: plan, build, review, debug, docs.
• Есть смысл подключать built-in инструменты и MCP только там, где они действительно дают ценность.

Operating model проекта

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

Стартовая настройка репозитория

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

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

• Как собрать проект и как запускать локальную среду.
• Как запускать тесты, линтеры и typecheck.
• Какие пакеты, сервисы или директории критичны для проекта.
• Какие архитектурные слои существуют и что между ними разрешено.
• Какие паттерны запрещены и какие short-cuts считаются нежелательными.
• Как оформлять миграции, API, UI и инфраструктурные изменения.
• Что обязательно проверить перед завершением задачи.

Permissions как boundary контроля

В сложных проектах особенно важно не оставлять права агенту "по умолчанию". Хорошая permission policy делает поведение предсказуемым и отделяет безопасные действия от чувствительных.

Plan как default для новых больших задач

Если в проекте много архитектурных и cross-cutting изменений, полезно начинать новые задачи с plan по умолчанию. Это снижает шанс, что реализация начнётся до того, как команда согласовала scope, риски и способ проверки результата.

Как правильно дробить работу

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

• "Добавить аудит действий администратора end-to-end".
• "Внедрить фоновую обработку задач с retry и метриками".
• "Перевести модуль X на новый API-контракт и закрыть старый путь".

Один управляемый рабочий цикл

1. Plan

Задача в plan должна звучать как постановка хорошему инженеру: с контекстом, ограничениями, ссылками на похожие участки кода и критериями приемки. На выходе нужен не код, а план с целями, затрагиваемыми модулями, рисками, порядком действий, верификацией и assumptions.

2. Уточнение плана

На этом шаге полезно специально уменьшить лишний scope. Хороший вопрос не "можешь сделать больше?", а "какой минимальный инкремент закрывает основной риск и даёт демонстрируемый результат?".

3. Build

Только после согласования плана запускается реализация. Просите сделать ровно тот scope, который уже принят: без дополнительных "улучшений", которые не были явно включены в план.

4. Verify

Агент должен запускать нужные команды и честно сообщать фактический статус. Формулировка "предположительно всё ок" не заменяет ни тесты, ни сборку, ни smoke-проверки.

• Какие команды были запущены.
• Что прошло успешно.
• Что упало и почему.
• Что не удалось проверить в локальном контуре.

5. Review

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

6. Stage Notes

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

Моноагент или мультиагенты

Когда достаточно моноагента

• Задача остаётся обозримой внутри одного planning loop.
• Контекст проекта помещается в один устойчивый reasoning cycle.
• Архитектура уже в целом ясна, а пользователь сам может быть product или tech reviewer.

Даже в этом режиме роли лучше разделять по фазам: сначала plan, потом build, затем review и при необходимости docs.

Когда имеет смысл переходить к мультиагентам

• Проект стал слишком большим для одного контекста.
• Frontend, backend, infra и tests смешиваются в один шумный пайплайн.
• Нужен независимый review-контур или параллельная работа по разным направлениям.
• У разных задач должны быть разные permissions и доступ к инструментам.

Практичная схема ролей

Как управлять качеством кода

Done - это не "код написан"

• Код написан и действительно закрывает заявленный сценарий.
• Статические проверки и релевантные тесты пройдены.
• Проверено поведение на правильном уровне: unit, integration, smoke или e2e.
• Изменённые контракты и важные решения задокументированы.
• Риски и ограничения перечислены явно.

Требуйте модульность, а не только работоспособность

В правилах проекта полезно заранее фиксировать допустимые слои и зависимости, правила именования, границы модулей, требования к public API и явный запрет на обход архитектуры через быстрые, но хрупкие shortcuts.

Second pass review обязателен

Отдельный review-проход должен целенаправленно искать следующие вещи:

• Неочевидные побочные эффекты.
• Архитектурный drift и нежелательное смешение слоёв.
• Избыточную сложность и неиспользуемый код.
• Уязвимые места, слабые permission boundaries и пропущенные тесты.

Инфраструктура и guardrails

Инфраструктура отлично подходит для агентной помощи, но именно здесь особенно опасно оставлять поведение неявным. Поэтому хорошая схема почти всегда выглядит так: IaC хранится в репозитории, агент может менять файлы инфраструктуры, но не применяет изменения без явного approval.

Что должен делать infra-проход

• Обновить IaC-файлы и связанные CI/CD-конфиги.
• Показать diff и перечислить ожидаемые изменения инфраструктуры.
• Сформировать runbook применения и rollback path.
• Явно отметить секреты, миграции БД, порядок деплоя и permission-sensitive места.

Как сделать проект тестируемым

Тесты должны жить в каждом этапе

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

• Unit там, где появляется новая логика.
• Integration там, где меняются контракты или взаимодействие модулей.
• Smoke / e2e там, где затронут критичный пользовательский путь.

Делайте eval mindset, а не только unit mindset

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

Что проверять помимо "работает / не работает"

• Контракт API и обратную совместимость.
• Миграции данных и последствия для существующего состояния.
• Observability: логи, метрики, трассировки на критичных путях.
• Обработку ошибок, latency и resource usage.
• Границы прав доступа и permission-sensitive сценарии.

Как держать фокус на бизнес-ценности

OpenCode легко уводит в инженерную активность ради самой инженерной активности. Чтобы этого не происходило, каждый delivery slice полезно прогонять через одни и те же вопросы.

1. Какой бизнес-сценарий улучшается?
2. Какой пользовательский путь станет лучше?
3. Какой риск снимается?
4. Как мы поймём, что изменение дало пользу?
5. Что будет демонстрацией результата?

Как писать хорошие инструкции агенту

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

• Цель и ожидаемое изменение для пользователя или системы.
• Границы scope и явное out of scope.
• Что менять нельзя.
• Референсы в кодовой базе или соседние реализации.
• Acceptance criteria.
• Required verification.
• Формат финального отчёта.

Спроектируй и реализуй защиту маршрута X по аналогии с модулем Y.
Сначала дай план.
Затем внеси минимальный инкремент.
Обнови тесты.
Проверь typecheck и integration suite Z.
В конце перечисли assumptions, риски и manual QA steps.

Skills, rules и repeatability

В зрелом OpenCode-проекте повторяемость строится не на одном "волшебном промпте", а на нескольких слоях, которые поддерживают друг друга.

Универсальный operating model для команды

На уровне проекта

• Один backlog и короткие этапы поставки.
• Единый Definition of Done.
• Обязательный AGENTS.md.
• Skills для типовых процедур.
• Настроенные permissions.
• Build, verify и review как отдельные фазы, а не один общий поток.

На уровне задачи

1. Plan
2. Build
3. Verify
4. Review
5. Document

На уровне релиза

• Changelog или release notes.
• Список ручных проверок.
• Known issues.
• Rollout plan.
• Rollback plan.
• Post-release monitoring checklist.

Антипаттерны, которые ломают процесс

Минимальный золотой стандарт

Готовые шаблоны процесса

Формат этапа

Название этапа
Цель
Scope
Out of scope
Acceptance criteria
План реализации
План проверки
Риски и допущения

Формат финального отчёта

Что сделано
Какие файлы или модули изменены
Какие проверки выполнены
Что не удалось проверить
Риски / tech debt
Manual QA checklist
Recommended next step

Итог