Рабочий процесс Spec-Driven Development: от требований к коду

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

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

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

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

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

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

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

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

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

Утверждение проблемы и пользователи

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

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

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

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

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

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

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

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

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

## Проблема
[Один абзац: кто страдает, почему и что вызывает боль.]

## Пользователи
- [Основная роль пользователя]
- [Вторичная роль пользователя]

## Цели
1. [Измеримый результат]
2. [Измеримый результат]

## Нецели
- [Явно выходит за рамки]
- [Явно выходит за рамки]

## Критерии приемки
- [ ] [Проверяемое поведение]
- [ ] [Проверяемое поведение]

## Открытые вопросы
- [ ] [Вопрос, блокирующий планирование]

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

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

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

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

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

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

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

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

Стратегия тестирования связана с критериями приемки. Определите, какие критерии требуют модульных тестов, какие — интеграционных, а какие — ручной проверки. Если вы используете модульное тестирование в Go или [модульное тестирование в Python](https://www.glukhov.org/ru/app-architecture/testing-architecture/unit-testing-in-python/ “Модульное тестирование в Python: полное руководство с примерами), укажите пакеты и файлы тестов, которые вы ожидаете добавить. План без стратегии тестирования — это план, который будет выпущен с пробелами, которые вы обнаружите в продакшене.

Фаза 3 — Декомпозиция задач реализации

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

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

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

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

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

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

### Задача 3 -- Добавить middleware ограничения частоты

**Зависит от:** Задача 1 (схема), Задача 2 (репозиторий)
**Файлы:** middleware/ratelimit.go, middleware/ratelimit_test.go, server.go
**Удовлетворяет:** AC-2 (429 при превышении лимита), AC-3 (заголовки лимита в ответе)
**Валидация:** `go test ./middleware/...` проходит; curl при превышении лимита возвращает 429 с Retry-After
**Контрольная точка проверки:** Подтвердить, что middleware запускается после аутентификации, но до обработчика

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

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

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

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

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

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

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

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

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

Автоматизированные проверки

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

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

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

Дифф «спефикация-код»

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

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

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

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

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

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

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

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

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

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

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

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

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

Переиспользуемые шаблоны

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

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

# Функция -- [название]

## Проблема
## Пользователи
## Цели
## Нецели
## Критерии приемки
## Открытые вопросы

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

# Дизайн -- [название функции]

## Сводка
## Затронутые модули
## Изменения модели данных
## Контракты API
## Миграции
## Безопасность
## Наблюдаемость
## Стратегия тестирования
## Риски и смягчение

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

# Задачи -- [название функции]

## Задача 1 -- [заголовок]
Зависит от:
Файлы:
Удовлетворяет:
Валидация:
Контрольная точка проверки:

## Задача 2 -- [заголовок]
...

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

# Валидация -- [название функции]

## Автоматизированно
- [ ] Все тесты прошли
- [ ] Линтинг чист
- [ ] Проверка типов чиста

## Критерии приемки
- [ ] AC-1 --
- [ ] AC-2 --

## Спецификация-код
- [ ] Измененные файлы соответствуют плану
- [ ] Нет недокументированных архитектурных изменений
- [ ] Спецификация обновлена, если реализация отличалась

Заключение

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

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

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

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

• Документация GitHub Spec Kit – набор инструментов с открытым исходным кодом, реализующий похожий цикл спецификация-план-задачи-реализация
• Мартин Фаулер о инструментах разработки на основе спецификаций – анализ Kiro, Spec Kit и Tessl