OpenSpec в команде

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

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

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

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

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

Обычный рабочий цикл

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

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

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

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

Именно здесь команда чувствует всю пользу подхода. Если в пулл-реквест включена дельта спецификации изменения, рецензент получает то, что никогда не даёт обычный 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/ репозитория с кодом — это правильное значение по умолчанию. Когда ваше планирование действительно охватывает несколько репозиториев или команд — например, одна функция затрагивает три сервиса, или требования, принадлежащие одной команде, используют другие — для этого существует бета-функция stores (хранилища): для планирования выделяется отдельный репозиторий, на который может ссылаться любой репозиторий с кодом. Начните с Руководства пользователя хранилищ.

Дальнейшие шаги

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