Разработка через OpenSpec

Что такое OpenSpec

OpenSpec — это рабочий процесс (и набор конвенций), при котором изменения живут в директории openspec/changes/ до тех пор, пока не будут реализованы и слиты. Каждое изменение — это набор документов: зачем, что меняем, как проверяем. Это превращает «историю коммитов» в читаемый трекер решений.

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

• Явность намерений. Прежде чем писать код, формулируется проблема и решение — спекуляция снижается.
• Независимый review. Спеку можно проверить до кода (GO/NO-GO), не читая реализацию.
• Воспроизводимость. Архив changes — это документация «почему мы так сделали», живущая рядом с кодом.
• Безопасные мелкие шаги. Большие фичи дробятся на проверяемые изменения с чёткими критериями приёмки.

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

1. 1
   Propose. Создаётся change с proposal.md (зачем/что/влияние).
2. 2
   Design & Spec. Пишутся design.md и спецификация требований (ADDED Requirements + Scenarios) в specs/.
3. 3
   Tasks. Реализация дробится на чек-лист в tasks.md.
4. 4
   Validate. openspec validate проверяет формат и внутреннюю непротиворечивость.
5. 5
   Implement & Review. Код пишется под задачи; независимый GO/NO-GO review до merge в защищённую ветку.
6. 6
   Archive. После слияния change архивируется, спецификации продвигаются в openspec/specs/ как актуальные.

Структура change

openspec/changes/<change-id>/
├── proposal.md      # зачем и что меняем
├── design.md        # как решаем (архитектура)
├── tasks.md         # чек-лист реализации
└── specs/<capability>/
    └── spec.md      # требования + сценарии (ADDED/MODIFIED)

Ключевые принципы

• Delta-формат. Спецификация описывает изменение (## ADDED Requirements), а не полный снимок системы.
• Scenarios > абстракции. Каждое требование подкрепляется конкретным сценарием приёмки.
• Fail-closed gates. Непрошедшая валидация или тесты блокируют деплой, а не предупреждают.
• Review до кода. Спека получает GO/NO-GO независимым ревьюером раньше, чем написан код.