Быстрый старт
Ваше первое изменение, от идеи до архивации, в новом или существующем проекте.
Прежде чем начать, вам понадобится CLI на вашей машине (Установка) и инициализированный OpenSpec в вашем проекте (Настройка проекта).
Начните с пустого проекта
Вы можете начать без выбранного стека или полной архитектуры. Инициализируйте OpenSpec в папке вашего проекта, затем попросите вашего агента исследовать варианты вместе с вами. В вашем AI-чате:
Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.Определите, что нужно для первого изменения, и оставьте последующие архитектурные решения открытыми. Попросите вашего агента предложить это одно изменение, затем следуйте шагам ниже. Вы сможете вернуться к архитектуре по мере роста проекта.
Цикл в двух словах
Каждое изменение проходит одни и те же пять шагов: вы обдумываете идею вместе с агентом, он составляет план, вы исправляете план до появления кода, агент реализует его, а архивация обновляет ваши спецификации тем, что было выпущено.
flowchart LR
explore["1 · Исследование<br/>обдумайте вместе"] --> propose["2 · Предложение<br/>агент составляет план"]
propose --> review["3 · Проверка<br/>вы исправляете план"]
review --> apply["4 · Применение<br/>агент реализует задачу за задачей"]
apply --> archive["5 · Архивация<br/>спецификации впитывают изменение"]
archive -. "следующее изменение" .-> explore
Каждый запрос ниже вводится в ваш AI-чат — то же место, где вы запрашиваете код. Примеры используют простой язык, поэтому работают в разных инструментах. Вы также можете вызвать навык напрямую; синтаксис зависит от инструмента (поддерживаемые инструменты).
Шаг 1: Исследование
Обдумайте идею вместе с вашим агентом, прежде чем запрашивать план. В вашем AI-чате:
Help me explore how rate limiting should work in this app.Исследование — это режим размышления. Агент изучает вашу кодовую базу, задаёт важные вопросы, набрасывает варианты и оспаривает допущения. Он никогда не пишет код. Он ничего не записывает, если вы не попросите зафиксировать принятое решение или не согласитесь, когда он предлагает. Результат — более чёткая идея.
Оставайтесь здесь столько, сколько требуется задаче. Когда форма покажется правильной, передайте её:
Propose the change we just discussed.Эта строка запускает предложение для вас, перенося всё, что вы определили. Пропустите первый запрос в шаге 2.
Шаг 2: Предложение
Предложение превращает идею в проверяемый план. Приходя из исследования, он уже запущен. Начиная с нуля, когда изменение ясно в голове, спросите напрямую. В вашем AI-чате:
Propose a change to add rate limiting.Агент задаёт необходимые вопросы, затем создаёт папку изменения:
openspec/changes/add-rate-limiting/
├── proposal.md зачем и что меняется
├── specs/ что значит «готово», в виде проверяемых требований
├── design.md технические решения (только если изменению нужен)
└── tasks.md чек-лист реализацииКода пока нет. Предложение останавливается на плане.
Шаг 3: Проверка и исправление плана
Исправьте план, пока это ещё только слова и ничего не построено. Читайте в следующем порядке:
proposal.md: это правильная задача правильного размера?specs/: самое ценное для чтения. Примете ли вы эти требования как выполненные?tasks.md: охватывают ли задачи спецификации, и ничего лишнего?
Чтобы что-то исправить, подойдёт любой способ:
- Отредактируйте файл самостоятельно. Артефакты — это обычный markdown, и файлы — это и есть план.
- Скажите вашему агенту, что не так («в спецификации отсутствует неаутентифицированный случай»). Он пересмотрит артефакты.
Шаг 4: Применение
Применение превращает план в код. Начните новую сессию чата, так как реализация проходит лучше с чистым контекстным окном. В вашем AI-чате:
Apply the add-rate-limiting change.Агент читает папку изменения, затем проходит по tasks.md, отмечая каждую задачу по мере выполнения.
- Прервано или закончился контекст? Откройте новую сессию и попросите применить снова. Он продолжит с первой неотмеченной задачи.
- План оказался неверным? Исправьте артефакты (любым способом из шага 3), затем продолжите применение.
- Прогресс хранится в флажках
tasks.md. Скрытого состояния нет.
Шаг 5: Архивация
Архивация делает две вещи: обновляет ваши основные спецификации требованиями изменения и перемещает папку изменения в папку архива (в /openspec/changes/archive/*).
Когда каждая галочка в tasks.md отмечена, в вашем AI-чате:
Archive the add-rate-limiting change.Рассмотрим, что делает архивация:
## Завершённое изменение
> Реализация завершена. Дельта-спецификация (что добавляет это изменение) всё ещё находится в папке изменения; specs/ ещё не знает об ограничении запросов.
openspec/
├── specs/ (спецификации ограничения запросов пока нет)
└── changes/
└── add-rate-limiting/
├── proposal.md
├── tasks.md каждая галочка отмечена
└── specs/
└── rate-limiting/
└── spec.md дельта: добавленные требования
## Требования попадают в specs/
> Каждое требование в дельте попадает в основную спецификацию: добавленные дополняют, изменённые заменяют свою старую версию. Новая возможность получает новый файл спецификации.
openspec/
├── specs/
+ │ └── rate-limiting/
+ │ └── spec.md получает "Requirement: Rate limiting"
└── changes/
└── add-rate-limiting/
└── specs/
└── rate-limiting/
└── spec.md дельта, источник слияния
## Папка перемещается в archive/
> Вся папка изменения, включая дельту, перемещается в архив с префиксом даты. Ничего не удаляется.
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md
└── changes/
- └── add-rate-limiting/
+ └── archive/
+ └── 2026-08-08-add-rate-limiting/
+ ├── proposal.md
+ ├── tasks.md
+ └── specs/rate-limiting/spec.md
## Спецификации описывают систему в том виде, как она реализована
> changes/ очищена для следующего изменения. specs/ — источник истины о том, что делает система; archive/ — история того, как она стала такой.
openspec/
├── specs/
│ └── rate-limiting/
│ └── spec.md спецификация в том виде, как реализована
└── changes/
└── archive/
└── 2026-08-08-add-rate-limiting/Git — отдельная задача. Зафиксируйте папку изменения вместе с кодом, и больше ничего в вашем рабочем процессе не изменится.
Сохранение или удаление заархивированных изменений
openspec/changes/archive/ хранит предложение, проект, задачи и дельту для каждого завершённого изменения. В описанном выше процессе архивации дельта уже обновила openspec/specs/.
- Сохраните всю папку изменения, если вам нужна самодостаточная запись в текущем checkout.
- Удалите папку
specs/заархивированного изменения, если Git является вашей историей спецификаций. Сначала зафиксируйте архив, затем удалитеopenspec/changes/archive/<change>/specs/. Предложение, проект и задачи останутся в checkout.openspec validate --archivedпродолжит работать, так как проверяет завершённость задач, а не применённые дельты. - Удалите всю папку изменения, только если вам больше не нужны её предложение, проект или история задач в checkout. Текущие спецификации не изменятся, но
openspec validate --archivedи поиск по checkout больше не будут включать это изменение.
WARNING
Сохраните коммит архива в истории вашего репозитория, если хотите, чтобы Git сохранил удалённые файлы. Объединение коммитов архива и очистки удаляет этот промежуточный снимок.
OpenSpec не удаляет заархивированные изменения автоматически и не предоставляет настройку хранения.
Дальнейшие шаги
- Дельта-спецификации: как писать изменения поведения в дельта-спецификации.
- Профили: необязательные рабочие процессы помимо основного набора (проверка перед архивацией, инкрементное планирование).
Продвинутые руководства
Ещё не написано; руководства, которые мы планируем добавить:
- Сначала прототип: создайте код-развязку до любой спецификации, затем заполните предложение на основе того, чему научил прототип.
- Итеративная разработка: последовательность небольших изменений вместо одного большого предложения.
- Пересмотр реализованного изменения: план нужно сдвинуть снова после применения, но изменение ещё не слито или не заархивировано.