Основные понятия вкратце

OpenSpec — это лёгкий слой согласования между вами и ИИ. Вы описываете, что должно делать изменение, ИИ составляет подробности, вы вместе изучаете один и тот же план и только после этого пишете код. На этой странице — вся модель в одном месте. Подробное объяснение есть в разделе Основные понятия.

Вся идея в пяти словах: сначала договориться, затем уверенно создавать.

Пять идей

В основе OpenSpec лежат пять понятий. Разберитесь в них — всё остальное будет деталями.

1. Спецификации — источник истины. Спецификация описывает, как ваша система работает сейчас. Она находится в openspec/specs/ и организована по областям (auth/, payments/, ui/). Спецификации состоят из требований («система ДОЛЖНА завершать сеансы через 30 минут») и сценариев (конкретные примеры в формате «дано/когда/тогда»). Считайте спецификации единым согласованным ответом на вопрос «что делает это программное обеспечение?»

2. Изменение — это единица работы. Чтобы добавить, изменить или удалить поведение, создайте изменение: папку в openspec/changes/, где собрано всё, относящееся к этой работе: предложение, проектное решение, список задач и правки спецификаций. Одно изменение, одна папка, одна функция.

3. Дельта-спецификации описывают изменения, а не весь мир. Внутри изменения не нужно переписывать спецификацию целиком. Вместо этого создаётся небольшая дельта: это требование ADDED (добавлено), то MODIFIED (изменено), а другое REMOVED (удалено). Благодаря этому OpenSpec подходит для доработки существующих систем, а не только для новых проектов. Описывайте разницу, а не конечное состояние.

4. Артефакты создаются один на основе другого. Изменение содержит несколько документов, которые создаются в естественном порядке, и каждый служит основой для следующего:

proposal ──► specs ──► design ──► tasks ──► implement
   зачем      что        как       шаги       сделать

К любому из них можно вернуться в любой момент. Это опоры, а не обязательные этапы. (Подробнее ниже.)

5. Архивация возвращает изменение в источник истины. Закончив работу, архивируйте изменение. Его дельта-спецификации объединятся с основными спецификациями, а папка изменения переместится в changes/archive/ с отметкой даты. Теперь спецификации описывают новое состояние системы, и можно приступать к следующему изменению. Цикл завершён.

Схема

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ источник истины  │объединить│ одна папка на изменение │    │
│   │ как система      │при       │ предложение · решение    │    │
│   │ работает сейчас  │архивации │ задачи · дельта-спецификации│ │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Всего две папки. specs/ — то, что уже верно. changes/ — то, что вы предлагаете. Архивация переносит предложение в источник истины.

Рабочий цикл

В стандартной конфигурации работа выглядит так. При желании сначала обдумайте идею; затем одна команда подготовит план, вы прочитаете его, следующая команда реализует его, а последняя отправит изменение в архив.

/opsx:explore                   →  (необязательно) сначала обдумайте задачу с ИИ
/opsx:propose add-dark-mode     →  ИИ подготовит предложение, спецификации, решение и задачи
        (вы читаете и корректируете план)
/opsx:apply                     →  ИИ реализует изменение, отмечая выполненные задачи
/opsx:archive                   →  спецификации обновлены, изменение архивировано

Если сомневаетесь, начните с исследования. /opsx:explore — безопасный партнёр для обдумывания: он изучит код, предложит варианты и превратит смутную идею в конкретный план ещё до написания кода. Это лучший способ не дать ИИ построить что-нибудь по расплывчатому запросу. Уже точно знаете, чего хотите? Сразу переходите к /opsx:propose. Команда explore входит в профиль по умолчанию и всегда доступна. См. руководство по исследованию.

Это slash-команды, которые вводятся в чате ИИ-ассистента. Настройка (openspec init) выполняется в терминале. Если такое разделение для вас новое, сначала прочитайте Как работают команды — чаще всего именно здесь возникает путаница.

«Опоры, а не обязательные этапы»

Эта фраза часто встречается в OpenSpec. Вот что она означает простыми словами.

Традиционные процессы работы со спецификациями устроены по каскадной модели: сначала завершите планирование, затем приступайте к реализации, а возвращаться назад трудно. OpenSpec отказывается от такого подхода. Порядок proposal → specs → design → tasks показывает, что можно сделать дальше, а не к чему вы обязаны перейти.

Во время реализации выяснилось, что проектное решение неверно? Измените design.md и продолжайте. Поняли, что область работ нужно сократить? Обновите предложение. Ничто не заблокировано. Зависимости нужны лишь для того, чтобы у ИИ был необходимый контекст (нельзя составить хорошие задачи без спецификаций, на которых они основаны), а не для того, чтобы ограничивать вас.

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

Почему небольшие дополнительные усилия оправданы

Скажем прямо: OpenSpec добавляет один шаг. Перед разработкой вы пишете краткий план. Что это даёт?

• Вы замечаете неверный путь до того, как он обойдётся дорого. Исправить недопонимание в предложении из одного абзаца ничего не стоит. Исправлять его после того, как ИИ написал 400 строк, — совсем другое дело.
• План и код хранятся в одном репозитории. Через полгода спецификация объяснит вам (и следующему сеансу ИИ), почему система работает именно так.
• Изменения легко проверять. Папка изменения — аккуратный комплект: прочитайте предложение, просмотрите дельты, проверьте задачи. Не нужно археологических раскопок в истории чата.
• Подходит для существующих кодовых баз. Благодаря дельтам можно описать изменение приложения на 50 000 строк, не документируя предварительно весь проект.

И честный компромисс: для действительно тривиального исправления в одну строку эти формальности могут быть не оправданы — это нормально. OpenSpec задуман как лёгкий инструмент, но его использование не бесплатно. Применяйте его там, где важно согласование. При работе с ИИ, который уверенно создаст что угодно по расплывчатому запросу, это нужно чаще, чем кажется.

Что дальше

• Вы здесь впервые? В разделе Начало работы подробно разобрано первое изменение.
• Ещё не решили, что создавать? Начните с раздела Сначала исследуйте.
• Не знаете, где выполняются команды? См. Как работают команды.
• Хотите подробнее узнать обо всём выше? См. Основные понятия.
• Хотите учиться на примерах? См. Примеры и рецепты.
• Нужно определить термин? См. Глоссарий.