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

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

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

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

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

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

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

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

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

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

Описание проблемы и пользователи

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

Пример для функции ограничения частоты запросов (rate-limiting) 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 — Планирование проектирования

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Минимальный элемент задачи:

### 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 — Реализация по одной задаче за раз

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

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

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

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

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

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

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

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

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

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

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

Дифф спецификации и кода

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

Где ИИ-агенты вписываются в рабочий процесс

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

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

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

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

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

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

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

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

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

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

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 в репозитории. Обновляйте спецификацию, когда реальность расходится. Валидируйте перед слиянием. Когда цепочка работает, вы получаете меньше дрейфа, меньшие проверяемые диффы и долговечную запись намерений, которая переживает сбросы сессий и передачи между командами.

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

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

• Документация GitHub Spec Kit — open-source инструментарий, реализующий похожий цикл спецификация-план-задачи-реализация
• Superpowers Quickstart: Install, Workflow, and Tryout — устанавливаемый пакет навыков, который автоматизирует этот же пятифазный цикл с обязательными контрольными точками ревью
• Martin Fowler о инструментах разработки на основе спецификаций — анализ Kiro, Spec Kit и Tessl