Spec-Driven Development: руководство для AI Coding Agent

По официальному рабочему процессу Spec Kit разработка проходит через четыре базовых артефакта — Specification, план, задачи и реализацию. Это показывает главный практический вывод: побеждает Spec-Driven Development, если AI Coding Agent должен писать код в условиях устойчивых ограничений, проверяемых требований и обязательной приёмки; для маленькой однофайловой правки без зависимостей достаточно обычного запроса. Официальное описание базового процесса подтверждает, что каждый этап создаёт структурированный результат для следующего, а не просто добавляет новый Prompt в историю чата.

Эта статья предназначена для трёх групп:

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

Фиксация проектных границ

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

В существующем репозитории сначала фиксируются постоянные правила проекта:

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

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

Главная ошибка здесь — смешать постоянные ограничения с требованиями конкретной функции. Например, «не изменять каталог миграций без отдельной проверки» относится к проекту в целом. А «после удаления пользователя отзывать его активные сессии» относится к одной функции и должно попасть в её Specification.

Полезно завершить подготовку проверяемым списком:

• [ ] В проекте указана фактическая команда установки зависимостей.
• [ ] Определены команды тестирования, статического анализа и сборки.
• [ ] Отмечены каталоги, которые AI Coding Agent не должен менять.
• [ ] Описаны правила работы с секретами и конфигурацией.
• [ ] Зафиксировано, что считается завершённой задачей.
• [ ] Понятно, кто утверждает изменения в архитектурных границах.

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

Превращение намерения в Specification

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

Для каждой функции стоит описать несколько слоёв.

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

Основные сценарии. Что происходит при корректных входных данных, какие состояния меняются и какой ответ получает клиент.

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

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

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

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

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

Пример компактной формулировки:

Функция: отзыв активных сессий после удаления учётной записи.

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

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

Такая запись не диктует конкретный класс, ORM или endpoint, но задаёт результат, исключения и доказательства.

Подготовка дизайна и зависимостей

После Specification AI Coding Agent должен сначала предложить план, а не немедленно редактировать файлы. На этом шаге проверяется, правильно ли агент понял границы изменения.

Хороший план отвечает на несколько вопросов:

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

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

Перед утверждением плана полезно попросить агента перечислить несоответствия:

Проверь план относительно Specification.
Для каждого требования укажи:
1. где оно реализуется;
2. какой тест или проверка его подтверждает;
3. какая зависимость может заблокировать работу;
4. что останется без покрытия.
Не изменяй файлы.

Этот запрос важен не из-за формулировки Prompt, а потому что разделяет анализ и изменение состояния. Если агент уже начал редактировать код, спор о плане превращается в спор о готовом решении, которое сложнее откатить.

Декомпозиция на независимые задачи

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

Список задач следует строить вокруг результата, а не вокруг абстрактных слоёв вроде «сделать backend» или «добавить frontend». Практичная задача имеет:

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

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

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

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

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

Для каждой задачи применяется короткий контроль:

• [ ] Понятно, какое требование она закрывает.
• [ ] Результат можно проверить без устного пояснения.
• [ ] Задача не смешивает несвязанные модули.
• [ ] Указаны затрагиваемые файлы или границы поиска.
• [ ] Есть команда, по которой определяется успех.
• [ ] Ясно, что делать при провале проверки.

Пошаговое выполнение изменений

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

Безопасная последовательность выглядит так.

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

Затем — локальное изменение. Агент реализует только текущую задачу и не меняет соседние компоненты «заодно», если это не указано в плане.

После этого — проверка. Сначала запускается наиболее узкий тест, затем статический анализ или сборка, а после завершения связанной группы — интеграционный сценарий.

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

Наконец — решение о переходе. Если задача соответствует Specification, она принимается. Если нет, фиксируется, на каком слое возникла проблема: в требовании, плане, задаче или коде.

Для крупных функций базовый цикл можно организовать командами Spec Kit: specify, plan, tasks, implement. В актуальной документации также описаны этапы clarify, analyze и converge, предназначенные для уточнения требований, проверки согласованности артефактов и поиска незавершённой работы. Полная схема агентного процесса

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

Связка реализации с доказательствами

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

Требование → задача → изменённые файлы → тест или проверка → результат приёмки

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

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

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

Команда анализа должна запускаться до реализации, пока исправление Specification или плана ещё дёшево. В официальной документации analyze описан как проверка согласованности между spec.md, plan.md и tasks.md; команда не должна самостоятельно скрыто редактировать исходные артефакты. Справка по analyze

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

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

Такой порядок снижает риск «лечить» архитектурную проблему локальной заплаткой.

Версионирование и изменение требований

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

При изменении требований выполняется следующая последовательность:

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

Нельзя считать код источником истины только потому, что он уже работает. Если поведение изменилось, но Specification осталась прежней, следующий запуск агента получит противоречивые инструкции. В результате AI Coding Agent может «исправить» код обратно к старому варианту, удалить нужный тест или сохранить устаревший контракт.

Для больших функций полезно делить дорожную карту на независимые спецификации. Документация Spec Kit описывает подход, при котором каждый ограниченный фрагмент имеет собственные spec.md, plan.md и tasks.md, а общая дорожная карта связывает их зависимостями. Подход к составным спецификациям

Итоговая проверка перед слиянием

Перед объединением изменений технический руководитель или ответственный разработчик может пройти короткий контроль:

• [ ] Все обязательные сценарии из Specification имеют реализацию.
• [ ] Для каждого критичного сценария есть тест или описанная ручная проверка.
• [ ] Ошибки и отрицательные сценарии не остались только в устных договорённостях.
• [ ] Изменённые файлы соответствуют границам утверждённого плана.
• [ ] Статический анализ, тесты и сборка выполнены после последнего изменения.
• [ ] В отчёте агента указаны фактические команды и результаты.
• [ ] Незапланированные изменения либо удалены, либо отдельно согласованы.
• [ ] Версия Specification, план и задачи сохранены вместе с кодом.
• [ ] Приёмка проверяет исходные требования, а не только визуальное впечатление.

Если проект требует удалённой среды для воспроизводимого запуска, тестирования или работы нескольких разработчиков, стоит заранее проверить, подходит ли облачная среда для AI Coding Agent. Для сценариев, где необходимы реальные системные компоненты Apple и удалённый доступ к macOS, полезно отдельно оценить аренду Mac mini для разработки и тестирования. Такой вариант не заменяет Specification, но помогает сохранить одинаковые команды, зависимости и состояние окружения между итерациями.

Ответы на частые вопросы

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

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

Поэтому после подготовки шаблона Specification разумно проверить, есть ли у текущего процесса версионирование, автоматические тесты и сбрасываемое окружение. Если эти компоненты нужны только на время разработки или тестирования, удалённая Mac-среда Zutcloud может дать более предсказуемый путь к запуску AI Coding Agent без покупки отдельного оборудования.