Рабочий процесс Spec-Driven Development

Если AI-агент сразу получает крупную задачу, вы получаете длинный diff, неясные допущения и сложное ревью. Самое быстрое решение — разделить процесс на два контура: Specification управляет требованиями и приемкой, а кодовый контур выполняет небольшие проверяемые задачи, связанные с версией, номером задачи и результатами тестов.

Кому нужен этот рабочий процесс

Эта схема предназначена для команды, которая собирается внедрить Spec-Driven Development в уже существующий репозиторий, а не писать учебный проект с нуля. Она особенно полезна руководителю разработки, которому нужно организовать коллективную проверку кода, созданного AI Coding Agent.

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

Почему нельзя передавать агенту задачу напрямую от идеи к коду

Проблема обычно начинается не с качества модели, а с отсутствия промежуточных обязательств. Формулировка «добавить уведомления пользователям» может скрывать несколько разных решений:

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

Если всё это остаётся в чате, команда теряет единую точку отсчёта. Один разработчик считает задачу выполненной после добавления API, другой ожидает очередь сообщений, а AI Coding Agent может самостоятельно расширить область изменений.

У такого подхода есть как минимум четыре скрытых ограничения:

1. Невозможность объективной приёмки. Нельзя проверить требование, если заранее не описаны наблюдаемое поведение и исключения.
2. Потеря контекста между сессиями. После перезапуска агента приходится повторно объяснять архитектурные решения и уже проверенные ограничения.
3. Рост стоимости ревью. Чем больше несвязанных файлов меняется за один проход, тем труднее отличить необходимую реализацию от самовольного рефакторинга.
4. Слабое восстановление после сбоя. Если задача не разделена на проверяемые этапы, после ошибки приходится заново анализировать весь незавершённый diff.

Поэтому в рабочем процессе должны существовать две связанные, но не смешанные линии:

• контур намерения — требования, Specification, ограничения, критерии приемки;
• контур исполнения — технический план, задачи, изменения файлов, команды проверки и результаты ревью.

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

Как требования превращаются в Specification

Первый этап: зафиксируйте границы, а не решение

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

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

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

В Specification полезно разделять три типа информации:

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

Каждый пункт связывайте с номером требования. Например, REQ-014 может описывать повторную отправку уведомления, а критерии приемки — несколько допустимых и недопустимых сценариев. Такой номер затем попадает в технический план, tasks.md, название ветки или pull request и отчёт агента.

Что должно находиться в Specification

Хорошая Specification описывает не внутренние действия модели, а контракт поведения системы. Минимальный состав выглядит так:

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

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

Чем Specification отличается от технического дизайна

Specification отвечает на вопрос: что система должна делать и как заказчик поймёт, что результат корректен. Технический дизайн отвечает на другой вопрос: как изменить конкретный репозиторий, чтобы это поведение реализовать без нарушения его архитектурных ограничений.

Например, Specification может требовать, чтобы пользователь видел только собственные документы и получал понятную ошибку при обращении к чужому объекту. Технический план уже определяет:

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

Если смешать эти уровни, техническое решение начнёт незаметно менять исходное требование. Агент может выбрать удобную ему структуру данных, а команда примет её за часть Specification, хотя бизнес-решение ещё не было согласовано.

Практическое правило простое: если изменение влияет на пользовательское поведение, границу ответственности или критерий приемки, его нужно вернуть в Specification. Если оно описывает размещение компонентов, зависимости, миграции и команды тестирования, оно относится к техническому плану.

Как подготовить существующий репозиторий к работе агента

Перед запуском AI Coding Agent не передавайте ему весь репозиторий без ориентиров. Сначала сформируйте технический план с четырьмя обязательными блоками.

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

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

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

Стратегия тестирования. Свяжите каждый критерий из Specification с проверкой: модульной, интеграционной, контрактной, браузерной или ручной. Если тест пока невозможно автоматизировать, укажите, кто и каким способом выполняет ручную проверку.

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

В актуальной документации Spec Kit базовый цикл описывается как «Spec → Plan → Tasks → Implement», а расширенный процесс дополняется уточнением, контрольными списками, анализом согласованности и проверкой сходимости. Каждый этап создаёт артефакт, который используется следующим этапом, а не заменяется очередным длинным запросом к модели. (github.com)

Важно: конкретные команды и каталоги следует проверять по версии установленного инструмента. Например, в текущей документации Spec Kit активная функция отслеживается через .specify/feature.json, а переключение ветки Git само по себе не обязано менять активный каталог функции. (github.com)

Какой размер задачи передавать AI Coding Agent

Второй этап: превратите план в проверяемые изменения

Каждая задача должна иметь пять полей:

1. ссылку на пункт Specification;
2. целевые файлы или ограниченную область репозитория;
3. зависимость от предыдущих задач;
4. команду или набор команд проверки;
5. условие выхода, после которого задача считается завершённой.

Не передавайте агенту задачу «реализовать весь модуль авторизации». Разделите её, например, на добавление схемы данных, проверку сервиса, обработку одного маршрута, тесты отказа и обновление документации. Размер выбирайте не по числу строк, а по способности человека быстро проверить результат.

Для длительной работы используйте контрольные точки:

• после изменения схемы данных;
• после создания основного интерфейса;
• после добавления негативных сценариев;
• после прохождения тестов;
• перед переходом к следующей пользовательской истории.

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

Официальное описание Spec Kit прямо предусматривает выполнение задач в порядке зависимостей, поддержку поэтапной реализации крупных функций и повторную проверку результата после выполнения. Для больших изменений рекомендуется запускать реализацию отдельными фазами, проверяя каждую перед переходом к следующей. (github.com)

Решение можно принимать по следующим условиям:

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

Как встроить Spec-Driven Development в Git-процесс

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

• Specification;
• технический план;
• список задач;
• результаты анализа;
• тестовые отчёты;
• итоговый diff и описание нерешённых вопросов.

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

Не принимайте pull request только потому, что тесты прошли. Перед слиянием проверьте четыре связи:

• каждый обязательный пункт Specification имеет реализацию;
• каждая существенная часть реализации относится к пункту Specification;
• тесты покрывают не только успешный сценарий, но и описанные исключения;
• код не расширяет объём задачи без отдельного согласования.

Если команда использует Spec Kit, его команда анализа проверяет согласованность между spec.md, plan.md и tasks.md до реализации. При обнаружении конфликта исправлять нужно исходный артефакт, а не маскировать проблему дополнительным кодом. (github.com)

Что проверять на код-ревью, кроме качества кода

Ревью в двухконтурном процессе состоит из двух независимых вопросов.

Проверка реализации:

• работает ли основной сценарий;
• корректно ли обрабатываются ошибки;
• не нарушены ли права доступа;
• не появились ли лишние зависимости;
• проходят ли заявленные команды проверки;
• не затронуты ли несвязанные файлы.

Проверка соответствия Specification:

• реализованы ли все критерии приемки;
• присутствуют ли описанные исключения;
• не изменилось ли поведение за пределами согласованного объёма;
• нет ли требований, которые остались только в документации;
• совпадают ли номера задач, тестов и итогового изменения.

Отчёт AI Coding Agent должен включать не рекламное резюме, а проверяемые сведения:

• краткий diff по компонентам;
• перечень выполненных задач;
• команды и их результаты;
• известные ограничения;
• нерешённые вопросы;
• пункты Specification, требующие ручной проверки.

После реализации полезно запускать отдельный этап проверки сходимости. В Spec Kit он сравнивает кодовую базу со Specification, планом и задачами; если обнаружены пропуски, новые задачи добавляются в tasks.md, после чего реализацию и проверку можно повторить. (github.com)

Как поддерживать спецификации после релиза

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

• реализация нарушила действующую Specification;
• Specification была неполной;
• бизнес-правило изменилось;
• технический план оказался несовместимым с репозиторием.

В первом случае исправляется код и добавляется тест. Во втором обновляются Specification и критерии приемки, затем создаётся новая задача. Если изменилось бизнес-правило, старая версия документа должна остаться доступной для истории, а новая — получить отдельный номер или версию.

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

Для автоматизации последовательности можно использовать workflow с ручными воротами между этапами. Документация Spec Kit описывает сценарии, в которых после генерации Specification требуется одобрение человека, затем создаются план и задачи; workflow можно приостанавливать и возобновлять с места прерывания. (github.com)

Ниже — компактное сравнение вариантов организации процесса:

Что проверить перед запуском удалённого агента

Если код будет выполняться не на компьютере разработчика, к двухконтурной схеме добавляется инфраструктурный контур. До начала работы проверьте:

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

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

Текущий подход — локальный ноутбук или общий сервер — часто имеет три недостатка: агент конкурирует с рабочими процессами разработчика за ресурсы, состояние долгой сессии сложнее передать другому ревьюеру, а восстановление после сбоя зависит от конкретного компьютера. Если вам нужен временный изолированный Mac для AI Coding Agent, тестирования и удалённого ревью, аренда через kvmboot может оказаться удобнее постоянной настройки отдельной машины. Для долгой стабильной нагрузки или задач, которым требуются физические периферийные устройства, собственный Mac всё же рациональнее.

Так Spec-Driven Development превращается не в набор шаблонов, а в управляемую цепочку передачи ответственности: требования определяют границы, Specification фиксирует поведение, план описывает влияние на репозиторий, задачи ограничивают действия агента, а ревью подтверждает одновременно код и исходный контракт.