OpenSpec

Глоссарий ​

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

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

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

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

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

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

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

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

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

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

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

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

RFC 2119 keywords. Слова 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, построенный вокруг гибких действий вместо жестких фаз. Все его слэш-команды начинаются с /opsx:. См. Рабочий процесс OPSX.

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

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

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

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

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

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

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

Настройка ​

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

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

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

Context injection (Внедрение контекста). Добавление фона проекта в поле context: файла config.yaml, чтобы он автоматически добавлялся к каждому артефакту, генерируемому ИИ. Более надежный способ, чем надеяться, что ИИ прочитает отдельный файл.

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

Enablers, not gates (Разрешители, а не шлюзы). Принцип, согласно которому зависимости артефактов показывают, что становится возможным следующим, а не тем, что требуется следующим. Вы можете вернуться и отредактировать любой артефакт в любое время. См. Основные концепции в двух словах.

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

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

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

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

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

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

См. также ​