diff --git a/README.md b/README.md index f2eed6a..18425da 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ | Артефакт | Назначение | Где находится | |---|---|---| | Схема OpenSpec `use-case-driven` | Русскоязычные спецификации поведения и workflow `proposal → specs / design → tasks → apply` | [`openspec/schemas/use-case-driven/`](openspec/schemas/use-case-driven/) | -| Заготовки `AGENTS.md` и `config.yaml` с контекстом проекта | Правила агента, параметры проекта и начальная навигация по постоянным документам | [`examples/project-bootstrap/`](examples/project-bootstrap/) | +| Заготовки `AGENTS.md` и `config.yaml` с контекстом проекта | Правила OpenSpec и Git для агента, параметры проекта и навигация по постоянным документам | [`examples/project-bootstrap/`](examples/project-bootstrap/) | | Скилл Codex `task-tracker` | Одна задача на change: привязка, метка приложения, синхронизация, учёт времени, archive и коммит | [`skills/task-tracker/SKILL.md`](skills/task-tracker/SKILL.md) | Схема и скилл хранятся и развиваются здесь. Подключайте их символическими @@ -33,13 +33,17 @@ Master specs описывают `Purpose`, границы capability и треб [`examples/project-bootstrap/`](examples/project-bootstrap/): - [`AGENTS.md`](examples/project-bootstrap/AGENTS.md) — навигация по контексту, - правила OpenSpec и вызовы `task-tracker` в жизненном цикле change; + правила OpenSpec, Git-процесс и вызовы `task-tracker` в жизненном цикле change; - [`openspec/config.yaml`](examples/project-bootstrap/openspec/config.yaml) — выбор схемы и начальный контекст OpenSpec; - `openspec/context/` — индекс контекста, правила ADR и шаблон решения. Объедините заготовки с существующими файлами, сохраняя применимые инструкции -и настройки проекта. Заполните в проектном `AGENTS.md`: +и настройки проекта. В шаблоне `AGENTS.md` задан двухэтапный Git-процесс: +первый PR содержит только планирование OpenSpec, второй — реализацию после +слияния первого PR и явной команды владельца. Для существующего проекта +объедините эти правила с его настройками целевой ветки и ревью. Заполните +в проектном `AGENTS.md`: ```markdown ## Task Management @@ -59,7 +63,8 @@ Lifecycle: - При существенном изменении change синхронизируй существующую задачу. - После каждого рабочего сеанса Apply синхронизируй фактическое время. - Перед archive выполни финальную синхронизацию; после успешной архивации - закрой задачу и закоммить изменения change с русским описанием в 4–7 слов. + закрой задачу и закоммить изменения change. Начинай сообщение коммита с ключа + связанной задачи, затем кратко опиши изменения по-русски: `CON-27 Правка тестов`. При ошибке archive задачу не закрывай. - При повторном запросе возобнови незавершённую синхронизацию по существующей связи, включая архивные changes. @@ -112,7 +117,8 @@ openspec/changes/archive//task-tracker.yaml Archive переносит весь каталог, включая файл связи. После успешного переноса закройте YouTrack-задачу и зафиксируйте относящиеся к change изменения -Git-коммитом с русским сообщением из 4–7 слов. Исходный `change_id`, +Git-коммитом с сообщением в формате «ключ связанной задачи + краткое описание +изменений по-русски», например `CON-27 Правка тестов`. Исходный `change_id`, непрозрачный `task_id`, URL и снимок проектных параметров остаются в файле. Не пытайтесь восстанавливать ID только из архивного имени: change сам может начинаться с даты. Сохраняйте файл в Git вместе с change и архивом. diff --git a/examples/project-bootstrap/AGENTS.md b/examples/project-bootstrap/AGENTS.md index 41daa3e..9aa0d26 100644 --- a/examples/project-bootstrap/AGENTS.md +++ b/examples/project-bootstrap/AGENTS.md @@ -21,6 +21,33 @@ - Не принимай Proposed ADR самостоятельно. При конфликте запроса с принятым ADR явно сообщи о нём и запроси решение владельца. +## Git-процесс OpenSpec Change + +- Для каждой задачи используй одну feature-ветку от целевой ветки репозитория: + `feature/-`. Код бери из связанной задачи, имя — + короткий ASCII slug в нижнем регистре с дефисами. Не переименовывай уже + используемую ветку вслед за переименованием задачи. +- Используй эту ветку для двух последовательных PR в одну целевую ветку. + Обычный push разрешён только в feature-ветку; прямой push в целевую ветку, + force push и изменение чужих веток запрещены. +- Первый PR содержит только артефакты планирования OpenSpec: proposal, delta + specs либо отметку `skip_specs: true`, design, tasks и связанные метаданные. + Не начинай и не публикуй реализацию до ручного слияния первого PR и + отдельной команды владельца. +- После открытия первого PR остановись. Владелец отдельно ревьюит и вручную + сливает его, сохраняя feature-ветку. Одобрение или слияние сами по себе + не разрешают продолжать: дождись явной команды владельца в этом чате. +- После команды проверь в Git, что первый PR действительно слит в целевую + ветку. Если он ещё не слит, сообщи об этом и жди. После подтверждения + обнови ту же feature-ветку из целевой и продолжай реализацию в ней. +- Второй PR содержит реализацию, применимые проверки, документацию и + обновлённые задачи OpenSpec; добавь ссылку на задачу и первый PR. Для него + требуется отдельное актуальное ревью и успешные обязательные проверки. + Оба PR вручную сливает владелец. +- После запроса правок продолжай только по явной команде владельца. Закрытый + без слияния PR останавливает процесс до отдельного решения владельца. + Автоматическое слияние и продолжение по событиям Git не используются. + ## Task Management Для всех OpenSpec Changes используй скилл `task-tracker`. @@ -39,8 +66,9 @@ Lifecycle: - При существенном изменении change синхронизируй существующую задачу. - После каждого рабочего сеанса Apply синхронизируй фактическое время. - Перед archive выполни финальную синхронизацию; после успешной архивации - закрой связанную задачу и создай коммит с изменениями change и русским - описанием в 4–7 слов. При ошибке archive задачу не закрывай и коммит не создавай. + закрой связанную задачу и создай коммит с изменениями change. Начинай сообщение + коммита с ключа связанной задачи, затем кратко опиши изменения по-русски: + `CON-27 Правка тестов`. При ошибке archive задачу не закрывай и коммит не создавай. - При повторном запросе или незавершённой синхронизации возобнови работу с существующей связью, включая архивные changes. diff --git a/examples/project-bootstrap/README.md b/examples/project-bootstrap/README.md index 2f33400..33192d3 100644 --- a/examples/project-bootstrap/README.md +++ b/examples/project-bootstrap/README.md @@ -8,7 +8,8 @@ OpenSpec `use-case-driven`. Схема не устанавливает их ав В комплект входят: -- `AGENTS.md` — навигация по контексту, правила OpenSpec и вызовы `task-tracker`; +- `AGENTS.md` — навигация по контексту, правила OpenSpec и Git-процесс + с двумя PR, вызовы `task-tracker`; - `openspec/config.yaml` — выбор схемы и начальный контекст OpenSpec; - `openspec/context/index.md` — карта постоянных документов проекта; - `openspec/context/adr/README.md` — правила ведения ADR; @@ -19,6 +20,12 @@ OpenSpec `use-case-driven`. Схема не устанавливает их ав требования из `openspec/specs/`. Перед архитектурными изменениями читайте применимые принятые ADR. +Git-процесс из `AGENTS.md` использует одну feature-ветку для двух PR: +сначала PR с планированием OpenSpec, затем после ручного слияния и явной +команды владельца — PR с реализацией. При переносе шаблона в существующий +проект объедините этот раздел с проектными правилами ветвления и защиты +целевой ветки. + `ADR-template.md` соответствует `openspec/schemas/use-case-driven/templates/adr.md` в этом репозитории. При изменении исходного шаблона обновляйте его копию здесь. @@ -43,7 +50,8 @@ Task tracker configuration: [инструкции корневого README](../../README.md#подключение-из-домашней-директории). Создание или привязка, содержательные обновления, учёт времени, закрытие задачи и коммит после успешного archive выполняются по Lifecycle из `AGENTS.md`. -Сообщение коммита должно быть на русском языке и состоять из 4–7 слов. Эти правила не нужно +Сообщение коммита начинайте с ключа связанной задачи, затем кратко описывайте +изменения по-русски: `CON-27 Правка тестов`. Эти правила не нужно добавлять в схему или `config.yaml`. Запуск OpenSpec CLI вне Codex не вызывает скилл; для завершения внешней синхронизации обратитесь к агенту. diff --git a/openspec/schemas/use-case-driven/README.md b/openspec/schemas/use-case-driven/README.md index 5f22a0b..4c1c9df 100644 --- a/openspec/schemas/use-case-driven/README.md +++ b/openspec/schemas/use-case-driven/README.md @@ -5,12 +5,20 @@ формат требований определён в `schema.yaml` и шаблонах. Существующие changes с явно указанной `schema: spec-driven` продолжают использовать свою схему. +## Git-процесс проекта + +Схема задаёт порядок и формат OpenSpec-артефактов. Правила веток, двух +последовательных PR, ручного слияния и явной команды продолжения находятся +в [шаблоне проектных инструкций](../../../examples/project-bootstrap/AGENTS.md). +При подключении схемы включите правила из этого шаблона в проектный +`AGENTS.md` и согласуйте имя целевой ветки с настройками репозитория. + ## Уровни спецификации - Capability — отдельная бизнес-функция или понятный результат в иерархии доменов. - Границы master-спецификации фиксируют ответственность capability: что входит в её область, что исключено и кому принадлежат соседние обязанности. - Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario. -- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы. +- Scenario — один из двух форматов Use case: полный или сокращённый. Формат определяется сложностью сценария, независимо от того, описываются ли БД, API, логика, UI или другая часть системы. - FR — подробные правила и контракты сообщений за пределами Scenario; контракт HTTP endpoint размещается в завершающем CONTRACT. @@ -68,8 +76,11 @@ Markdown-рендерер автоматически создаёт якоря ## Форматы Use case -Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания. -Для каждого HTTP endpoint используй отдельный Requirement и полный Use case. +- Полный Use case используй для крупных многошаговых сценариев с большим количеством последовательных действий. +- Сокращённый Use case используй для простых коротких требований. Рассматривай их как кандидаты на выделение в отдельные Requirements для переиспользования в сценариях других Requirements. +- Выбирай формат по сложности: не используй полный Use case для простых требований, а сокращённый — для объёмных многошаговых сценариев. Правило действует и для HTTP endpoint. + +Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращённый Use case содержит только Основной поток; каждый шаг ссылается на FR. ```text #### Scenario: Сокращенный use case: описание функции @@ -106,8 +117,8 @@ FR задаёт тексты, дальнейшие действия и связ ## HTTP-контракт в Requirement -Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный -Use case; сложные правила шагов выносятся в FR. После всех FR, в конце +Каждый endpoint оформляется отдельным Requirement. Формат Use case выбирается +по сложности сценария; сложные правила шагов выносятся в FR. После всех FR, в конце Requirement, размещается раздел CONTRACT с подразделами Request и Response. В Request указываются один HTTP-метод и путь, тело и query-параметры. В Response указываются HTTP status и таблица сериализуемого ответа. Не создавай diff --git a/openspec/schemas/use-case-driven/patterns/message-contract.md b/openspec/schemas/use-case-driven/patterns/message-contract.md index edb7a05..3adb75c 100644 --- a/openspec/schemas/use-case-driven/patterns/message-contract.md +++ b/openspec/schemas/use-case-driven/patterns/message-contract.md @@ -7,8 +7,8 @@ CONTRACT. Для асинхронного сообщения или технич ## HTTP endpoint -Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные -правила обработки указываются в FR, а контракт помещается в самом конце +Каждый endpoint описывается отдельным Requirement; формат Use case выбирается +по сложности сценария. Сложные правила обработки указываются в FR, а контракт помещается в самом конце Requirement: ```markdown diff --git a/openspec/schemas/use-case-driven/schema.yaml b/openspec/schemas/use-case-driven/schema.yaml index f56313e..21823b6 100644 --- a/openspec/schemas/use-case-driven/schema.yaml +++ b/openspec/schemas/use-case-driven/schema.yaml @@ -94,8 +94,13 @@ artifacts: пояснения, не влияющие на поведение и не снимающие неоднозначность контракта. Scenario: - - Автор выбирает полный или сокращённый сценарий независимо от типа FR - и части системы (процесс, БД, API, UI и другие), кроме обязательного полного HTTP-сценария. + - Выбирай формат по сложности сценария, независимо от типа FR и части системы + (процесс, БД, API, UI и другие). + - Полный Use case используй для крупных многошаговых сценариев с большим + количеством последовательных действий, а не для простых коротких требований. + - Сокращённый Use case используй для простых коротких требований, а не для + объёмных многошаговых сценариев. Рассматривай такие требования как кандидаты + на выделение в отдельные Requirements для переиспользования в сценариях других Requirements. - Полный сценарий содержит разделы Участники, Предусловия, Основной поток, Альтернативы и ошибки, Результат, Коды завершения — в таком порядке. @@ -105,7 +110,8 @@ artifacts: которых нет в заголовке. Контекст отсутствует. - Основной поток — нумерованные короткие шаги «Что делаем — как делаем». - В шаге выполнения можно указать действие, endpoint API или способ записи со ссылкой на FR. - - Каждую конечную точку HTTP описывай отдельным Requirement с полным сценарием. + - Каждую конечную точку HTTP описывай отдельным Requirement; формат сценария + выбирай по его сложности. Сложные правила шагов выноси в FR со ссылками из сценария. - Основной поток и альтернативы обычного сценария включают коды завершения, если они определены для этой функции. diff --git a/openspec/schemas/use-case-driven/templates/spec.md b/openspec/schemas/use-case-driven/templates/spec.md index 9ffe135..fbbca6b 100644 --- a/openspec/schemas/use-case-driven/templates/spec.md +++ b/openspec/schemas/use-case-driven/templates/spec.md @@ -20,6 +20,12 @@ Система SHALL <наблюдаемый результат завершённой функции>. + + #### Scenario: <название завершённого процесса> ##### Участники @@ -69,7 +75,7 @@ HTTP endpoint располагай в завершающем разделе CONT <При необходимости — параметры сообщений, связанные требования и соответствие действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.> - -