Урок 15.4. Как работают команды: чат агента и терминал

Зачем это нужно

В уроке 15.1 мы уже показывали таблицу с двумя колонками: команды openspec ... в терминале и команды /opsx:... в чате агента. В уроке 15.2 вы провели первое изменение по циклу /opsx:explore → /opsx:propose → /opsx:apply → /opsx:archive, а в уроке 15.3 разобрали, какие артефакты при этом создаются: proposal, дельта-спецификации, design, tasks. Но механика самих команд - где именно они выполняются, кто их обрабатывает и почему написание различается между инструментами - пока не разбиралась.

Отсылка к обзорному уроку 2.10: там OpenSpec фигурировал как один из инструментов на карте SDD-рынка, а здесь разбирается его повседневная механика - то, с чем вы сталкиваетесь при каждом запуске.

А это самый частый камень преткновения новых пользователей OpenSpec. Типичная ситуация: вы прочитали про /opsx:propose, открыли терминал, ввели команду - и ничего не произошло. Документация посвящает этому отдельную страницу, и не зря: слэш-команды - не терминальные команды, и попытка выполнить их в shell обречена с самого начала.

Этот урок раскладывает устройство команд по полочкам: две половины OpenSpec, «интерактивный режим» (точнее, его отсутствие), вариации написания /opsx:* в разных инструментах, разницу между skills и commands и то, что именно делает openspec init для выбранного инструмента. После него справочники - урок 15.5 по слэш-командам и урок 15.6 по CLI - читаются без путаницы.

После урока вы сможете:

• однозначно определять, в какой половине выполняется любая команда OpenSpec;
• проверять установку по четырем быстрым проверкам и чинить пропавшие команды через openspec update;
• подбирать правильное написание команды для своего инструмента вместо угадывания.

Основная идея

Главное, что нужно знать: в OpenSpec есть два вида команд, и выполняются они в двух разных местах.

• команды openspec ... выполняются в терминале (пример: openspec init);
• команды /opsx:... выполняются в чате AI-ассистента (пример: /opsx:propose).

Слэш-команда - это не команда shell. Это инструкция coding-агенту, введенная в тот же чат, куда вы обычно пишете «добавь форму логина». Половина терминала при этом готовит почву: именно запуск openspec init устанавливает слэш-команды в ваш AI-инструмент. После настройки повседневная работа почти целиком происходит в чате.

Простая проверка на понимание: если команда начинается с openspec - ей место в терминале; если со слэша или другого префикса вроде $ или @ - в чате агента.

Две половины OpenSpec

OpenSpec - один проект, который носит две шляпы.

CLI: половина терминала

CLI - это программа с именем openspec, которую вы устанавливаете и запускаете из shell. Она настраивает проект, показывает список активных изменений и валидирует их, открывает дашборд и архивирует завершенную работу. Эти команды набирают там же, где вы привыкли запускать git или npm: в iTerm, во встроенном терминале VS Code, в PowerShell.

openspec init        # настроить OpenSpec в этом проекте
openspec list        # посмотреть активные изменения
openspec view        # открыть интерактивный дашборд

Полный список терминальных команд с флагами и примерами - в уроке 15.6.

Слэш-команды: половина чата

Слэш-команды - короткие команды вроде /opsx:propose и /opsx:apply, которые вы вводите AI-ассистенту. Они говорят агенту следовать workflow OpenSpec: набросать proposal, написать спецификации, строить реализацию по списку задач, архивировать по завершении. Набирают их в Claude Code, Cursor, Devin Desktop, Copilot - в любом ассистенте, которым вы пользуетесь.

/opsx:propose add-dark-mode    (в чате AI-ассистента)
/opsx:apply                    (в чате AI-ассистента)
/opsx:archive                  (в чате AI-ассистента)

Ментальная модель одной картинкой

Обратите внимание на стрелку. Запуск openspec init в терминале - это то, что устанавливает слэш-команды в ваш AI-инструмент. Половина терминала настраивает половину чата. После этого повседневное управление процессом в основном происходит в чате.

Сводное сравнение

Типичная ошибка новичка

Если вы когда-нибудь введете /opsx:propose в терминале и ничего не произойдет - причина именно в этом: вы обращаетесь не к той половине OpenSpec. Слэш-команды не являются терминальными командами, и терминал не знает, что с ними делать.

Схематично обе попытки выглядят так:

Терминал (неправильное место):
$ /opsx:propose
command not found          ← shell не знает слэш-команды OpenSpec

Чат агента (правильное место):
Вы:   /opsx:propose add-dark-mode
AI:   распознает команду, загружает skill OpenSpec
      и готовит артефакты изменения

Это различие - главный спотыкачный камень новых пользователей, поэтому зафиксируем его в форме таблицы типичных симптомов:

Все строки таблицы сводятся к одному принципу диагностики: сначала убедитесь, что вы обращаетесь к правильной половине OpenSpec, затем - что файлы для этой половины существуют и не устарели.

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

«Как включить интерактивный режим?»

Отдельного интерактивного режима, который нужно включать, не существует. Этот вопрос возникает часто, поэтому он заслуживает прямого ответа: вы не входите ни в какой специальный режим OpenSpec. Вы просто открываете свой coding-агент, как обычно, и вводите слэш-команду в чат. Слэш-команда - это и есть способ «войти» в OpenSpec: ассистент распознает ее, загружает соответствующий OpenSpec skill и начинает следовать workflow.

Реальная последовательность действий выглядит так:

1. Откройте coding-агент (Claude Code, Cursor, Devin Desktop и так далее) в вашем проекте.
2. Введите /opsx:propose в его чат - там же, куда вы пишете любой другой запрос.
3. Следите за автодополнением: если OpenSpec установлен, при вводе слэша появятся /opsx:propose, /opsx:apply и остальные команды.

Вот и все. Не нужно переключать режимы, запускать демон или открывать отдельное окно.

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

Разница между двумя «интерактивностями» в двух словах:

• openspec view - интерактивный просмотр того, что уже есть: спецификации, активные изменения, архив;
• слэш-команды - интерактивное создание нового: обсуждение, proposal, реализация, архивация.

Почему разделение устроено именно так

Разделение стоит понять глубже - оно объясняет, почему OpenSpec работает с более чем 30 разными AI-инструментами.

CLI - это двигатель. Он знает правила: как выглядит каталог изменения, какие артефакты от каких зависят, как влить дельта-спецификацию в living spec. Двигатель везде один и тот же.

Слэш-команды - это руль, и у каждого AI-инструмента он немного свой. Claude Code называет их командами. У Cursor и Devin Desktop свои форматы. Некоторые инструменты называют их skills. Когда вы запускаете openspec init, OpenSpec генерирует файл нужного вида для каждого выбранного инструмента - поэтому одно и то же намерение /opsx:propose работает независимо от того, какого ассистента вы предпочитаете.

Сила этого дизайна: workflow выучивается один раз и переносится между инструментами. Плата за него: точное написание команды немного различается между инструментами - это тема следующего раздела.

Написание слэш-команд в разных инструментах

Намерение везде одинаковое: /opsx:propose в Claude Code и /opsx-propose в Cursor - одна и та же команда. Написание определяется тем, какой файл загружает ваш инструмент:

Здесь <id> - идентификатор команды: propose, apply, archive и так далее.

Чтобы не запоминать всю таблицу, достаточно держать в голове три семейства написаний плюс два исключения:

• семейство с двоеточием: /opsx:propose - инструменты, которые читают каталог commands/opsx/<id>;
• семейство с дефисом: /opsx-propose - инструменты с плоскими файлами opsx-<id>;
• семейство по имени skill: /openspec-propose - инструменты без файлов команд; иногда с префиксом: $openspec-propose в Codex и /skill:openspec-propose в Kimi Code;
• исключение-промпт: @opsx-propose в Amazon Q Developer - файлы загружаются в библиотеку промптов, вызываемую через @.

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

Частный случай: Devin

Devin - единственный инструмент, который охватывает две строки таблицы. Devin Desktop читает .devin/workflows/, поэтому в нем работает /opsx-propose. А Devin Local этот каталог не читает - на таком агенте используйте skill /openspec-propose. Skills, которые OpenSpec записывает в .devin/skills/, работают в обоих вариантах - поэтому они ссылаются друг на друга по имени skill.

Skills-only инструменты и имена skills

Полная таблица поддержки приведена в официальном документе Supported Tools (раздел How To Invoke) - она является источником истины. Две детали, которые стоит знать заранее:

• Amazon Q Developer - вообще не слэш-команды в чистом виде: файлы загружаются в библиотеку промптов и вызываются через @;
• последние три строки таблицы используют имя skill, которое не совпадает с id команды: /opsx:apply - это skill openspec-apply-change.

Практическое следствие: в skills-only инструментах ищите в автодополнении имена вида openspec-*, а не opsx-* - иначе легко решить, что установка сломана, хотя она в порядке.

Как узнать свое написание

Если сомневаетесь, прочитайте строку Getting started, которую напечатал openspec init: она уже использует ту форму, которую зарегистрировали ваши инструменты. Помогает и ввод слэша с наблюдением за автодополнением - для тех инструментов, которые показывают слэш-команды вообще.

Теперь понятно, почему setup-промпт из урока 15.1 требовал брать написание из созданных файлов, а не из строки summary: пунктуация различается по инструментам, и единственный надежный источник - файл, который init сгенерировал именно для вашего набора инструментов.

Если вы пользуетесь несколькими инструментами в одном проекте, init генерирует файлы для каждого выбранного - и форма вызова может отличаться между ними, потому что ее определяет каждый инструмент со своей раскладкой.

Откуда берутся команды: skills и commands

Когда вы запускаете openspec init (или openspec update), OpenSpec записывает в проект небольшие файлы, по которым ваш AI-инструмент находит workflow. В зависимости от инструмента и настроек это skills, commands или и то и другое.

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

Что именно init делает для выбранного инструмента

Соберем в один список то, что происходит при openspec init (и повторяется при openspec update):

1. OpenSpec определяет инструменты, которые вы выбрали при инициализации.
2. Для каждого инструмента генерируется файл нужного вида - skill, command или оба - в каталог, который этот инструмент сканирует: .claude/skills/, .cursor/commands/, .devin/workflows/ и .devin/skills/, .amazonq/prompts/, для Codex - .agents/skills/.
3. Раскладку и формат файла определяет сам инструмент - поэтому одно и то же намерение /opsx:propose превращается в разные написания (см. таблицу выше).
4. В выводе init печатается строка Getting started - в ней уже используется та форма вызова, которую зарегистрировали ваши инструменты.
5. При обновлении CLI openspec update перегенерирует файлы, чтобы слэш-команды соответствовали установленной версии.

Точные пути для каждого инструмента перечислены в уроке 15.13; история того, как skills заменили старый подход «только команды», - в Migration Guide (разбирается в уроке 15.15).

Инженерный вывод курса: разделение «двигатель + руль» - это разделение ответственности между детерминированным кодом и вероятностной моделью. Правила структуры изменений, зависимости артефактов и слияние дельт - то, что нельзя доверять языковой модели, - спрятаны в CLI. Все, что требует интерпретации и рассуждений, отдано агенту через маленькие файлы-инструкции. Такая архитектура - общий паттерн для инструментов поверх coding-агентов, и ее стоит копировать в собственных проектах.

Как убедиться, что все установлено

Быстрые проверки, в порядке от самой быстрой.

1. Слэш и автодополнение

Введите слэш в чате ассистента: начните набирать /opsx и следите за автодополнением. Появились подсказки - все готово.

Важная оговорка: на инструментах, работающих только через skills (Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent или общий каталог .agents), /opsx не дополняется никогда - даже при исправной установке. В этом случае попробуйте имя skill из таблицы написаний выше.

2. Файлы на диске

Проверьте, что сгенерированные файлы на месте. Для Claude Code убедитесь, что .claude/skills/ содержит каталоги openspec-*. Другие инструменты используют собственные каталоги - их перечень есть в Supported Tools (урок 15.13).

3. Повторная генерация

Из корня проекта выполните openspec update - команда перегенерирует файлы skills и команд для настроенных инструментов:

cd your-project
openspec update

4. Перезапуск ассистента

Многие инструменты сканируют skills и команды при старте, поэтому свежее окно может оказаться недостающим шагом.

Если после всех четырех проверок команды так и не появились - загляните в Troubleshooting: там собраны исправления именно для случая «команды не показываются» (урок 15.15).

Какой набор команд устанавливается по умолчанию

Core-набор

По умолчанию OpenSpec устанавливает core-набор слэш-команд:

Рабочий ритм по умолчанию: explore, когда решаете, что делать, затем propose, apply, archive. Почему первая ступень окупается - отдельно разобрано в уроке 15.7.

Расширенный набор

Есть и расширенный набор для тех, кому нужен более тонкий контроль: /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard. Он включается командой openspec config profile, после чего применяется через openspec update.

/opsx:onboard для первого знакомства

Только начинаете? Команда /opsx:onboard из расширенного набора проводит вас через полное изменение на вашем собственном коде, комментируя каждый шаг. Это самый дружелюбный способ познакомиться с системой.

Подробно о каждой команде - в уроке 15.5. О том, какую команду в какой ситуации применять, - в уроке 15.8.

Чистый первый запуск

Соберем все вместе - полная последовательность с пометкой, где происходит каждый шаг:

ТЕРМИНАЛ   $ npm install -g @fission-ai/openspec@latest
ТЕРМИНАЛ   $ cd your-project
ТЕРМИНАЛ   $ openspec init
             (устанавливает слэш-команды в ваш AI-инструмент)

ЧАТ АГЕНТА   /opsx:explore
             (необязательно: сначала продумать идею вместе с AI)

ЧАТ АГЕНТА   /opsx:propose add-dark-mode
             (AI готовит proposal, specs, design, tasks)

ЧАТ АГЕНТА   /opsx:apply
             (AI реализует изменение, отмечая задачи)

ЧАТ АГЕНТА   /opsx:archive
             (изменение вливается в спецификации и уходит в архив)

Два терминальных шага на настройку. Дальше вы живете в чате. Это и есть ритм работы с OpenSpec.

Та же последовательность как диаграмма - видно, что терминал участвует только в настройке, а дальше весь цикл изменения идет в чате:

Пошаговый разбор каждого этапа этой последовательности с живым выводом команд - в уроке 15.2; здесь она приведена как карта «что где происходит».

Связанные материалы

Раздел Related оригинальной страницы ложится на уроки модуля так:

Практика

Задания выполняются в тестовом проекте, где OpenSpec уже инициализирован (урок 15.2). Цель - прочувствовать границу «терминал / чат» руками, а не только по тексту.

1. В тестовом проекте выполните openspec list, затем openspec view и посмотрите дашборд: активные изменения, разделы спецификаций. Ожидаемый результат: список изменений в терминале и открытый интерактивный дашборд.
2. Откройте ваш coding-агент в этом же проекте, введите /opsx и посмотрите на автодополнение. Если подсказок нет - сверьтесь с таблицей написаний выше и попробуйте форму своего инструмента (например, $openspec-propose в Codex). Ожидаемый результат: ваш инструмент предлагает команды OpenSpec в той форме, которую зарегистрировал openspec init.
3. Найдите в выводе openspec init строку Getting started (или перезапустите openspec init - существующий каталог openspec/ он обновит, не трогая ваши specs и changes, см. урок 15.1). Выпишите ту форму команды, которую init зарегистрировал для вашего инструмента.
4. Загляните в каталоги, куда init записал файлы: например, .claude/skills/openspec-* или .cursor/commands/opsx-*. Откройте один файл и убедитесь, что написание команды в нем совпадает со строкой Getting started.
5. Для закрепления введите /opsx:propose в терминале и посмотрите на реакцию shell. Ошибка «команда не найдена» - ожидаемый результат и лучшая демонстрация того, что слэш-команды живут в другой половине OpenSpec.
6. Выполните openspec update, перезапустите ассистента и повторите проверку из шага 2 - команды должны по-прежнему дополняться.

Краткое резюме

Устройство команд OpenSpec сводится к одному различию, из которого вытекает все остальное.

• Два вида команд в двух местах: openspec ... - терминал, /opsx:... - чат AI-ассистента.
• Слэш-команда - инструкция coding-агенту, а не команда shell; вводить ее в терминал - самая частая ошибка новичка.
• openspec init устанавливает слэш-команды в выбранные инструменты; повседневная работа затем происходит в чате.
• Отдельного интерактивного режима нет: слэш-команда и есть вход в OpenSpec. Интерактивный дашборд openspec view - просмотрщик в терминале.
• CLI - двигатель (правила структуры и слияния дельт), слэш-команды - руль (отличается на каждом инструменте). Workflow выучивается один раз.
• Написание зависит от инструмента: /opsx:propose, /opsx-propose, @opsx-propose, /openspec-propose, /skill:openspec-propose, $openspec-propose. Источник истины - строка Getting started из init и таблица Supported Tools.
• Команды попадают в проект файлами skills и/или commands; если они пропали - openspec update перегенерирует их.
• Core-набор: explore → propose → apply → archive (плюс update и sync); расширенный набор включается через openspec config profile.

Вопросы для самопроверки

1. Чем слэш-команда /opsx:propose отличается от терминальной команды openspec init с точки зрения места выполнения и того, кто ее обрабатывает?
2. Что происходит после ввода /opsx:propose в чат ассистента: какой механизм распознает команду и запускает workflow?
3. Почему одно и то же намерение записывается по-разному в Claude Code, Cursor, Amazon Q Developer и Codex CLI? Перечислите формы.
4. Чем skills отличаются от commands, почему OpenSpec генерирует разные файлы для разных инструментов и что делать, если слэш-команды пропали?
5. /opsx не появляется в автодополнении чата. Перечислите проверки по порядку - от самой быстрой к самой медленной.
6. Какие команды входят в core-набор и в каком порядке их обычно применяют? Как включить расширенный набор?

Что дальше

Урок 15.5 - справочник всех слэш-команд /opsx:*: назначение, аргументы, ожидаемый результат и типовые сценарии применения каждой команды из core- и расширенного наборов.

Источники

• https://github.com/Fission-AI/OpenSpec/blob/main/docs/how-commands-work.md