OpenSpec — это лёгкий слой соглашений между тобой и твоим ИИ-ассистентом. Ты записываешь, что должно делать изменение, ИИ расписывает детали, вы смотрите на один и тот же план — и только потом пишется код. Вся идея в пяти словах: договорись сначала, потом строй уверенно.
← К разделу OpenSpec на сайтеПредставь знакомую ситуацию: ты говоришь ИИ «добавь тёмную тему», а получаешь непонятно что. OpenSpec лечит именно это.
Ты строишь софт, объясняя ИИ-инструментам, чего хочешь, на человеческом языке. Часто ты сам не смотрел в код — и это нормально. Проблема: ИИ догадывается, и догадка бывает не той.
OpenSpec переворачивает подход. Вместо «напиши код» ты сначала описываешь изменение словами: зачем, что меняем, как проверим. ИИ превращает это в структурированный план. Ты читаешь план, поправляешь — и только потом код пишется по плану, который вы оба видели.
# ты говоришь ассистенту:
/opsx:propose add-dark-mode
# ИИ создаёт в openspec/changes/add-dark-mode/
proposal.md # зачем и что
specs/ # что меняется (delta)
design.md # как технически
tasks.md # чек-лист шаговТы просишь не «сделай тёмную тему», а «оформи предложение добавить тёмную тему».
ИИ не лезет сразу в код. Он создаёт папку с планом из четырёх документов.
«Зачем и что» — одно предложение о намерении изменения, без кода.
«Что меняется» — кусочек спецификации, описывающий только разницу.
«Как технически» — архитектурное решение и файлы, которые тронем.
«Чек-лист шагов» — по нему ИИ будет строить и отмечать сделанное.
Весь OpenSpec живёт в двух папках. Одна — что работает прямо сейчас. Другая — что ты предлагаешь изменить.
Спеки (specs) — это источник правды. Они описывают, как система ведёт себя сейчас, разложены по доменам (auth/, payments/, ui/). Спеку можно проверить: «делает ли система то, что в ней написано?»
Изменение (change) — это предложенное изменение. Одна папка в openspec/changes/ = одна фича или фикс. В ней лежат все документы про эту работу в одном месте.
Разделение — ключевое. Можно вести несколько изменений параллельно без конфликтов. Можно пересмотреть изменение, пока оно не коснулось основных спек. А когда архивируешь — его дельта чисто сливается в источник правды.
Внутри изменения ты не переписываешь всю спеку. Ты пишешь крошечную дельту: ADDED это, MODIFIED то, REMOVED другое.
Это фокус, который делает OpenSpec удобным для доработки существующих систем, а не только для проектов с нуля. Ты описываешь diff, а не пункт назначения.
## ADDED Requirements
### Requirement: Dark Mode Toggle
The system SHALL provide a UI toggle
that switches between light and dark themes.
## MODIFIED Requirements
### Requirement: Default Theme
The system SHALL default to the OS preference
instead of always light. (was: always light)
## REMOVED Requirements
### Requirement: Hardcoded Light BG
Removed: theme is now configurable.ADDED — новое поведение, которого раньше не было (переключатель тем).
MODIFIED — поведение, что уже было и меняется. Пишешь полную новую версию + пометку, что изменилось.
На архиве ADDED добавится в основную спеку, MODIFIED заменит старую версию.
REMOVED — поведение уходит. На архиве выкинется из спеку.
Ты описываешь только разницу, а не переписываешь всю систему заново.
В типичной настройке твой день выглядит так: подумал → предложил → применил → заархивировал.
Команды начинаются с /opsx: и вводятся в чат с ассистентом (это не терминальные команды). По желанию сначала думаешь вслух с ИИ, потом одна команда черновикует план, ты его читаешь, следующая строит, последняя убирает в архив.
Спека — это поведение, не код. Она сделана из требований (что система ДОЛЖНА) и сценариев (конкретных примеров).
Требование пишут со словом SHALL (или MUST) — это жёстко, без вариантов. Хорошее требование — одно поведение, сформулированное так, что посторонний сможет проверить. Сценарий — это дано/когда/тогда, из которого можно собрать автотест.
### Requirement: Session Timeout
The system SHALL expire a session after
30 minutes of inactivity.
#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass with no activity
- THEN session invalidated, re-auth neededТребование названо понятно: «тайм-аут сессии».
SHALL = жёсткое правило. «После 30 минут бездействия сессия истекает».
Сценарий — конкретный случай, а не пересказ требования.
GIVEN — исходное состояние (залогинен).
WHEN — триггер (прошло 30 мин тишины).
THEN — результат (сессия сброшена, просят залогиниться снова).
The system SHALL handle large uploads gracefully.The system SHALL show an error banner when the upload exceeds 10 MB.Несколько терминов, чтобы дальше читать доки быстрее. А потом — как это запустить у себя.
Документ, как часть системы ведёт себя. В openspec/specs/, по доменам. Ответ на вопрос «что делает софт?»
Одна единица работы = папка в openspec/changes/. Внутри: proposal, design, tasks, delta spec.
Спека внутри изменения: только ADDED / MODIFIED / REMOVED. Описывает разницу, не весь мир.
Документ внутри изменения (proposal, delta spec, design, tasks). Создаются в порядке зависимости.
Завершение изменения: дельта сливается в specs, папка уходит в changes/archive/ДАТА-имя/.
Стандартный воркфлоу OpenSpec. Команды со слэшем: /opsx:explore, propose, apply, archive.
openspec init через CLI), скажи ассистенту «преврати это в предложение» — и используй /opsx:explore, когда идея туманна, а /opsx:propose, когда уже понятно.
Этот самый сайт (AI-Disrupt PDLC Coach) разрабатывался через OpenSpec: каждое добавление — публикация, модалка контактов, этот курс — прошло цикл propose → review → apply → archive.
Команда /opsx:archive — это «закрытие цикла». Разберём по шагам, что она делает с твоими файлами.
Пока изменение живёт в openspec/changes/<имя>/, его дельта — это только предложение. Спеки в openspec/specs/ ещё не знают о новом поведении. Когда ты архивируешь:
openspec/specs/<capability>/spec.md.openspec/changes/archive/2026-08-19-<имя>/ — с датой, чтобы история была читаемой.После архива openspec/specs/ описывает новую реальность, а ты готов к следующему изменению. Цикл замкнулся.
# openspec/specs/ui/spec.md (источник правды)
### Requirement: Default Theme
The system SHALL always render light theme.
# openspec/changes/persist-theme/ (предложение)
## MODIFIED Requirements
### Requirement: Default Theme
The system SHALL follow OS preference.Папка changes/persist-theme/ уехала в archive/2026-08-19-persist-theme/.
В specs/ui/spec.md старая строка «always light» заменена на «follow OS preference».
Источник правды теперь отражает то, что реально работает.
Самая частая ошибка спецификации — туманное требование. Хороший сценарий конкретен и проверяем посторонним.
Плохое требование: «Система должна аккуратно обрабатывать большие загрузки». Что значит «аккуратно»? Как проверить? Посторонний не поймёт, прошло ли оно.
Хорошее требование со словом SHALL + сценарий в GIVEN/WHEN/THEN, из которого можно собрать автотест:
# ПЛОХО
### Requirement: Large uploads
The system SHALL handle large uploads gracefully.
# ХОРОШО
### Requirement: Upload size limit
The system SHALL show an error banner
when an upload exceeds 10 MB.
#### Scenario: Oversized file rejected
GIVEN an authenticated user
WHEN they upload a 25 MB file
THEN an error banner appears, upload blocked«Gracefully» — не проверяемо. Замени на измеримое: лимит 10 МБ + баннер ошибки.
Сценарий назван конкретно («Oversized file rejected»), а не «Test 2».
GIVEN/WHEN/THEN можно прямо переложить в автотест.