Использование OpenSpec в существующем проекте

Не нужно документировать всю кодовую базу с самого начала. Пишите спецификации только для того, что собираетесь изменить. Это главное, что нужно знать об использовании OpenSpec в существующем проекте, и поэтому OpenSpec изначально создавался для уже работающих систем.

Часто возникает такой вопрос: «Моему приложению уже 80 000 строк. Нужно ли описать его целиком, прежде чем OpenSpec станет полезен?» Нет. Вам бы это не понравилось, как и нам. Спецификации OpenSpec пополняются по одному изменению за раз. Первое изменение документирует затронутую им часть, следующее — свою, и за несколько месяцев спецификации естественным образом охватят ту работу, которую вы действительно выполняете.

В этом руководстве показано, как начать в первый же день, не пытаясь объять необъятное.

Краткая версия

$ cd your-existing-project
$ openspec init          # добавляет openspec/ и команды для вашего ИИ-инструмента

Затем в чате с ИИ:

/opsx:explore            # необязательно: попросите ИИ изучить затрагиваемую область
/opsx:propose <небольшое реальное изменение, которое вам действительно нужно>
/opsx:apply
/opsx:archive

Теперь спецификации описывают только ту часть системы, которой коснулось изменение. Так и должно быть. Остальные 80 000 строк можно не трогать.

В чём секрет подхода с дельтами

Изменения OpenSpec описываются с помощью дельт: ADDED, MODIFIED, REMOVED. Дельта описывает, что меняется относительно текущего поведения, а не всю систему целиком.

Именно этого требует работа с существующими системами. Редко когда разработка начинается с нуля: обычно нужно добавить поле, исправить перенаправление или сократить время ожидания. Дельта позволяет точно описать одно изменение, не составляя предварительно 40-страничную спецификацию всего остального.

Поэтому каталог openspec/specs/ изначально почти пуст, а не полностью заполнен. Он постепенно пополняется: каждое архивированное изменение вносит в него свою дельту. Спецификация auth/ станет подробной после нескольких изменений авторизации — то есть именно тогда, когда это будет полезно.

Подробнее о механике см. раздел Основные понятия: дельта-спецификации.

Первое изменение в реальной кодовой базе

Выберите что-то небольшое и реальное. Не учебный пример и не переписывание системы, а изменение, которое вы и так собирались внести на этой неделе. Небольшое первое изменение поможет освоить рабочий процесс с минимальным риском.

Шаг 1: дайте ИИ изучить нужную область. Именно здесь /opsx:explore особенно полезен при работе с незнакомой или большой кодовой базой. Укажите, какую часть собираетесь менять, и дайте ИИ выяснить, как она устроена, прежде чем что-либо предлагать.

Вы: /opsx:explore

ИИ:  Что вы хотели бы исследовать?

Вы: Нужно добавить ограничение частоты запросов к нашему публичному API,
    но я не уверен, как сейчас запросы проходят через промежуточное ПО.

ИИ:  Прослежу путь запроса... [изучает маршрутизатор, цепочку промежуточного
     ПО и конфигурацию] Запросы поступают в Express, проходят через
     промежуточное ПО авторизации, а затем — в контроллеры. Ограничения
     частоты запросов сейчас нет. Лучше всего добавить промежуточное ПО
     сразу после авторизации. Подготовить план?

Теперь ИИ понимает реальную структуру проекта, поэтому подготовленное им предложение будет соответствовать вашему коду, а не типовой схеме. В большой кодовой базе эта привычка особенно полезна. См. раздел Сначала исследуйте.

Шаг 2: предложите изменение. Предложение и его дельта-спецификация зафиксируют только это изменение.

Вы: /opsx:propose add-api-rate-limiting

Шаг 3: реализуйте и архивируйте изменение с помощью /opsx:apply и /opsx:archive, как и любое другое. После архивации у вас будет полноценная спецификация ограничения частоты запросов — результат изменения, которое вам и так было необходимо.

Нужна экскурсия с объяснениями? Используйте onboard

Если вы хотите пройти весь цикл на собственном коде с пояснениями, используйте расширенную команду /opsx:onboard. Она находит в кодовой базе небольшое безопасное улучшение, а затем помогает предложить, реализовать и архивировать его, объясняя каждый шаг.

Сначала включите расширенные команды:

$ openspec config profile      # выберите расширенные рабочие процессы
$ openspec update              # примените их к этому проекту

Затем в чате:

Вы: /opsx:onboard

Это самый простой способ освоиться на реальном проекте; в результате появится настоящее (небольшое) изменение, которое можно сохранить или отменить. См. Команды: /opsx:onboard.

«У меня уже есть документация с требованиями»

Возможно, у вас есть PRD, SRS, формальная спецификация или даже модели TLA+. Отлично. Не нужно импортировать их целиком, но и отказываться от них не стоит.

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

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

Вы: /opsx:explore
Вы: Вот раздел нашего PRD об оформлении заказов. Теперь я собираюсь
    реализовать требование «оформление заказа без регистрации».
    [вставляет нужное требование]
ИИ: [читает текст, задаёт уточняющие вопросы, а затем помогает определить объём изменения]
Вы: /opsx:propose add-guest-checkout

Организация спецификаций в большой кодовой базе

Спецификации находятся в openspec/specs/ и сгруппированы по областям — логическим частям, соответствующим тому, как ваша команда воспринимает систему. Не нужно заранее продумывать всю классификацию. Создайте папку области, когда она впервые понадобится для изменения.

Распространённые способы разделить области:

• По функциональной области: auth/, payments/, search/
• По компоненту: api/, frontend/, workers/
• По ограниченному контексту: ordering/, fulfillment/, inventory/

Выберите структуру, которая будет понятна новичкам. Позже её можно уточнить. См. Основные понятия: спецификации.

Монорепозитории и работа в нескольких репозиториях

Для монорепозитория проще всего создать один каталог openspec/ в корне репозитория и области, соответствующие пакетам или сервисам. Этого достаточно для большинства команд.

Если работа действительно охватывает несколько репозиториев (или несколько пакетов, которые рассматриваются отдельно), в OpenSpec есть бета-функция хранилищ: планирование ведётся в отдельном репозитории, на который могут ссылаться любые репозитории с кодом. Таким образом, плану не обязательно находиться в папке openspec/ одного из репозиториев. Это бета-функция, поэтому её команды и поведение могут меняться. Чтобы ознакомиться с принципами и попробовать самый простой сценарий, начните с руководства по хранилищам.

Несколько важных предостережений

• Не поддавайтесь желанию задним числом документировать всё. Создание спецификаций для кода, который вы не меняете, кажется полезным, но чаще всего таковым не является. Они устареют, поскольку ничто не заставляет их соответствовать действительности. Пусть спецификации пополняются по мере реальных изменений.
• Делайте первые изменения небольшими. Первые несколько изменений нужны не только для выпуска функций, но и для освоения процесса. Ограниченная область работ ускоряет цикл и позволяет учиться с малыми затратами.
• Добавьте openspec/ в git. Спецификации и архив должны храниться в системе контроля версий рядом с описываемым ими кодом.
• Передайте ИИ контекст. Для большой кодовой базы с устоявшимися соглашениями заполните поле context: в openspec/config.yaml, чтобы каждое предложение учитывало стек и принятые шаблоны. См. раздел Настройка.

Что дальше

• Сначала исследуйте — полезная привычка: разберитесь в коде до его изменения
• Начало работы — полное руководство по первому изменению
• Редактирование и доработка изменений — корректировка изменения по мере работы
• Основные понятия: дельта-спецификации — как дельты упрощают работу с существующей системой
• Настройка — настройка OpenSpec с учётом соглашений проекта