Часто задаваемые вопросы

Краткие ответы на самые частые вопросы. Если у вас что-то не работает, лучше открыть раздел Устранение неполадок. Определения терминов см. в глоссарии.

Основы

Что такое OpenSpec, одним предложением?

Лёгкий слой согласования, который помогает вам и ИИ-ассистенту письменно договориться, что создавать, ещё до написания кода.

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

ИИ-ассистенты уверены в себе, даже когда ошибаются. Если требования существуют только в переписке, ИИ заполняет пробелы догадками, а вы узнаёте об этом уже после написания кода. OpenSpec помогает договориться раньше, когда исправление ошибок обходится недорого. Подробное обоснование см. в разделе Основные понятия вкратце.

Нужно ли использовать OpenSpec для всего?

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

Можно ли использовать OpenSpec в большой существующей кодовой базе или только в новых проектах?

OpenSpec в первую очередь предназначен для существующих кодовых баз. Не нужно заранее документировать всё приложение: пишите спецификации только для того, чего касается каждое изменение, и постепенно дополняйте их по мере работы. См. отдельное руководство Использование OpenSpec в существующем проекте.

OpenSpec работает только с одним ИИ-инструментом?

Нет. OpenSpec работает с более чем 30 ассистентами, включая Claude Code, Cursor, Devin Desktop, GitHub Copilot, Gemini CLI, Codex и другие. Полный список и сведения о каждом инструменте приведены в разделе Поддерживаемые инструменты.

Выполнение команд

Где вводить /opsx:propose?

В чате с ИИ-ассистентом, а не в терминале. Это самый частый источник путаницы, поэтому ему посвящена отдельная страница: Как работают команды. Кратко: openspec ... выполняется в терминале, /opsx:... — в чате.

Как «запустить интерактивный режим»?

Отдельного режима для запуска нет. Откройте ИИ-ассистента как обычно и введите slash-команду в чате. Так вы «входите» в OpenSpec. (Настоящая интерактивная функция в терминале — openspec view, панель для просмотра спецификаций и изменений.) Подробное объяснение см. в разделе Как работают команды.

Я ввёл slash-команду, но ничего не произошло. Почему?

Скорее всего, вы ввели команду в терминале, а не в чате с ИИ, использовали вариант написания, который инструмент не распознаёт, либо команды ещё не установлены. Если файлов нет или инструмент не был настроен, запустите openspec init; openspec update обновляет только уже существующие файлы. Затем перезапустите ассистента и используйте команду, напечатанную в разделе «Начало работы»; см. Вызов команд. Полный контрольный список приведён в разделе Устранение неполадок.

Почему в одном инструменте используется синтаксис /opsx:propose, а в другом — /opsx-propose?

Каждый ИИ-инструмент по-своему отображает пользовательские команды, а OpenSpec формирует их так, как инструмент загружает созданный файл. Команда из файла opsx-propose.md вызывается как /opsx-propose, а команда из commands/opsx/ — как /opsx:propose. В инструментах, использующих навыки вместо команд, применяется имя навыка: в Codex — $openspec-propose, в Kimi Code — /skill:openspec-propose. Команда openspec init уже выводит подходящий формат для выбранных вами инструментов; полная таблица находится в разделе Вызов команд.

Чем навык отличается от команды?

И то и другое — файлы, которые OpenSpec создаёт для запуска рабочего процесса в ассистенте. Навыки (.../skills/openspec-*/SKILL.md) — более новый универсальный стандарт; команды (.../commands/opsx-*) — более старые slash-файлы для отдельных инструментов. Выбирать не нужно: введите slash-команду, а OpenSpec установит подходящий для вашего инструмента вариант.

Рабочий процесс

С чего начать, если я не знаю, что создавать?

С /opsx:explore. Это партнёр для обдумывания без обязательств: он изучает кодовую базу, предлагает варианты и превращает расплывчатую проблему в конкретный план ещё до написания кода. Команда входит в профиль по умолчанию и всегда доступна. Когда план станет понятен, она передаст работу /opsx:propose. Это лучшая привычка, которая не даст увлечённому ИИ уверенно создать не то, что нужно. См. Сначала исследуйте.

Как выглядит самый простой рабочий процесс?

/opsx:explore (optional)   then   /opsx:propose <what you want>   then   /opsx:apply   then   /opsx:archive

Explore помогает обдумать задачу, propose составляет план, apply реализует его, а archive отправляет изменение в архив. Пропустите explore, если уже точно знаете, чего хотите.

Чем /opsx:propose отличается от /opsx:new?

/opsx:propose — стандартная команда для одного шага: она создаёт изменение и сразу подготавливает все артефакты планирования. /opsx:new входит в расширенный набор команд и только создаёт каркас пустого изменения; затем артефакты добавляются по одному с помощью /opsx:continue или сразу все — с помощью /opsx:ff. Используйте propose, если вам не нужен пошаговый контроль. См. раздел Команды.

Что такое профили core и expanded?

Профиль определяет, какие slash-команды будут установлены. По умолчанию профиль core предоставляет propose, explore, apply, update, sync и archive. Набор expanded добавляет new, continue, ff, verify, bulk-archive и onboard, обеспечивая более тонкий контроль. Переключитесь с помощью openspec config profile, а затем примените настройку командой openspec update.

Нужно ли запускать /opsx:sync?

Обычно нет. Sync объединяет дельта-спецификации изменения с основными спецификациями, а /opsx:archive предложит сделать это автоматически. Запускайте sync вручную, только если хотите объединить спецификации до архивации, например для длительного изменения. См. раздел Команды.

Как отредактировать предложение, спецификацию или задачу после начала работы?

Просто отредактируйте файл. Каждый артефакт — обычный Markdown в openspec/changes/<name>/; заблокированных этапов или особого режима редактирования нет. Внесите правки вручную или попросите ИИ обновить файл («измени проектное решение, чтобы использовать очередь»), а затем продолжайте. ИИ всегда использует актуальное содержимое файлов. Подробности: Редактирование и доработка изменения.

Можно ли вернуться и изменить план после частичной реализации?

Да, в любое время. Рабочий процесс гибкий, поэтому проверка и редактирование — не этапы, к которым нельзя вернуться. Измените артефакт и продолжайте. Чтобы структурированно проверить, соответствует ли код плану, запустите /opsx:verify. См. Редактирование и доработка изменения.

Я отредактировал код вручную. Как согласовать его со спецификацией?

Синхронизируйте их до архивации, поскольку после неё спецификации становятся источником истины. Если код теперь верен, обновите дельта-спецификацию, чтобы она описывала реализованное поведение; если верна спецификация, продолжайте разработку, пока код ей не будет соответствовать. Команда /opsx:verify покажет несоответствия. См. Редактирование и доработка изменения.

Когда следует обновить существующее изменение, а когда начать новое?

Обновляйте изменение, если уточняется та же работа. Начните заново, если цель принципиально изменилась или объём разросся до отдельной работы. Блок-схема и примеры приведены в разделе Рабочие процессы.

Что делать, если в сеансе закончился контекст или требования изменились в ходе реализации?

Именно здесь спецификации особенно полезны. План хранится в файлах, а не только в истории чата, поэтому можно очистить контекст, начать новый сеанс с ИИ и продолжить с /opsx:apply: команда прочитает артефакты и возобновит работу с первой неотмеченной задачи. Если требования изменятся, обновите артефакты в соответствии с новой ситуацией и продолжайте. Чистое окно контекста также улучшает результат; очистите его перед реализацией.

Нужно ли добавлять папку openspec/ в git?

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

Спецификации и изменения

Что относится к спецификации, а что — к проектному решению?

Спецификация описывает наблюдаемое поведение: что делает система, её входные и выходные данные и условия ошибок. Проектное решение описывает, как вы будете это реализовывать: технический подход, архитектурные решения, изменения файлов. Если реализация может измениться без изменения внешнего поведения, это относится к проектному решению, а не к спецификации. Подробнее см. Основные понятия.

Что такое дельта-спецификация?

Спецификация, описывающая только изменения с помощью разделов ADDED, MODIFIED и REMOVED, а не повторяющая весь документ. Благодаря этому OpenSpec удобно обновлять спецификации существующих систем. См. Основные понятия.

Куда перемещаются архивированные изменения?

В openspec/changes/archive/YYYY-MM-DD-<name>/ вместе со всеми артефактами изменения. Оно исчезает из списка активных изменений. Изменение, явно объявляющее retire_capabilities: true, также может удалить основную спецификацию возможности, если из неё удалено последнее требование.

Конфигурация и настройка

Как сообщить ИИ о технологическом стеке?

Укажите его в поле context: файла openspec/config.yaml. Этот текст добавляется к каждому запросу планирования, поэтому ИИ всегда знает ваш стек и соглашения. См. Настройка.

Можно ли создавать спецификации не на английском языке?

Да. Добавьте в поле context: конфигурации инструкцию о языке. В разделе Многоязычная работа приведены готовые фрагменты для нескольких языков.

Можно ли изменить сам рабочий процесс?

Да, с помощью пользовательских схем. Схема определяет, какие артефакты существуют и как они зависят друг от друга. Создайте копию схемы по умолчанию командой openspec schema fork spec-driven my-workflow, а затем измените её. См. Настройка.

Модели, конфиденциальность и обновления

Какую модель ИИ использовать?

OpenSpec лучше всего работает с моделями, способными к глубоким рассуждениям. В README для планирования и реализации рекомендуются, например, Codex 5.5 и Opus 4.7. Следите, чтобы окно контекста оставалось чистым: для наилучших результатов очистите его перед реализацией.

Собирает ли OpenSpec данные?

OpenSpec собирает анонимную статистику использования: только названия команд и версию. Аргументы, пути, содержимое и личные данные не собираются; в CI сбор автоматически отключён. Откажитесь от сбора с помощью export OPENSPEC_TELEMETRY=0 или export DO_NOT_TRACK=1.

Как обновить OpenSpec?

Два шага. Обновите пакет (npm install -g @fission-ai/openspec@latest), затем в каждом проекте запустите openspec update, чтобы обновить сгенерированные навыки и команды.

Как удалить OpenSpec?

Команды удаления нет, поскольку OpenSpec — это глобальный пакет и файлы в проекте. Удалите пакет (npm uninstall -g @fission-ai/openspec), а при желании также каталог openspec/ и сгенерированные файлы инструментов. Пошаговые инструкции, в том числе о том, что можно оставить, приведены в разделе Установка: удаление.

Получение помощи

Где задать вопрос или сообщить об ошибке?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Из терминала: команда openspec feedback "your message" создаст для вас задачу на GitHub.

В документации ошибка или что-то непонятно. Что делать?

Сообщите нам об этом или исправьте самостоятельно. Мы приветствуем и ценим пул-реквесты с правками документации. Создайте задачу или отправьте пул-реквест.