Глоссарий

Все термины OpenSpec собраны в одном месте и объяснены простыми словами. Просмотрите глоссарий, и остальная документация будет читаться быстрее.

Термины сгруппированы по темам и отсортированы по алфавиту внутри каждой группы.

Основные понятия

Spec (спецификация). Документ, описывающий поведение части системы. Спецификации хранятся в openspec/specs/, сгруппированы по областям и состоят из требований и сценариев. Это согласованный ответ на вопрос «что делает это программное обеспечение?». См. Основные понятия.

Source of truth (источник истины). Каталог openspec/specs/ целиком. В нём хранится актуальное согласованное описание поведения системы. Изменения предлагают правки, а архивация применяет их.

Change (изменение). Единица работы, оформленная в виде папки openspec/changes/<name>/. В папке собраны все материалы работы: предложение, проектное решение, задачи и правки спецификаций. Одно изменение — одна функция или исправление.

Artifact (артефакт). Документ внутри изменения. Стандартные артефакты — предложение, дельта-спецификации, проектное решение и задачи. Они создаются с учётом зависимостей и служат основой друг для друга.

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

Domain (область). Логическая группа спецификаций, например auth/, payments/ или ui/. Выбирайте области в соответствии с тем, как вы воспринимаете свою систему.

Внутри спецификации

Requirement (требование). Одно поведение, которое должна обеспечивать система. Обычно формулируется с ключевым словом RFC 2119: «Система SHALL завершать сеансы через 30 минут». Требования описывают что делает система, а не как.

Scenario (сценарий). Конкретный проверяемый пример выполнения требования, обычно в формате Given/When/Then. Сценарии делают требования проверяемыми: на их основе можно написать автоматизированный тест.

Ключевые слова RFC 2119. Слова MUST, SHALL, SHOULD и MAY, задающие стандартизированную степень обязательности требования. MUST и SHALL означают безусловное требование. SHOULD — рекомендацию, допускающую исключения. MAY — необязательное условие. Название происходит от документа интернет-стандарта, в котором они были определены.

Артефакты

Proposal (proposal.md, предложение). Зачем и что изменения: его цель, область работ и общий подход. Первый создаваемый артефакт.

Design (design.md, проектное решение). Как выполнить изменение: технический подход, архитектурные решения и файлы, которые планируется затронуть. Для простых изменений необязательно.

Tasks (tasks.md, задачи). Контрольный список реализации с флажками. Во время /opsx:apply ИИ последовательно выполняет задачи и отмечает их.

Жизненный цикл

Archive (архивация). Завершение изменения. Его дельта-спецификации объединяются с основными спецификациями, а папка изменения переносится в openspec/changes/archive/YYYY-MM-DD-<name>/. После архивации спецификации описывают новое состояние системы. См. Основные понятия.

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

Рабочий процесс и команды

OPSX. Современный стандартный рабочий процесс OpenSpec, основанный на гибких действиях, а не жёстких этапах. Все его slash-команды начинаются с /opsx:. См. Рабочий процесс OPSX.

Slash-команда. Команда, которую вводят в чате с ИИ-ассистентом, например /opsx:propose. Slash-команды управляют рабочим процессом; это не команды терминала. См. Как работают команды.

Explore (/opsx:explore). Команда-партнёр для обдумывания. Она изучает кодовую базу, сравнивает варианты и превращает расплывчатую идею в конкретный план. Команда никогда не пишет код и ничего не записывает, если вы не попросите сохранить результаты исследования как изменение или не согласитесь на её предложение. Рекомендуемая отправная точка, если проблема уже есть, а плана ещё нет. См. Сначала исследуйте.

CLI. Программа openspec, которую вы запускаете в терминале. Она настраивает проекты, выводит список изменений и проверяет их, открывает панель управления и архивирует изменения. Терминальная часть OpenSpec. См. CLI.

Skill (навык). Папка инструкций (.../skills/openspec-*/SKILL.md), которую ИИ-ассистент автоматически обнаруживает и использует. Навыки становятся универсальным межплатформенным стандартом для интеграции рабочего процесса OpenSpec с ассистентом.

Файл команды. Файл slash-команды для конкретного инструмента (.../commands/opsx-*). Это более старый способ распространения, который по-прежнему поддерживается наряду с навыками. Обычно напрямую изменять такие файлы не требуется.

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

Delivery (способ установки). Определяет, устанавливает ли OpenSpec навыки, файлы команд или оба варианта для ваших инструментов. Настраивается глобально и применяется командой openspec update.

Настройка

Schema (схема). Описание артефактов рабочего процесса и их зависимостей. Встроенная схема по умолчанию — spec-driven (предложение → спецификации → проектное решение → задачи). Её можно скопировать и изменить или создать собственную. См. Настройка.

Template (шаблон). Markdown-файл в схеме, задающий содержание артефакта, который генерирует ИИ. Изменения шаблона сразу влияют на результат ИИ; повторная сборка не нужна.

Конфигурация проекта (openspec/config.yaml). Настройки конкретного проекта: схема по умолчанию, context:, добавляемый к каждому запросу планирования, и rules: для отдельных артефактов. Это простой способ рассказать OpenSpec о вашем технологическом стеке и соглашениях. См. Настройка.

Внедрение контекста. Добавление сведений о проекте в поле context: файла config.yaml, чтобы они автоматически включались в каждый создаваемый ИИ артефакт. Это надёжнее, чем надеяться, что ИИ прочитает отдельный файл.

Граф зависимостей. Направленный граф, образованный отношениями requires: между артефактами. Это DAG (направленный ациклический граф: стрелки направлены вперёд и не образуют циклов), который OpenSpec использует, чтобы определить, что можно создавать следующим.

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

Координация между репозиториями (бета-версия)

Эти термины нужны, только если планирование охватывает несколько репозиториев. Функция находится в бета-версии, и большинству пользователей этот раздел не понадобится. См. Руководство по хранилищам.

Store (хранилище). Отдельный репозиторий, предназначенный для планирования. Он имеет знакомую структуру openspec/ (спецификации и изменения) и небольшой файл идентификации. Достаточно один раз зарегистрировать его на компьютере под именем — после этого любая команда OpenSpec сможет работать с ним откуда угодно.

Reference (ссылка). Объявление в openspec/config.yaml репозитория с кодом, указывающее на используемое им хранилище. Ссылки доступны только для чтения: у репозитория остаётся собственный корень, а openspec instructions получает индекс спецификаций связанного хранилища с точной командой для получения каждой из них.

Рабочий контекст. Набор сведений, который openspec context формирует для текущего репозитория: его корень OpenSpec и все связанные с ним хранилища, включая инструкции по получению данных из каждого. Ответ на вопрос «с чем я сейчас работаю?»

Workset (рабочий набор). Личный набор локальных папок, которые открываются вместе (например, хранилище и репозитории с кодом, над которыми вы работаете). Создаётся явной командой openspec workset create; локальные пути не попадают в общий репозиторий планирования.

См. также

• Основные понятия вкратце: пять идей на одной странице
• Основные понятия: подробное объяснение
• Как работают команды: slash-команды и CLI