Основные концепции на взгляд

OpenSpec — это легковесный уровень согласования между вами и вашим ИИ. Вы описываете, что должно делать изменение; ИИ черновик детали, вы оба просматриваете один и тот же план, и только потом пишется код. Эта страница представляет собой всю ментальную модель на одном экране. Если вам нужен полный вариант, Concepts содержит его.

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

Пять идей

Всё в OpenSpec построено на пяти концепциях. Изучите их, и остальное — это детали.

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

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

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

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

proposal ──► specs ──► design ──► tasks ──► implement
   why        what       how       steps      do it

Вы можете вернуться к любому из них в любое время. Они являются активаторами, а не барьерами. (Подробнее об этом ниже.)

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

Обзорная картина

┌─────────────────────────────────────────────────────────────────┐
│                          openspec/                              │
│                                                                 │
│   ┌──────────────────┐         ┌──────────────────────────┐    │
│   │     specs/       │         │        changes/          │    │
│   │                  │ ◄─────  │                          │    │
│   │ source of truth  │  merge  │ one folder per change    │    │
│   │ how things work  │  on     │ proposal · design ·      │    │
│   │ today            │ archive │ tasks · delta specs      │    │
│   └──────────────────┘         └──────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

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

Цикл, который вы на самом деле будете выполнять

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

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

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

Это слэш-команды, которые вводятся в чате вашего помощника ИИ. Настройка (openspec init) выполняется в вашем терминале. Если этот раздельный процесс вам незнаком, сначала прочтите How Commands Work; это самая распространенная точка замешательства.

«Активаторы, а не барьеры»

Эта фраза встречается повсюду в OpenSpec, поэтому вот что она означает простыми словами.

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

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

Сила здесь в честности: реальная работа беспорядочна и итеративна, и OpenSpec это позволяет. Компромисс — дисциплина: поскольку ничто не заставляет вас двигаться вперед, вы должны сами поддерживать фокус изменения, а не позволять ему разрастаться. Руководство Workflows содержит хорошие привычки для этого.

Почему это стоит небольшого оверхеда

Простая правда: OpenSpec добавляет шаг. Вы пишете краткий план перед созданием. Так что же вы получаете взамен?

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

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

Куда двигаться дальше

• Новичок? Getting Started подробно описывает первое изменение.
• Не уверены, что строить? Explore First — это место для начала.
• Сбились с толку насчет того, где запускаются команды? How Commands Work.
• Хотите глубокий вариант всего вышеперечисленного? Concepts.
• Учитесь на примерах? Examples & Recipes.
• Нужен термин? Glossary.