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

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

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

Этот гайд покажет, как начать с первого дня, не пытаясь охватить всё сразу.

Версия за тридцать секунд

$ cd your-existing-project
$ openspec init          # adds openspec/ and your AI tool's commands

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

/opsx:explore            # optional: have the AI read the area you'll touch
/opsx:propose <a real, small change you actually need>
/opsx:apply
/opsx:archive

Ваши спецификации теперь описывают именно ту часть системы, которую затронуло изменение, и ничто больше. Это правильно. Вы перестали беспокоиться о других 80 000 строках.

Почему "delta-first" — это весь секрет

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

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

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

Если вам нужны более глубокие механизмы, см. Concepts: Delta Specs.

Ваше первое изменение на реальной кодовой базе

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

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

You: /opsx:explore

AI:  What would you like to explore?

You: I need to add rate limiting to our public API, but I'm not sure
     how requests currently flow through the middleware.

AI:  Let me trace it... [reads the router, middleware stack, and config]
     Requests hit Express, pass through auth middleware, then your
     controllers. There's no rate-limiting layer today. The cleanest
     insertion point is a middleware right after auth. Want me to scope it?

Обратите внимание: теперь ИИ понимает вашу реальную структуру, поэтому предложение, которое он напишет, будет соответствовать вашему коду, а не какому-то общему шаблону. На большой кодовой базе эта одна привычка сэкономит больше всего боли. См. Explore First.

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

You: /opsx:propose add-api-rate-limiting

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

Хотите управляемый тур? Используйте onboard

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

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

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Затем в чате:

/opsx:onboard

Это максимально мягкое введение на реальном проекте, и оно оставляет вам подлинное (маленькое) изменение, которое вы можете сохранить или отбросить. См. Commands: /opsx:onboard.

«Но у меня уже есть требования»

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

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

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

You: /opsx:explore
You: Вот раздел нашего PRD о чекауте. Я реализую требование «гостевой чекаут».
     [paste the relevant requirement]
AI:  [reads it, asks clarifying questions, then helps scope a change]
You: /opsx:propose add-guest-checkout

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

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

Общие способы разбивки на домены:

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

Выберите то, что заставит новичка кивнуть. Вы можете уточнить позже. См. Concepts: Specs.

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

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

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

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

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

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

• Explore First — ключевая привычка для понимания кода до того, как вы его измените
• Getting Started — полное пошаговое руководство по первому изменению
• Editing & Iterating on a Change — корректировка изменения по мере обучения
• Concepts: Delta Specs — почему дельты делают работу в условиях "brownfield" чистой
• Customization — научите OpenSpec конвенциям вашего проекта