Глоссарий

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

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

Основные существительные

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

Source of truth. Весь каталог openspec/specs/. Он содержит текущее, согласованное поведение вашей системы. Изменения предлагают правки в него; архивирование применяет их.

Change. Одна единица работы, упакованная как папка под openspec/changes/<name>/. Change содержит все о этой работе: ее предложение, дизайн, задачи и правки spec, которые она вносит. Один change — одна функция или исправление.

Artifact. Документ внутри change. Стандартные артефакты — это предложение (proposal), delta specs, дизайн и задачи. Они создаются в порядке зависимостей и влияют друг на друга.

Delta spec. Spec внутри change, которое описывает только то, что меняется, используя разделы ADDED, MODIFIED и REMOVED, а не пересказывая весь spec. Это позволяет OpenSpec чисто редактировать существующие системы. См. Concepts.

Domain. Логическая группа для specs, например auth/, payments/ или ui/. Вы выбираете домены, которые соответствуют вашему представлению о системе.

Внутри spec

Requirement. Одно поведение, которое должна иметь система, обычно записанное с использованием ключевого слова RFC 2119: «Система ДОЛЖНА истекать сессии через 30 минут». Requirements описывают что, а не как.

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

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

Артефакты

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

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

Tasks (tasks.md). Чек-лист реализации с флажками. AI проходит по нему во время /opsx:apply и отмечает пункты по мере выполнения.

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

Archive. Действие завершения изменения. Его delta specs сливаются в основные specs, а папка change перемещается в openspec/changes/archive/YYYY-MM-DD-<name>/. После архивирования ваши specs описывают новую реальность. См. Concepts.

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

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

OPSX. Текущий стандартный рабочий процесс OpenSpec, основанный на гибких действиях, а не на жестких фазах. Все его слэш-команды начинаются с /opsx:. См. OPSX Workflow.

Slash command. Команда, которую вы вводите в чат своего AI-ассистента, например /opsx:propose. Slash commands управляют рабочим процессом. Это не терминальные команды. См. How Commands Work.

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

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

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

Command file. Файл слэш-команды для конкретного инструмента (.../commands/opsx-*). Более старый механизм доставки, который все еще поддерживается наряду со skills. Вы редко трогаете их напрямую.

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

Delivery. То, устанавливает ли OpenSpec skills, command files или оба для ваших инструментов. Настраивается глобально и применяется командой openspec update.

Кастомизация

Schema. Определение того, какие артефакты есть в рабочем процессе и как они зависят друг от друга. Встроенный вариант по умолчанию — spec-driven (proposal → specs → design → tasks). Вы можете форкнуть его или написать свой собственный. См. Customization.

Template. Markdown-файл внутри schema, который формирует то, что AI генерирует для данного артефакта. Редактирование шаблона немедленно меняет вывод AI без пересборки.

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

Context injection. Размещение информации о проекте в поле context: файла config.yaml, чтобы она автоматически добавлялась ко всем артефактам, генерируемым AI. Это надежнее, чем надеяться на то, что AI прочитает отдельный файл.

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

Enablers, not gates. Принцип, согласно которому зависимости артефактов показывают, что становится возможным следующим, а не то, что требуется следующим. Вы можете пересматривать и редактировать любой артефакт в любое время. См. Core Concepts at a Glance.

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

Эти термины применимы, только если ваше планирование охватывает более одного репозитория. Они находятся в бета-версии. Большинству пользователей их можно игнорировать. См. Stores User Guide.

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

Reference. Объявление в файле openspec/config.yaml репозитория кода о store, на который опирается этот репозиторий. References являются только для чтения: репозиторий сохраняет свой собственный корень, а openspec instructions получает индекс specs referenced store, каждый с точной командой для его получения.

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

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

См. также

• Core Concepts at a Glance: пять идей на одной странице
• Concepts: подробное объяснение
• How Commands Work: слэш-команды против CLI