Spec-driven development: как писать спецификации для ИИ-агентов

Вчера вы полчаса объясняли агенту, как устроен проект, какую базу брать и чего не трогать. Сегодня открываете новую сессию — и он снова предлагает другую библиотеку, переименовывает папки и делает «почти то», что нужно. Эту проблему и решает spec-driven development. Разберемся, как вынести договорённости из чата в markdown-файлы, из чего состоит конституция проекта и как провести фичу по циклу план — реализация — проверка. На выходе — шаблон для своего репозитория и понятный порядок действий для первой фичи.

Что такое spec-driven development и чем он отличается от вайб-кодинга

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

Подход spec-driven development, или SDD (разработка от спецификации), переносит усилия в начало. До того как агент напишет хоть строку, вы фиксируете в спецификации задачу, критерии успеха, ограничения и сценарии пользователя. Агент реализует написанное, а не то, что угадал из короткого промпта.

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

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

Почему ИИ-агент теряет контекст и как спецификация это лечит

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

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

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

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

Особенно это заметно, когда агент работает долго и без вас — например, на сервере в фоновой сессии. Как настроить такую схему, разбирается в курсе «Claude Code на своём компьютере и VPS».

Конституция проекта: миссия, стек и дорожная карта

Конституция — набор документов уровня проекта, которые агент читает при каждом старте. Многие разработчики держат правила в файле AGENTS.md в корне репозитория. Конституция решает ту же задачу, но строже по структуре и не привязана к конкретному агенту: её одинаково поймут Claude Code и любой другой инструмент.

Обычно в ней три части:

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

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

Главный вопрос — уровень детализации. Пишите много о целях, аудитории и ограничениях и мало о низкоуровневых решениях, которые агент примет сам.

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

Перед коммитом конституции проверьте:

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

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

Цикл фичи: план, реализация, проверка

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

План

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

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

Реализация

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

Проверка

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

Как проверять работу агента и не утонуть в ревью

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

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

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

Если нужен второй взгляд, поручите глубокий разбор проекта субагентам. Они часто находят то, что пропустил основной агент, и не засоряют его контекст.

Перепланирование и версии спецификаций

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

Конституция — живой документ, и её тоже нужно менять. Правки делайте в отдельной ветке: так всегда можно восстановить, какая версия конституции породила какой код.

Кстати, собирать процесс с нуля не обязательно. GitHub Spec Kit — одна из попыток оформить spec-driven процесс в набор шаблонов и команд для агента. Его удобно взять за основу и подогнать под свою команду.

Чтобы цикл работал без перерывов, агенту нужна стабильная среда. Как поднять Claude Code на собственном сервере, чтобы сессии не обрывались при закрытии ноутбука, — в курсе «Установка Claude Code на локальный сервер и VPS».

Ключевые термины

• Spec-driven development — Подход, при котором агент пишет код по заранее согласованной спецификации в markdown, а спецификация считается главным артефактом проекта.
• Конституция проекта — Набор документов уровня проекта — миссия, технологический стек и дорожная карта, — задающий неизменные правила для агента и команды.
• Спецификация фичи — Комплект из плана задач, требований и критериев проверки для одной функции, который готовится до написания кода.
• Context decay (распад контекста) — Ухудшение работы агента по мере заполнения контекстного окна и потеря договорённостей между сессиями.
• Когнитивный долг — Нагрузка от необходимости понимать, что делает код и как он менялся, растущая при больших непроверенных изменениях.
• Дрейф спецификаций — Расхождение спецификаций и документации с реальным кодом после правок в обход общего процесса.
• Human in the loop — Режим работы, при котором человек проверяет каждый результат агента, прежде чем принять его.

Итог: несколько минут на спецификацию вместо часов переделок

Двадцать–тридцать минут самостоятельной работы агента могут соответствовать нескольким часам ручной разработки. Поэтому перед такой задачей выгоднее потратить три-четыре минуты на ясные инструкции, чем потом разбирать результат, который ушёл не туда. Главное: спецификация — самый дешёвый способ управлять агентом, ведь одна фраза в ней определяет сотни строк кода.

Проверьте себя

1. Вы начинаете реализацию фичи после долгого обсуждения спецификации с агентом. Что разумно сделать перед стартом?

• А. Продолжить в той же сессии, чтобы агент «помнил» обсуждение
• Б. Скопировать весь диалог в промпт реализации
• В. Очистить контекст агента и дать ему опираться на сохранённые спецификации

2. Что из этого стоит записать в требования спецификации фичи? (Верных ответов несколько.)

• А. Обязательное строгое использование TypeScript
• Б. Какие CSS-классы использовать в каждой кнопке
• В. Закреплённую версию фреймворка
• Г. Точные имена переменных в каждом компоненте

3. Вы заметили неудачную структуру файлов и хотите быстро поправить её руками в IDE. Чем это грозит?

• А. Агент откажется работать с проектом
• Б. Ничем — ручные правки всегда безопаснее
• В. Дрейфом: спецификации и README перестанут совпадать с кодом

4. Чем конституция проекта отличается от обычного файла AGENTS.md?

• А. Её пишут один раз и больше не меняют
• Б. Её читает только человек, агенту она не нужна
• В. Она не привязана к конкретному агенту и разделена на миссию, стек и дорожную карту

5. Агент реализовал фичу. Как ревьюить результат, чтобы не выгореть? (Верных ответов несколько.)

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