SDD и OpenSpec: от требований до проверенного изменения

Рекомендуемый вход — после coding agents из модуля 4. Номер 17 сохраняет адреса существующих уроков; ждать окончания курса не нужно. Первые десять разделов — теория с разобранными примерами, затем справочник команд и самостоятельный проект. К разделу про AI-качество полезно вернуться после evals. Чтение с разборами занимает около 6–7 часов, лабораторная — ещё 6–7.

1. Зачем нужен Spec-Driven Development

SDD — способ вести разработку от явно описанного и проверяемого поведения системы. Спецификация задаёт договорённость; код реализует её; проверки дают доказательства. С AI-агентом это особенно полезно: агент способен быстро написать много правдоподобного кода, но недостающие правила он часто заполняет предположениями. Контекст чата неполон, сокращается и плохо передаётся другому участнику.

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

Пример. Просьба «выдай доступ после подтверждения» не определяет, кто подтверждает, допустимо ли самосогласование, что делать при повторе и когда доступ кончается. Промпт «сделай качественно» не устраняет эти вопросы. Нужны решения владельца процесса и проверяемый контракт.

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

2. От потребности к требованиям

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

AS-IS описывает текущий процесс: сотрудник пишет в чат, руководитель отвечает, администратор выдаёт права вручную. TO-BE — согласованное изменение: заявка и решение фиксируются в сервисе. Из этого не следует, что сервис автоматически меняет реальные ACL: границу интеграции надо договорить отдельно.

Разобранное уточнение брифа

Исходная просьба: «Сделайте согласование доступа к документации». Аналитик спрашивает: кто подаёт и кто решает? Можно ли подать за другого? Что видит другой сотрудник? Может ли согласующий решить свою заявку? После ответа «сотрудник подаёт только за себя, согласующий не согласовывает своё» появляется два самостоятельных правила: принадлежность заявки и запрет самосогласования.

Записывайте решение отдельно от предположения. «Полагаем, что доступ бессрочный» нельзя незаметно превратить в SHALL. У каждого существенного вопроса должен быть владелец и понятное последствие отсутствия ответа. Неизвестное о безопасности блокирует соответствующее решение; выбор имени локальной переменной может остаться исполнителю.

3. Подготовка требований системного анализа

От пользовательского намерения переходите к системному поведению. Пользовательское требование «согласующий принимает решение» раскладывается на допустимые роли, предусловия, переход состояния, результат, ошибки и повторные действия. Контракт API — наблюдаемая часть системы; внутренний класс контроллера — техническое решение.

Состояние заявки и состояние доступа

Одобренная заявка — исторический факт решения. Истёкшее или отозванное разрешение — состояние права доступа. Если при отзыве поменять approved на rejected, история решения станет ложной. Разделение понятий в глоссарии предотвращает ошибку модели данных ещё до кода.

При двух одновременных противоположных решениях нужно выбрать политику. В лабораторной первым считается атомарно зафиксированное решение, второе получает конфликт. Просто «используем mutex» — описание реализации; «у заявки не бывает двух разных окончательных решений» — контракт.

Минимальный пакет аналитика

Контекст и границы; глоссарий; список вопросов и решений; требования с источниками и приоритетами; модель данных с инвариантами; матрица ролей; таблица состояний; контракты интерфейсов и ошибок; условия приёмки. Не для каждой задачи нужны все диаграммы: выбирайте форму, которая делает неоднозначность видимой.

4. Как писать хорошие требования и сценарии

Хорошее требование достаточно атомарно, понятно участникам, согласовано с остальными правилами и допускает проверку. Полнота означает покрытие существенного поведения в выбранных границах, а не попытку описать весь мир. Отдельно фиксируйте уровень обязательности: SHALL/MUST задают обязательство; SHOULD — рекомендацию с возможными исключениями; MAY — разрешённую возможность. В нормативных примерах OpenSpec этого модуля используем SHALL/MUST.

Требование, сценарий и приёмка

Требование описывает общее правило; сценарий — конкретный случай его применения; критерий приёмки — условие, по которому принимают изменение. Один пример не исчерпывает правило. К успешному сценарию добавьте отрицательные, пограничные и повторные действия.

### Requirement: Decision authorization
The system SHALL allow an approver to decide a pending request
only when the approver is not its owner.

#### Scenario: Self approval is forbidden
- **GIVEN** carol is an approver and owns a pending request
- **WHEN** carol approves that request
- **THEN** the service returns 403
- **AND** the request remains pending and no grant is created

Given фиксирует исходные условия, When — действие, Then — наблюдаемый результат. «Когда всё корректно, тогда всё работает» не проверяет ничего. Для срока 1–24 часа нужны минимум допустимые границы, 0, 25, дробное значение, отсутствие поля и точный момент истечения.

Идентификаторы вроде DEC-01 помогают связать правило с источником и тестом. Они являются соглашением проекта. В OpenSpec заголовок требования также участвует в сопоставлении дельты: не переименовывайте его случайно при изменении формулировки. Шаблон дисциплинирует запись, но не доказывает её смысл.

5. Основная спецификация: зачем нужна мастер-спека

В этом курсе мастер-спека — согласованный набор основных спецификаций системы. В OpenSpec это обычно несколько файлов openspec/specs/<capability>/spec.md. Обязательного единого master.md нет. Основные спеки отвечают на вопрос «какое поведение сейчас принято», а история change-пакетов объясняет, как и почему оно появилось.

openspec/
  specs/
    access-requests/spec.md   # создание и чтение заявок
    access-decisions/spec.md  # принятие решений и права
    access-grants/spec.md     # действующий доступ
  changes/
    temporary-access/         # предлагаемое изменение
      proposal.md
      specs/access-grants/spec.md
      design.md
      tasks.md

Capability — устойчивая возможность системы. Название access-grants переживёт несколько релизов; add-expiry-this-week описывает работу, поэтому подходит change, а не основной capability. Не дробите каждый метод в отдельный документ и не складывайте всё в безразмерный system: границу удобно ревьюить и поддерживать одним владельцем поведения.

Что хранить в основной спеке

Назначение возможности, обязательное наблюдаемое поведение, ошибки, ограничения, проверяемые сценарии. Бизнес-контекст можно вынести в аналитический документ со ссылкой; способ хранения времени — в design; причины выбора механизма — в ADR; последовательность реализации — в tasks. Изменение библиотеки без изменения поведения обычно не требует новой поведенческой дельты.

Пример. В baseline правило разрешает бессрочный доступ. План «ввести срок» пока живёт в change. До приёмки этой работы основные спеки не должны одновременно утверждать несовместимые политики. После согласованной синхронизации в них остаётся новый целостный контракт, включая исключение для ранее выданных разрешений.

6. Дельта-спеки: как менять контракт

Дельта-спецификация описывает изменение относительно основной спецификации выбранной базовой версии. Она позволяет ревьюеру видеть, что добавляется и что перестаёт быть истинным. Это семантическое изменение требований, которое затем надо согласовать с API, данными, тестами и миграциями.

Разобранный пример: добавляем срок

Было: «После одобрения доступ действует бессрочно». Решено: новым заявкам нужен срок 1–24 часа от одобрения; старые разрешения сохраняются. Изменения касаются создания заявки и проверки доступа. Одной фразы «добавить expires_at» недостаточно: не определены границы, повтор одобрения и совместимость.

## MODIFIED Requirements

### Requirement: Grant validity
The system SHALL grant access for newly approved requests until
approved_at + requested_hours. It SHALL keep legacy indefinite grants
valid unless revoked. Replaying approval SHALL NOT reset expiry.

#### Scenario: Exact expiration boundary
- **GIVEN** a new grant expires at 2026-11-05T12:00:00Z
- **WHEN** access is checked at 2026-11-05T12:00:00Z
- **THEN** that grant does not permit access

#### Scenario: Existing indefinite grant
- **GIVEN** a grant was issued under the indefinite policy
- **WHEN** the temporary-access policy is enabled
- **THEN** that grant remains valid

#### Scenario: Approval replay
- **GIVEN** a request was approved at 10:00Z for one hour
- **WHEN** the same approval is repeated at 10:30Z
- **THEN** its grant still expires at 11:00Z

Этот фрагмент показывает структуру; в настоящей дельте скопируйте весь изменяемый блок из своей базовой спеки и сохраните остальные сценарии, например проверку владельца и ресурса. MODIFIED заменяет требование целиком. Если оставить только сценарий истечения, при синхронизации можно потерять старые гарантии. Сохранение гарантии не означает буквальное копирование устаревших входов: после введения обязательного срока успешный сценарий создания должен передавать hours=1, а отдельный сценарий — проверять отказ без hours. Strict validator версии 1.16.0 выявляет пропущенные имена прежних сценариев, но не доказывает сохранность их смысла: ослабленный текст с прежним заголовком всё равно требует ревью.

## RENAMED Requirements
- FROM: `### Requirement: Check access`
- TO: `### Requirement: Grant validity`

## REMOVED Requirements
### Requirement: Indefinite access for new requests
**Reason**: New requests use bounded access duration.
**Migration**: Require 1–24 hours for new requests;
retain already issued indefinite grants.

Удалять можно только существующее требование с таким именем. Второй фрагмент — иллюстрация отдельных операций; его нельзя слепо добавить к любому baseline. В раздаточных материалах есть отдельное упражнение с подходящей базой. Если меняется и имя, и содержание, явно согласуйте RENAMED и MODIFIED с форматом закреплённой версии.

Параллельные изменения

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

7. Артефакты OpenSpec и работа с агентом

OpenSpec организует change как папку с контекстом изменения. Разделение файлов нужно для разных решений: зачем, какое поведение, каким способом, какими шагами. Если все четыре документа повторяют один и тот же текст, они создают четыре источника рассинхронизации.

В схеме spec-driven proposal даёт контекст для specs и design; tasks опираются на specs и design. Это граф зависимостей артефактов. Он помогает определить следующий доступный документ и не означает запрет пересмотреть ранее принятое решение.

Запрос агенту при подготовке изменения:
Прочитай основные спеки access-requests и access-grants целиком.
Найди требования, затронутые временным доступом.
Отдельно перечисли неизвестные бизнес-правила и риски совместимости.
Подготовь proposal и дельты; код пока не изменяй.
Для MODIFIED сохрани все сценарии, которые остаются действительными.

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

8. Жизненный цикл: от исследования до архива

1. Исследовать. Прочитать текущие спеки, код и тесты, собрать вопросы.
2. Согласовать изменение. Определить scope, подготовить proposal, дельты, design и задачи; провести ревью.
3. Реализовать. Делать небольшие изменения с проверками. Если выяснилось новое ограничение, вернуться к документам и согласовать его последствия.
4. Проверить. Формат документов, наблюдаемое поведение и смысл требований проверяются разными средствами.
5. Синхронизировать. Внести принятые дельты в основные спецификации и проверить целостность результата.
6. Архивировать. Сохранить change с историей решений. Git merge и развёртывание выполняются отдельно.

Как начать в существующем проекте

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

Пример: код позволяет одобрять собственную заявку, но владелец процесса считает это недопустимым. Нельзя написать «система SHALL разрешать самосогласование», потому что так удобнее пройти проверку baseline. Зафиксируйте дефект и отдельное исправление с регрессионным сценарием. Если же клиенты зависят от странного поведения, потребуется решение о совместимости и миграции.

Что означает завершение. Реализация проверена, изменения требований согласованы, доказательства доступны, основные спеки соответствуют принятому результату, change архивирован. Возможность технически архивировать незавершённую работу не делает её принятой. В учебном процессе не пропускаем приёмку и синхронизацию.

Рабочие команды агента могут анализировать код и предлагать изменения, но выводы агента требуют проверки. Терминальный CLI детерминированно создаёт структуру и проверяет формат. Не приписывайте CLI способность доказать бизнес-корректность программы.

9. Прослеживаемость, приёмка и ответственность

Трассировка связывает исходную потребность, правило, сценарий, проверку и результат. Она нужна, чтобы при изменении требования понять, что ещё проверить, а при провале теста — какое обещание нарушено. Для маленького проекта достаточно таблицы в Markdown.

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

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

10. Как специфицировать AI-системы

В AI-продукте есть две разные природы требований. Проверка прав, предел бюджета и подтверждение операции относятся к детерминированной обвязке. Полезность ответа и полнота цитирования зависят от модели и входа; для них нужны измеримые цели и процедура оценки. Формулировка «ассистент всегда отвечает правильно» непригодна для честной приёмки.

Разобранная дельта для RAG

Было: «Возвращать ответ по найденным документам». Новое намерение: уменьшить неподтверждённые ответы. Перед дельтой надо определить, какой сигнал достаточности использует система, как выглядит отказ и как оценивается качество. Самооценка уверенности модели не является гарантией.

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

Для воспроизводимости укажите набор и его версию, состав критичных срезов, модель/промпт, параметры, правила оценки и допустимую регрессию. Смена judge или корпуса тоже может изменить результат: это изменение процедуры приёмки, требующее ревью. Подробности — в модуле 8, контроль доступа и действий — в модуле 7, итоговая защита — в капстоуне.

Шпаргалка OpenSpec: команды и порядок

Справочник относится к OpenSpec 1.16.0. В чате агента используйте интеграционную форму имени, созданную init. Например, в Codex: $openspec-propose, $openspec-new-change, $openspec-continue-change, $openspec-apply-change, $openspec-verify-change, $openspec-sync-specs, $openspec-archive-change. Ниже — канонические имена /opsx:…; форма зависит от инструмента. CLI-команды openspec … выполняются в терминале и решают другие задачи. Перед обновлением версии сверяйте --help и документацию.

Основной путь:
[explore] → propose → ревью → apply → тесты → приёмка → sync → archive

Пошаговый путь лабораторной:
[explore] → new → continue → ревью → continue → …
          → apply → тесты → verify → приёмка → sync → archive

Уточнение: update → ревью → повтор затронутых проверок
[ ] = необязательный шаг; ff заменяет серию continue

В версии 1.16.0 нет отдельного пресета «expanded»: пошаговые действия включаются через custom с явным списком workflows (точные локальные команды — в README лабораторной). В текущем core доступны explore, propose, apply, update, sync, archive; для new/continue/ff/verify выбираются дополнительные workflows. Для обучения полезнее пошаговое создание с ревью: видна связь документов. OpenSpec не требует навсегда «закрывать» предыдущую фазу: уточняйте документы, когда узнали новое.

В лабораторной CLI устанавливается локально с закреплённой версией; перед командами используется путь локального бинарника, указанный в README. В README настройка профиля изолируется через отдельные XDG_CONFIG_HOME и XDG_DATA_HOME: это позволяет выбрать дополнительные workflows без изменения настроек других проектов. Команды не требуют глобальной установки пакета.

Практика: Access Requests

Небольшой сервис хранит заявки на доступ к документации. В нём нет модели: SDD применяется к процессу разработки, а проверяемое поведение остаётся детерминированным. Это позволяет сосредоточиться на качестве требований и изменениях. Затем тот же процесс переносится на RAG.

Материалы в репозитории: examples/m17-sdd; Java-код — examples/java/m17-sdd. В локальном checkout откройте README первого каталога: бриф, задания, исходные спеки, эталон и команды запуска.

Самопроверка

Вопросы с собеседований

Источники

Проверенная учебная версия инструмента: OpenSpec 1.16.0. Документация ветки main меняется; команды лабораторной сверяются с закреплённым пакетом и его справкой. Аналитический шаблон и правила Access Requests — учебные решения, а не требования самого OpenSpec.

• OpenSpec: официальный репозиторий
• Concepts: основные спеки, изменения и дельты
• Workflows: итерации, синхронизация и архив
• Commands: действия AI-агента
• CLI: терминальные команды
• Схема spec-driven и формат артефактов
• Gherkin: язык сценариев
• RFC 2119: уровень обязательности требований
• RFC 8174: регистр нормативных ключевых слов