FAQ

Быстрые ответы на вопросы, которые задают чаще всего. Если ваш вопрос на самом деле касается «что-то сломано», лучше подойдёт страница Troubleshooting. Если вам нужно определение термина, обратитесь к Glossary.

Основы

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

Лёгкий слой, который помогает вам и вашему ИИ-ассистенту согласовать, что именно вы будете строить, в письменной форме, до того как будет написан хоть один код.

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

Потому что ИИ-ассистенты уверены, даже когда ошибаются. Когда требования живут только в чате, ИИ заполняет пробелы догадками, и вы узнаёте об этом уже после того, как код существует. OpenSpec переносит согласование на более ранний этап, где ошибки исправлять дешевле. Полное обоснование см. в Core Concepts at a Glance.

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

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

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

Существующие кодовые базы — это основной случай. OpenSpec ориентирован на работу с существующим кодом (brownfield-first): вы не документируете всё приложение заранее. Вы пишете спецификации только для того, что затрагивает каждое изменение, и ваши спецификации постепенно заполняются по мере выполнения реальной работы. Есть специальное руководство: Using OpenSpec in an Existing Project.

Привязан ли он к одному ИИ-инструменту?

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

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

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

В чате вашего ИИ-ассистента, а не в терминале. Это самый распространённый источник путаницы, поэтому для него есть отдельная страница: How Commands Work. Короткая версия: openspec ... выполняется в терминале, /opsx:... — в чате.

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

Отдельного режима для запуска нет. Вы открываете своего ИИ-ассистента как обычно и вводите слеш-команду в чат. Слеш-команда — это способ «войти» в OpenSpec. (Единственная действительно интерактивная функция терминала — openspec view, панель для просмотра спецификаций и изменений.) Полное объяснение в How Commands Work.

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

Скорее всего, вы ввели её в терминале, а не в чате ИИ, использовали написание, которое ваш инструмент не распознаёт, или команды ещё не установлены. Если файлы отсутствуют — или вы не настроили инструмент — запустите openspec init; openspec update только обновляет уже существующие файлы. Затем перезапустите ассистента и используйте форму, напечатанную в разделе «Getting started» — см. How To Invoke. В Troubleshooting есть полный чек-лист.

Почему синтаксис /opsx:propose в одном инструменте и /opsx-propose в другом?

Каждый ИИ-инструмент отображает пользовательские команды немного по-разному, и OpenSpec записывает их так, как ваш инструмент загружает файл, который он создаёт. Файл команды с именем opsx-propose.md вводится как /opsx-propose; файл, размещённый в commands/opsx/, вводится как /opsx:propose. Инструменты, которые используют навыки (skills) вместо команд, используют имя навыка — Codex требует $openspec-propose, Kimi Code — /skill:openspec-propose. Строка «Getting started» из openspec init уже печатает правильную форму для выбранных вами инструментов; полная таблица в How To Invoke.

В чём разница между навыком и командой?

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

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

С чего мне начать, если я не уверен, что нужно строить?

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

Какой самый простой возможный поток?

/opsx:explore (необязательно)   затем   /opsx:propose <что вы хотите>   затем   /opsx:apply   затем   /opsx:archive

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

В чём разница между /opsx:propose и /opsx:new?

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

Что такое core и расширенные профили?

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

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

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

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

Просто отредактируйте файл. Каждый артефакт — это обычный Markdown в openspec/changes/<name>/, и нет заблокированных фаз или специального режима редактирования. Меняйте его вручную или попросите ИИ пересмотреть («обновите дизайн, чтобы использовать очередь»), затем продолжайте. ИИ всегда работает с текущим содержимым файла. Полное руководство: Editing & Iterating on a Change.

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

Да, в любое время. Рабочий процесс гибок, поэтому обзор и редактирование — это не фазы, из которых вас блокируют. Отредактируйте артефакт и продолжайте. Если хотите проверить, что код всё ещё соответствует плану, запустите /opsx:verify. См. Editing & Iterating on a Change.

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

Приведите их в соответствие перед архивацией, потому что после архивации спецификации становятся источником истины. Если код теперь правильный, обновите дельта-спецификацию, чтобы соответствовать тому, что вы выпустили; если спецификация правильная, продолжайте разработку, пока код не согласуется. /opsx:verify выявляет расхождения. См. Editing & Iterating on a Change.

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

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

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

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

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

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

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

Что идёт в спецификацию, а что в дизайн?

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

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

Спецификация, которая описывает только изменения, используя секции ADDED, MODIFIED и REMOVED, вместо пересказа всей спецификации. Так OpenSpec аккуратно обрабатывает изменения существующих систем. См. Concepts.

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

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

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

Как рассказать ИИ о моём технологическом стеке?

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

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

Да. Добавьте языковую инструкцию в context: вашей конфигурации. В Multi-Language есть готовые фрагменты для нескольких языков.

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

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

Модели, приватность и обновления

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

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

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

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

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

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

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

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

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

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

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Из терминала: openspec feedback "ваше сообщение" создаст для вас issue на GitHub.

Эти документы неправильные или запутанные. Что делать?

Сообщите нам или исправьте. PR с документацией приветствуются и ценятся. Откройте issue или отправьте pull request.