Урок 2.10. OpenSpec

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

OpenSpec важен для курса как пример lightweight SDD workflow, который особенно хорошо подходит для brownfield changes.

Многие SDD-подходы начинаются с полной feature specification. Это полезно, но в существующем продукте часто нужно не описать весь мир, а внести конкретное изменение:

Добавить 2FA.
Изменить правила поиска.
Добавить фильтр по роли.
Исправить edge case в billing.

OpenSpec строится вокруг change proposals и delta specs. Он помогает ответить:

Что именно меняется в текущем source of truth?

Основная идея

OpenSpec разделяет две вещи:

Current truth
Proposed change

Current truth лежит в:

openspec/specs/

Proposed changes лежат в:

openspec/changes/

Это меняет мышление. Агент не "придумывает feature с нуля", а предлагает изменение к уже существующим specs.

Ключевые термины

Как это устроено

OpenSpec хорош тем, что не смешивает current state и proposed state. Пока change не принят и не архивирован, он остается отдельным working unit.

Repository layout

Типовая структура:

openspec/
  project.md
  specs/
    auth/
      spec.md
    projects/
      spec.md
  changes/
    add-profile-filters/
      proposal.md
      design.md
      tasks.md
      specs/
        profiles/
          spec.md

Смысл:

• project.md задает project context, conventions, architecture notes;
• specs/ хранит living system specs;
• changes/ хранит active work;
• внутри change лежат proposal, tasks and deltas;
• после archive change перестает быть active work и становится history.

Как пользоваться

Установка на обзорном уровне:

npm install -g @fission-ai/openspec@latest
openspec init

Затем полезно заполнить project context:

Please read openspec/project.md and help me fill it out
with details about the project, tech stack, conventions, and boundaries.

Типовой workflow:

/opsx:explore
-> /opsx:propose <change>
-> review proposal/design/tasks
-> openspec validate <change>
-> /opsx:apply
-> tests and verification
-> /opsx:archive

CLI и slash commands имеют разные роли. CLI проверяет и управляет OpenSpec files. Slash commands обычно запускаются в AI assistant chat.

Delta format

OpenSpec encourages requirements deltas:

## ADDED Requirements

### Requirement: Profile role filter
The system SHALL allow users to filter profiles by role.

#### Scenario: Filter by engineering role
- WHEN the user selects "Engineering"
- THEN only engineering profiles are shown

Для modified behavior нужно обновлять requirement полностью, а не писать "изменить немного". Это важно для AI agents: partial patches часто создают ambiguity.

Пример: фильтры профилей

Задача:

Добавить поиск profiles по role и team.

Prompt:

Use OpenSpec.

Start with `/opsx:propose add-profile-filters`.

The proposal must cover:
- role filter
- team filter
- empty result state
- no changes to authentication
- no changes to profile ownership rules

Do not implement until proposal, deltas, and tasks are reviewed.

Expected artifacts:

openspec/changes/add-profile-filters/
  proposal.md
  design.md
  tasks.md
  specs/
    profiles/
      spec.md

Review questions:

• Does the delta modify the right capability?
• Are non-goals explicit?
• Are scenarios concrete?
• Does tasks.md include tests?
• Does implementation require API contract update?

Когда OpenSpec полезен

OpenSpec хорошо подходит, когда:

• проект уже существует;
• changes маленькие или средние;
• нужно хранить living specs;
• важно отделять proposed changes from current truth;
• команда хочет lightweight SDD;
• разные agents должны читать один и тот же spec store;
• нужно архивировать completed work.

Особенно сильный кейс:

Brownfield product with many incremental changes.

Когда не стоит брать

OpenSpec может быть не лучшим выбором, если:

• команда хочет full lifecycle methodology с ролями;
• feature полностью greenfield и требует product discovery;
• нужен strict multi-phase governance;
• проект не готов поддерживать living specs;
• change слишком маленький и не меняет behavior.

OpenSpec не отменяет architecture docs. Если system boundaries неясны, delta spec будет фиксировать путаницу, а не устранять ее.

OpenSpec vs Spec Kit

Это не "кто лучше". Это разные способы управлять ambiguity.

Prompt patterns

Explore first

Use OpenSpec.
Start with `/opsx:explore`.
Read the relevant code and current specs.
Help me decide whether this needs a new change proposal or an update to an existing spec.
Do not write code.

Create proposal

/opsx:propose add-project-templates

Include:
- proposal.md
- tasks.md
- spec deltas
- design.md only if needed

Make non-goals explicit.

Validate before implementation

Before applying the change:
- run openspec validate add-project-templates
- check that each requirement has concrete scenarios
- confirm tasks map to requirements
- stop if validation fails

Типичные ошибки

Ошибка 1. Редактировать living spec напрямую

Если change не trivial, лучше создать change proposal. Иначе теряется reviewable history.

Ошибка 2. Делать delta слишком vague

Плохо:

Add better profile search.

Лучше:

The system SHALL filter profiles by role and team.

Ошибка 3. Архивировать без verification

Archive должен означать, что change implemented and verified. Если tests не прошли, archive превращает незавершенную работу в ложную историю.

Ошибка 4. Забыть обновить contract

Если change меняет API, OpenSpec spec alone недостаточен. Нужно обновить OpenAPI/JSON Schema/types и запустить contract checks.

Практика

Опишите change proposal для маленького изменения:

Change name:
Problem:
What changes:
What does not change:
Requirements added:
Requirements modified:
Tasks:
Verification:

Проверьте, можно ли понять change без чтения chat history.

Критерии готовности

После урока студент должен уметь:

• объяснить разницу между current spec и change proposal;
• описать структуру openspec/;
• понять, когда нужен /opsx:explore;
• написать delta requirement;
• объяснить, зачем нужен archive;
• встроить OpenSpec в agent workflow.

Краткое резюме

OpenSpec делает SDD change-oriented. Его сила в том, что current truth и proposed changes разделены. Это особенно полезно для existing products, где agent должен не изобретать систему заново, а аккуратно менять согласованные capabilities.

Вопросы для самопроверки

1. Зачем OpenSpec разделяет specs/ и changes/?
2. Когда лучше начать с /opsx:explore?
3. Почему archive нельзя делать до verification?
4. Чем delta spec удобен для brownfield?
5. Когда OpenSpec нужно дополнять OpenAPI или contract tests?

Источники для актуализации

• OpenSpec repository: https://github.com/Fission-AI/OpenSpec
• OpenSpec docs: https://github.com/Fission-AI/OpenSpec/tree/main/docs

Что дальше

Следующий урок разберет BMAD Method - более широкий full lifecycle framework, где SDD становится частью AI-driven agile process с ролями, PRD, architecture, epics and stories.

Глубокий разбор OpenSpec по официальной документации - установка, концепции, справочники команд, Stores, кастомизация и архитектура OPSX - вынесен в отдельный модуль 15.