openspec в работе

Примерно два месяца назад я узнал про openspec, и решил попробовать. Пет-проекты на тот момент были на паузе, поэтому пробовать начал сразу в рабочем проекте. В этой статье покажу как выглядит рабочий процесс с использованием openspec внутри opencode.

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

Установка в проекте

В терминале в папке с проектом выполнил команду openspec init и отметил нужные инструменты (opencode и т.д.)

Выбрал opencode

После нажатия enter нужно перезагрузить IDE, в моем случае - просто завершить сеанс opencode в терминале и запустить его заново

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

Использование в работе

Запускаем opencode и начинаем вводить команду /o

Первые несколько секунд идет загрузка всех команд, а потом в списке появляются новые команды openspec

Новая мелкая фича

Если есть полное понимание, что нужно делать, то можно сразу использовать /opsx-ff - я так делал два раза для мелких задач, где все максимально очевидно и обсуждать нечего, например:

/opsx-ff task1234-toggle

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

Отправляем промпт в работу, и получаем ответ типа такого:

I found existing toggle-related code in the project (reminder settings toggle, filter dialog toggle), but "task-1234-toggle" doesn't tell me what you want to build or fix.
What do you want this change to do? For example:
- Add a new toggle for some feature
- Fix a bug with an existing toggle
- Refactor toggle logic
Describe the feature/fix and I'll create all the OpenSpec artifacts.

Дальше отправляю промпт с кратким описанием фичи (ведь она мелкая):

нужно сделать фичефлаг для настройки возможности включения или отключения экрана с логами для разработчика на экране

Агент какое-то время думает и создает все необходимые документы (артефакты) по задаче:

Окончание работы по созданию документов к задаче

Теперь нужно проверить получившиеся документы самостоятельно (т.к. там действительно немного текста) и при обнаружении нестыковок/ошибок нужно внести правки в документы (вручную или опять же через агента).

После проверки/исправления всех документов можно сразу переходить к /opsx-apply или сохранить прогресс (делаем коммит) и переключиться на что-то еще.

Новая стандартная фича

Если хочется больше контроля над процессом создания документации, или еще не до конца известны все требования для задачи, то есть смысл начинать с команды /opsx-new, например:

/opsx-new task1234-medium-feature

Отправляем этот промпт и получаем ответ:

Here's the summary:
Change: task1234-medium-feature
Location: openspec/changes/task1234-medium-feature/
Schema: spec-driven (4 artifacts)
Progress: 0/4 complete
[ ] proposal ← ready now
[-] design (blocked by: proposal)
[-] specs (blocked by: proposal)
[-] tasks (blocked by: design, specs)
First artifact: proposal.md — establish why this change is needed.
Template:
## Why

## What Changes

## Capabilities
### New Capabilities
- `<name>`: <description>

### Modified Capabilities

## Impact
<!— Affected code, APIs, dependencies -->
Ready to create the first artifact? Run /opsx-continue or describe what this change is about and I'll draft it.

В таком сценарии можно делать все документы по порядку, начиная с proposal, который является кратким описанием задачи для последующей детализации в других документах, напишем промпт с использованием команды /opsx-continue:

/opsx-continue task1234-medium-feature нужно сделать фичефлаг для настройки возможности включения или отключения экрана с логами для разработчика на экране

Отправляем этот промпт и получаем ответ:

Created: proposal.md
Schema: spec-driven | Progress: 1/4
[x] proposal ✓
[ ] design ← unlocked
[ ] specs ← unlocked
[-] tasks (blocked by: design, specs)
What's in the proposal:
- Why: Нет способа просмотреть логи внутри приложения, нужна фиче-флаг для скрытия от обычных пользователей
- Capabilities: dev-log-screen (экран логов) + dev-log-feature-flag (флаг управления)
- Impact: AppSettingsDataStore, Screen, MoreScreen, новый DevLogScreen + ViewModel
Ready to create the next artifact? Run /opsx-continue — I'll draft either design.md or the spec files next.

Теперь читаем proposal, вносим правки при необходимости, и либо продолжаем дальше работу в том же формате с командой /opsx-continue, либо ставим на паузу и переключаемся на что-то другое - главное сделать коммит, чтобы сохранить прогресс.

В нашем случае для примера я "промотаю" создание документов командой /opsx-ff, чтобы показать как работает /opsx-apply:

Агент начал работу

После окончания работы агент предлагает добавить фичу в архив как выполненную

Результат работы - тоггл "Developer logs"

Если тоггл включить, появится новая кнопка Dev Log

А вот и сам экран логов

Представим, что положение тоггла было таким и задумано изначально.

И вот пришло новое требование (ну ничего себе) - нужно тоггл переместить в нижнюю часть экрана. Правим артефакты либо вручную, либо новым промптом (без использования команд /opsx) и снова вызываем /opsx-apply для применения правок в коде:

Успех! Положение тоггла исправлено

Верификация статуса

Бывает, что задача откладывается на неопределенный срок, пока ее тестируют, обсуждают и т.д., и все это время код по задаче не пишется, но возможно меняются документы (вручную или нет, не важно).

Когда к задаче нужно вернуться, то можно проверить статус с помощью команды /opsx-verify, это я и сделал в нашем случае, вот итоги проверки:

No critical issues found.
3 warnings to consider — all minor. The implementation correctly follows all design decisions, covers all requirements and scenarios, and maintains code pattern consistency.
Ready for archive. ✓

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

Когда задачу "приняли" окончательно, ее нужно архивировать командой /opsx-archive:

Archive Complete
Change: task1234-medium-feature
Schema: spec-driven
Archived to: openspec/changes/archive/2026-06-27-task1234-medium-feature/
Specs: Delta specs preserved (new capabilities — no main specs to sync to)
All 4 artifacts complete. All 20 tasks complete.

Вот и все! Работа над задачей завершена, теперь любые доработки нужно делать через отдельные задачи (/opsx-new или /opsx-ff).

Мой отзыв

Мне нравится использовать openspec, потому что:

Стандартизируется рабочий процесс - сначала документация, потом реализация по четкому плану
Появляется документация в удобном формате прямо в папке с проектом, а не где-то далеко в отдельной системе
Удобно отслеживать работу и возвращаться к задаче после длительного перерыва

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

Нюансы

Многое зависит от используемой модели и настроек проекта (в том числе AGENTS.md) - не нужно ожидать классную реализацию плана с нужным стилем/подходом, если агент не знает ничего этого
Даже если проект настроен правильно, нейросеть может ошибиться в составлении документации (например), и потом сделать работу по неправильному плану, поэтому нужно перепроверять документацию и реализацию (как это делать - другой вопрос, кто-то будет сам читать, а у кого-то будут автоматизированные проверки)

Еще раз ссылка на репозиторий openspec, рекомендую попробовать самостоятельно 😉