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

Разработка на основе спецификаций (Spec-Driven Development, SDD) работает тогда, когда спецификация является рабочим процессом, а не документом, который архивируют после запуска проекта. Цель — не создать большой документ требований к продукту.

Цель — пройти последовательность проверяемых артефактов, каждый из которых снижает неоднозначность до того, как кто-либо — человек или ИИ-агент — изменит производственный код.

Если вы не понимаете, что такое SDD концептуально, начните со статьи Что такое разработка на основе спецификаций? — там есть определения, сравнение с TDD и BDD, а также аргументы в пользу того, чтобы рассматривать спецификацию как источник истины. Эта статья в кластере документации Архитектура приложений служит операционным руководством. В ней описаны пять фаз, показано, что должен содержать каждый артефакт, объяснено, как вписать ИИ-агентов в процесс, и предоставлены повторяемые шаблоны, которые вы можете скопировать в свой репозиторий уже сегодня.

SDD — это рабочий процесс, а не документ

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

Рабочий процесс SDD создает цепочку артефактов, каждый из которых проходит ревью перед началом следующей фазы. Требования снижают продуктовую неоднозначность. Дизайн снижает техническую неоднозначность. Задачи снижают операционную неоднозначность. Реализация создает код в соответствии с известной целью. Валидация доказывает, что цепочка сохранилась. Если на какой-либо фазе выявляется ошибка, вы исправляете артефакт и перезапускаете процесс с этой точки — а не после того, как три тысячи строк расхождений уже попали в main.

Рабочий процесс не привязан к конкретным инструментам. Вы можете использовать его с markdown-файлами в Git, с GitHub Spec Kit, с легковесным CLI, ориентированным на изменения, как OpenSpec, с планами Cursor, с пакетом навыков с принудительным контролем, как Superpowers, или просто с текстовым редактором и дисциплинированным ревьюером. Важно — последовательность и контрольные точки ревью, а не бренд инструментов.

Фаза 1 — Спецификация требований

Фаза спецификации отвечает на вопросы: какую проблему вы решаете и что означает «готово». Она намеренно избегает вопросов о том, как это строить. В тот момент, когда в вашей спецификации требований появляется фраза «использовать sorted sets в Redis», вы перестали специфицировать и начали дизайн в неправильном документе. Держите реализацию вне требований. Перенесите это в план.

Формулировка проблемы и пользователи

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

Пример для функции ограничения частоты запросов API:

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

Цели, нецели и критерии приемки

Цели описывают результаты, которые вы предоставите. Нецели описывают заманчивые смежные работы, которые вы явно не будете делать. Вместе они ограничивают креативность агента, что至关重要, когда ИИ-инструменты иначе «помогательно» расширяют скоуп.

Критерии приемки должны быть достаточно точными, чтобы каждый из них соответствовал хотя бы одному тесту. «Эндпоинт безопасен» — это не критерий приемки. «Неавторизованные запросы получают HTTP 401» — это критерий. Если вы не можете сформулировать конкретный критерий, требование все еще слишком расплывчато для реализации.

Открытые вопросы

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

Минимальный шаблон требований:

## Problem
[One paragraph: who hurts, why, and what triggers the pain.]

## Users
- [Primary user role]
- [Secondary user role]

## Goals
1. [Measurable outcome]
2. [Measurable outcome]

## Non-goals
- [Explicitly out of scope]
- [Explicitly out of scope]

## Acceptance criteria
- [ ] [Verifiable behavior]
- [ ] [Verifiable behavior]

## Open questions
- [ ] [Question that blocks planning]

Фаза 2 — Планирование дизайна

Фаза плана трансформирует намерения в технические решения. Здесь имеют место быть sorted sets в Redis, границы модулей, изменения схемы, контракты API, шаги миграции, ограничения безопасности и стратегия тестирования. План выводится из спецификации требований и существующих ограничений вашего проекта — выбор стека, записи решений и соглашения, хранящиеся в файлах вроде AGENTS.md или конституции проекта.

Архитектура и затронутые модули

Назовите модули, сервисы или пакеты, которые изменятся, и обобщите паттерн интеграции. Если фича пересекает границу сервиса, документируйте контракт с обеих сторон. Агенты галлюцинируют API, когда контракты неявные. Явное указание их в плане предотвращает изобретенные эндпоинты и неверные формы ответов.

Модель данных, контракты API и миграции

Документируйте изменения схемы, новые таблицы или поля, требования к индексам и правила обратной совместимости. Для HTTP API записывайте метод, путь, форму запроса, форму ответа и коды ошибок. Для событий записывайте названия топиков, схемы payload и семантику доставки. Включайте шаги миграции и заметки по откату при изменении модели данных.

Безопасность, наблюдаемость и стратегия тестирования

Ограничения безопасности должны быть в плане, а не добавлены постфактум на код-ревью. Отметьте требования к аутентификации, правила авторизации, границы валидации входных данных и данные, которые не должны появляться в логах. Наблюдаемость должна покрывать метрики, логи или трейсы, необходимые для подтверждения работы фичи в production.

Стратегия тестирования связана с критериями приемки. Определите, какие критерии требуют unit-тестов, какие — интеграционных, а какие — ручной проверки. Если вы используете юнит-тестирование на Go или юнит-тестирование на Python, назовите пакеты и файлы тестов, которые вы планируете добавить. План без стратегии тестирования — это план, который выйдет в production с пробелами, которые вы обнаружите слишком поздно.

Фаза 3 — Разбивка задач реализации

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

Размер задач и зависимости

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

Файлы, валидация и контрольные точки ревью

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

Минимальная запись задачи:

### Task 3 -- Add rate-limit middleware

**Depends on:** Task 1 (schema), Task 2 (repository)
**Files:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Satisfies:** AC-2 (429 over limit), AC-3 (limit headers in response)
**Validate:** `go test ./middleware/...` passes; curl over limit returns 429 with Retry-After
**Review checkpoint:** Confirm middleware runs after auth, before handler

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

Фаза 4 — Реализация одной задачи за раз

Реализация намеренно узкая. Выберите одну задачу, дайте агенту только тот контекст, который ему нужен для этой задачи, и остановитесь, когда валидация пройдет. Сброс контекста между задачами — это фича, а не баг. Это предотвращает загрязнение предыдущих допущений будущей работой и сохраняет diff проверяемыми.

Применение ограничений из стека спецификаций

Реализующий агент должен читать спецификацию требований, план дизайна, описание текущей задачи и ограничения на уровне проекта. Ограничения — это раздел с самым высоким ROI, который большинство команд пропускают. Они говорят агенту, чего не делать — не рефакторить несвязанные модули, не изменять сигнатуры публичного API за пределами этой фичи, не вводить новые зависимости без обновления плана.

Обновление плана, когда реальность отличается

Реализация выявит сюрпризы. Библиотека не поддерживает предполагаемое поведение. Миграция занимает больше времени, чем ожидалось. Краевой случай отсутствовал в критериях приемки. Когда это происходит, обновите спецификацию перед продолжением. Исправьте требования или план, получите быстрое ревью, затем возобновите реализацию по исправленному артефакту. Код, который тихо расходится со спецификацией, — это путь к постоянному дрейфу.

Фаза 5 — Валидация по спецификации

Валидация — это там, где SDD оправдывает себя. Без этого спецификация — просто упражнение в планировании. С ней спецификация — это контракт, по которому можно проверять выпущенный код.

Автоматические проверки

Запускайте полный набор тестов, линт и проверки типов в CI. Встраивайте эти процессы в ваш пайплайн, используя паттерны из шпаргалки по GitHub Actions, если вам нужна практическая отправная точка. Автоматические проверки ловят регрессии. Они не ловят неверные фичи, правильно реализованные, поэтому ревью критериев приемки по-прежнему важно.

Критерии приемки и ручное ревью

Пройдите по каждому критерию приемки из спецификации требований. Отметьте каждый как выполненный, проваленный или отложенный с обоснованием. Ручное ревью ловит UX-проблемы, пробелы в безопасности и неверное поведение, которое тесты пропустили, потому что тесты были написаны под ошибочную спецификацию.

Diff спецификация-код

Последний шаг валидации сравнивает реализацию с планом дизайна. Соответствовали ли измененные файлы тем, которые предсказал план? Соответствовали ли архитектурные решения в коде записанным решениям? Неожиданные файлы в diff — это сигнал: либо план был неполным, либо агент сбился. Обоим случаям нужно уделить внимание перед мериджем. Держание спецификаций, тестов и кода в синхроне в разработке с ИИ превращает этот одноразовый diff-ревью в повторяемую таблицу трассировки и набор проверок в CI, так что дрейф ловится в каждом PR, а не только когда кто-то вспомнит посмотреть.

Роль ИИ-агентов в рабочем процессе

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

Агенты особенно полезны при создании первых черновиков и boilerplate-тестов. Люди особенно полезны при ловле неверных целей, небезопасной архитектуры и тонкого расширения скоупа. Рабочий процесс проваливается, если пропускается любая сторона — когда агенты реализуют без спецификаций, или когда люди пишут спецификации, никогда не валидируя их по коду.

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

Типовые ошибки, убивающие разработку на основе спецификаций

Огромные спецификации до какой-либо валидации. Тридцатистраничный документ требований, написанный до прототипа или спайка — это бумажная работа водопада, а не SDD. Пишите минимальную спецификацию, которая устраняет неоднозначность для следующей фазы, затем валидируйте допущения рано. Не каждой фиче нужен полный пятифазный цикл — Разработка на основе спецификаций vs Vibe Coding объясняет, когда легкая структура достаточна.

Размытые критерии приемки. Прилагательные вроде «быстрый», «чистый» и «удобный» — это не критерии приемки. Заменяйте их измеряемым поведением. Если вы не можете это протестировать, вы не можете надежно это реализовать — особенно с ИИ-агентом.

Отсутствие нецелей. Без нецелей агенты по умолчанию расширяют скоуп. Они добавляют слои кэширования, рефакторят соседние модули и вводят зависимости, о которых вы не просили. Нецели — это способ сказать «нет» заранее.

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

Пропуск ревью на границах фаз. Спецификация ревьюится перед планом. План ревьюится перед задачами. Задачи ревьюятся перед реализацией. Каждая точка входа дешевая. Исправление дрейфа после большого мерджа дорого.

Давать сгенерированным задачам взорваться. Относитесь к списку из пятидесяти задач, сгенерированному ИИ, как к первому черновику, а не к расписанию. Объединяйте избыточные пункты, делите слишком большие, удаляйте задачи, которые не соответствуют требованию.

Удалять отклоненные исследования вместо записи причин. Когда ревью фазы 2 заключает, что направление не стоит строить, рефлекс — удалить спецификацию и двигаться дальше. Это стирает рассуждения, и та же идея всплывает в следующем квартале, исследованная с нуля тем, кто — человек или агент — снова наткнется на нее. Запись отклонения с той же строгостью, что и принятого решения, дешева по сравнению; Отклоненные предложения в OpenSpec: конвенция памяти решений разбирает один конкретный способ сделать это, включая инструкцию, которая заставляет агента искать предыдущие решения перед повторным предложением.

SDD работает, когда каждая фаза снижает неоднозначность. Он проваливается, когда создает бумажную работу.

Повторяемые шаблоны

Скопируйте эти в свой репозиторий и адаптируйте. Храните спецификации рядом с веткой фичи, ревьюите их в pull requests и держите в контроле версий, чтобы агенты и люди читали один и тот же источник.

Шаблон требований

# Feature -- [name]

## Problem
## Users
## Goals
## Non-goals
## Acceptance criteria
## Open questions

Шаблон дизайна

# Design -- [feature name]

## Summary
## Affected modules
## Data model changes
## API contracts
## Migrations
## Security
## Observability
## Test strategy
## Risks and mitigations

Шаблон списка задач

# Tasks -- [feature name]

## Task 1 -- [title]
Depends on:
Files:
Satisfies:
Validate:
Review checkpoint:

## Task 2 -- [title]
...

Чек-лист валидации

# Validation -- [feature name]

## Automated
- [ ] All tests pass
- [ ] Lint clean
- [ ] Type check clean

## Acceptance criteria
- [ ] AC-1 --
- [ ] AC-2 --

## Spec-to-code
- [ ] Changed files match plan
- [ ] No undocumented architectural changes
- [ ] Spec updated if implementation differed

Заключение

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

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

Когда цепочка становится бумажной работой, режьте скоуп — а не ревью. Двухстраничная спецификация, прошедшая валидацию, лучше тридцатистраничной, которую никто не читал.

Полезные ссылки

• Документация GitHub Spec Kit — open-source набор инструментов, реализующий похожий цикл specify-plan-tasks-implement
• OpenSpec Quickstart: установка, рабочий процесс и типовые ошибки — легковесный, ориентированный на изменения CLI, который запускает этот же цикл как explore-propose-apply-archive
• Отклоненные предложения в OpenSpec: конвенция памяти решений — запись отклоненного решения фазы 2, чтобы его не переисследовали с нуля
• Superpowers Quickstart: установка, рабочий процесс и тестирование — устанавливаемый пакет навыков, автоматизирующий этот же пятифазный цикл с обязательными точками ревью
• Мартин Фаулер о инструментах для разработки на основе спецификаций — анализ Kiro, Spec Kit и Tessl