OpenSpec в команде

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

Краткий ответ: изменение — это просто файлы, а OpenSpec не взаимодействует с git. Поэтому он встраивается в ваш рабочий процесс, а не заменяет его. На этой странице описаны удачные соглашения.

Главное правило: OpenSpec не взаимодействует с git

OpenSpec читает и записывает обычные Markdown-файлы в openspec/. Он не создаёт коммиты и ветки, не отправляет изменения и не выполняет pull в вашем проекте, а также самостоятельно не клонирует и не синхронизирует хранилища. Это значит, что:

• Добавляйте openspec/ в коммиты, как и любой исходный код. Спецификации, активные изменения и архив входят в историю проекта. (Да, коммитьте всю папку — см. FAQ.)
• Версионируйте папку изменения так же, как код. openspec/changes/add-dark-mode/ — это просто файлы в ветке.
• Всё ниже — соглашения, а не принудительные правила. OpenSpec не заставляет вас поступать именно так, но легко вписывается в такой процесс.

Повседневный цикл

Удобный рабочий процесс связывает изменение с веткой и пул-реквестом:

git switch -c add-dark-mode        создать ветку как обычно
   │
/opsx:propose add-dark-mode        подготовить план (proposal + specs + tasks)
   │
ПРОВЕРЬТЕ ПЛАН                     прочитайте его до написания кода — см. «Проверка изменения»
   │
/opsx:apply                        реализовать; артефакты и код меняются вместе
   │
git commit && open a PR            пул-реквест содержит дельту спецификации И код
   │
коллега проверяет и объединяет изменения
   │
/opsx:archive                      объединить дельту с specs/ и переместить изменение в архив

План и код находятся рядом в одной ветке, поэтому коллеги проверяют их вместе. А через полгода архивная спецификация всё ещё объясняет, почему код устроен именно так.

Проверка спецификаций в пул-реквесте

Именно здесь команда ощущает пользу подхода. Если пул-реквест содержит дельта-спецификацию изменения, проверяющий получает то, чего не даёт обычный diff: понятное описание того, что должно делать изменение, ещё до прочтения первой строки кода.

Рекомендуемый порядок проверки:

1. Прочитайте proposal.md — правильно ли определены проблема и объём работ?
2. Прочитайте дельту в specs/ — верно ли определено, что значит «готово»? (Это двухминутная проверка изменения, проходящая теперь прямо в пул-реквесте.)
3. Затем изучите diff кода — реализует ли он именно эти требования?

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

Когда архивировать

Архивация объединяет дельты изменения с основными спецификациями в openspec/specs/ и перемещает папку изменения в openspec/changes/archive/YYYY-MM-DD-<name>/. Поскольку specs/ — это общий источник истины, для команды важно выбрать подходящее время. Есть два рабочих соглашения:

• Архивируйте после слияния пул-реквеста (рекомендуется). Активное изменение находится в ветке; после её слияния с основной веткой архивируйте изменение там (часто это небольшой дополнительный коммит или запланированная очистка). Так общие specs/ обновляются только для действительно выпущенной функциональности.
• Архивируйте в рамках пул-реквеста. Для небольших команд это проще: тот же пул-реквест, в котором добавляется код, также синхронизирует и архивирует изменение. Недостаток в том, что diff specs/ и diff кода попадают вместе, из-за чего пул-реквест может стать шумнее.

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

Параллельная работа

Поскольку изменения хранятся в отдельных папках, они не конфликтуют:

• Разные люди работают над разными изменениями — проблем нет. add-dark-mode и rate-limit-login — разные папки в разных ветках; они не затрагивают друг друга до архивации.
• Одно изменение — один ответственный. Если два человека редактируют одну папку изменения, возникает конфликт, как если бы они меняли один файл. Назначьте одного автора или разделите работу на два изменения (ещё одна причина выбирать подходящий размер).
• Конфликты возникают в specs/. Если два изменения затрагивают одно и то же требование, при архивации второго возникнет конфликт в openspec/specs/…/spec.md. Разрешите его как любой конфликт слияния, оставив требование, соответствующее действительности. Такое случается редко, и это полезно: git показывает, что два изменения по-разному определяют поведение системы.

Когда планирование выходит за рамки одного репозитория

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

Что дальше

• Проверка изменения — проверка плана прямо в пул-реквесте.
• Написание хороших спецификаций — в том числе выбор подходящего объёма изменения для одной ветки.
• Руководство по хранилищам — планирование, охватывающее несколько репозиториев и команд.