Полное руководство по Spec‑Driven Development: как разрабатывать с помощью программных спецификаций AI Coding Agent

Четыре последовательных артефакта — Specification, план, задачи и реализация — составляют базовый цикл Spec-Driven Development в официальной документации проекта. (github.github.com) Победителем для команд, которые хотят сократить возвраты к AI Coding Agent, становится не самый длинный Prompt, а версия спецификации, связанная с конкретными задачами и проверяемыми доказательствами. Если требования нельзя проверить тестом, статическим анализом или ручной процедурой, Agent всё равно будет вынужден додумывать границы задачи.

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

Границы проекта до первой спецификации

Spec-Driven Development начинается не с описания функции, а с фиксации условий, которые не должны заново объясняться в каждом запросе. Этот слой можно оформить в constitution.md, CONTRIBUTING.md или другом файле проекта, если его расположение заранее принято командой.

В него стоит включить:

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

Такой файл решает сразу несколько скрытых проблем.

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

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

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

Опыт: если один и тот же запрет приходится повторять в каждом запросе, это уже не часть Prompt, а кандидат на постоянное правило проекта.

Минимальная проверка перед переходом к Specification выглядит так:

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

Если эти пункты не согласованы, дальнейшая автоматизация создаст не скорость, а больше вариантов неправильной реализации.

Наблюдаемое поведение в Specification

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

1. Цель пользователя — какую проблему решает функция.
2. Поведение системы — что происходит при конкретных входных данных.
3. Границы и исключения — что считается ошибкой, отказом или недопустимым состоянием.
4. Критерии приёмки — каким способом проверяется каждый существенный пункт.

Например, вместо фразы «добавить импорт документов» лучше записать:

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

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

Хорошая спецификация также различает обязательные и второстепенные требования. Пользовательские истории можно маркировать приоритетами, но приоритет сам по себе не заменяет критерий проверки. Запись «P1 — важная функция» недостаточна; рядом должно быть указано, какое состояние доказывает её завершённость.

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

Для каждой функции полезно ответить:

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

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

Проектирование и разбиение работы

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

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

Рекомендуемая последовательность:

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

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

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

Полезный формат каждой записи:

T014 [US2] Добавить проверку формата в src/import/validator.ts.
Результат: неподдерживаемые файлы отклоняются до записи.
Проверка: npm test -- validator.
Зависимости: T006.

В официальных шаблонах также применяется строгий формат с идентификатором задачи, отметкой параллельности, пользовательской историей и путём к файлу. (github.com) Такой формат облегчает передачу задач между разработчиком, Agent и системой контроля изменений.

Чтобы AI Coding Agent не принял предположение за факт, перед созданием задач нужно запросить у него отдельный список неопределённостей:

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

Если список содержит вопрос, влияющий на архитектуру или безопасность, переход к реализации следует остановить.

Исполнение по одной проверяемой задаче

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

Перед изменением файлов Agent должен вывести:

1. понимание задачи;
2. список предполагаемых файлов;
3. план изменения;
4. риски и неизвестные места;
5. команду или набор команд для проверки.

После изменения должен быть подготовлен отчёт:

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

Это снижает стоимость ревью: разработчик видит не только diff, но и заявленную связь между изменением и требованием. Если Agent изменил файл вне разрешённой области, это становится видимым нарушением границы, а не случайной деталью.

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

• [ ] Открыта только актуальная версия Specification.
• [ ] Проверены зависимости и запретные зоны проекта.
• [ ] Agent сформулировал план до редактирования.
• [ ] Изменение ограничено заявленными файлами и контрактами.
• [ ] Запущена проверка, указанная в задаче.
• [ ] Diff просмотрен человеком или отдельным проверочным шагом.
• [ ] Результат задачи отмечен в списке без удаления исходного критерия.

Официальная документация описывает базовый путь specify → plan → tasks → implement, а также дополнительные шаги анализа согласованности и проверки качества артефактов. (github.com) Это позволяет использовать процесс не как обязательный ритуал, а как набор контрольных ворот: полный цикл нужен для сложной функции, а малое локальное изменение может использовать сокращённый вариант при сохранении критериев приёмки.

Проверка результата и управляемый откат

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

Для каждого требования нужно назначить свидетельство:

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

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

При ошибке важно определить уровень отклонения:

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

Такой разбор не позволяет лечить архитектурную проблему новым Prompt. Если причина находится в Specification, Agent возвращают к уточнению требований. Если причина в коде, исправляется конкретная задача. Если тест не доказывает поведение, обновляется проверка, а не только реализация.

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

В автоматизированном сценарии контрольные точки можно оформить как ручные ворота между стадиями. Документация по workflow описывает команды, shell-шаги, условные переходы, циклы и остановку на ручном подтверждении; после паузы процесс можно возобновить с сохранённого состояния. (github.com) Для команды это означает, что утверждение Specification и плана не обязано происходить в одном интерактивном сеансе с Agent.

Версионирование требований и кода

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

Минимальный порядок выглядит так:

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

Для крупных функций удобно хранить отдельную папку с spec.md, plan.md, tasks.md, тестовыми контрактами и журналом решений. Официальная документация рекомендует сохранять независимые спецификации для ограниченных функциональных срезов, чтобы план и задачи оставались обозримыми в пределах контекста Agent. (github.com)

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

Рабочий минимум для команды

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

Для проектов, где требуется отдельная операционная среда, важно заранее проверить доступ к версиям инструментов, тестовым данным, переменным окружения и удалённому запуску. Если команде нужно временно прогонять сборку или автоматизированные тесты на Mac, можно отдельно изучить сценарии использования аренды Mac для разработки и тестирования, а сведения о самой инфраструктуре проверить в описании Zutcloud. Это не заменяет спецификацию, но закрывает средовой риск, из-за которого Agent часто получает неполный или невоспроизводимый результат.

Итоговая модель принятия решения

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

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

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

Частые вопросы

С чего начать внедрение Spec-Driven Development в небольшом проекте?

Начните не с генерации кода, а с короткого файла проектных ограничений: стек, команды проверки, структура каталогов, запретные зоны, правила безопасности и Definition of Done. Затем опишите одну небольшую функцию в Specification с проверяемыми сценариями. Если спецификация не помещается в одну независимую задачу, сначала уменьшите область изменения.

Насколько подробной должна быть спецификация, чтобы AI Coding Agent мог её выполнить?

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

Как AI Coding Agent должен разбивать работу по Specification?

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

Что делать, если требования изменились после реализации части кода?

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