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

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

Основы

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

Это легковесный слой, который помогает вам и вашему помощнику по коду ИИ согласовать, что именно нужно создать, письменно, прежде чем будет написан какой-либо код.

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

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

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

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

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

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

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

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

Команды

Где я набираю /opsx:propose?

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

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

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

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

Вероятно, вы набрали ее в терминале, а не в чате своего ИИ, или команды еще не установлены. Запустите openspec update в своем проекте, перезапустите помощника и попробуйте ввести /opsx в чате, обращая внимание на автозаполнение. Troubleshooting содержит полный контрольный список.

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

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

Какова разница между навыком (skill) и командой (command)?

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

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

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

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

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

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

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

Какова разница между /opsx:propose и /opsx:new?

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

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

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

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

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

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

Просто отредактируйте файл. Каждый артефакт — это обычный 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?

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

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

Что входит в спецификацию (spec), а что — в дизайн (design)?

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

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

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

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

В openspec/changes/archive/YYYY-MM-DD-<name>/, с сохранением всех артефактов. Ничего не удаляется; изменение просто перемещается из вашего активного списка.

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

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

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

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

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

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

Да, с помощью пользовательских схем (schemas). Схема определяет, какие артефакты существуют и как они зависят друг от друга. Форкните стандартную схему командой 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.

Как мне обновиться?

Два шага. Обновите пакет (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 "ваше сообщение" откроет для вас задачу в GitHub.

Эти документы неверны или сбивают с толку. Что мне делать?

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