Spec-driven development: как заставить кодинг-агента писать то, что нужно. Пошагово

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

Spec-driven development, разработка по спецификации, предлагает другой порядок. Сначала вы описываете в markdown-файлах, что строить и почему. Потом агент реализует. Тема сейчас на подъёме: агенты пишут код по 20-30 минут подряд, и три-четыре минуты на внятное задание окупаются многократно. Разбираем рабочий процесс по шагам.

Зачем нужна спецификация

Спецификация даёт три выгоды.

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

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

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

Что понадобится

• Кодинг-агент. Метод не привязан к конкретному инструменту. В примере это Claude Code в терминале внутри IDE WebStorm. Подойдут и другие связки: VS Code с Codex CLI, редактор Zed с локальной моделью.
• Проект под Git. Каждый шаг фиксируется коммитом. В примере проект называется Agent Clinic: это учебный веб-сайт с TypeScript, где ИИ-агенты «лечатся» от галлюцинаций и переполненного контекста.
• Файл с пожеланиями. В примере в README.md лежат заметки трёх заинтересованных сторон: инженеры хотят надёжный стек на TypeScript, продукт хочет набор функций, маркетинг хочет современный сайт.

Создайте проект с репозиторием Git, выберите TypeScript и запустите агента командой claude. Первым делом попросите его сделать коммит стартового состояния.

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

Шаг 1. Пишем конституцию проекта

Конституция это три файла в папке specs:

• mission.md. Зачем проект, для кого, что в него входит.
• tech-stack.md. Технологии и ограничения, понятные всей команде.
• roadmap.md. Живой документ: фазы работы, каждая со своим циклом фичи.

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

Мы пишем AgentClinic, место, где ИИ-агенты находят облегчение от своих людей. Посмотри в README.md пожелания заинтересованных сторон. Создадим «конституцию» в папке specs: mission.md, tech-stack.md и roadmap.md с высокоуровневым порядком реализации очень маленькими фазами. Важно: перед записью на диск обязательно задай вопросы через инструмент AskUserQuestion, сгруппировав их по этим трём файлам.

Инструмент вопросов Claude Code по желанию. В примере его выбрали, потому что вопросы с вариантами ответов удобно читать. Маленькие фазы нужны, чтобы вы проверяли небольшие изменения.

В примере агент спросил про тон миссии (выбрали игривый), про стек и про детальность дорожной карты. После ответов он просит разрешение на запись файлов. Если вы готовы к рискам, можно разрешить такую команду на всю сессию.

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

Шаг 2. Планируем фичу

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

Начните с чистого контекста: всё нужное агент возьмёт из конституции. Работать лучше в отдельной ветке. Промт просит агента найти следующую фазу, создать ветку и расспросить вас:

Найди следующую фазу в specs/roadmap.md, создай ветку и спроси меня о спецификации фичи. Создай папку ГГГГ-ММ-ДД-название-фичи в specs, а в ней: plan.md как набор пронумерованных групп задач, requirements.md с рамками, решениями и контекстом, validation.md с тем, как понять, что реализация удалась и её можно сливать. Ориентируйся на specs/mission.md и specs/tech-stack.md. Важно: перед записью обязательно задай вопросы.

Агент задаёт вопросы по ключевым решениям. С его вариантами необязательно соглашаться. В примере выбрали оставить объём фазы как есть, зафиксировать версию Hono, включить строгий режим TypeScript, а проверку сделать вручную через curl.

Затем читаем три документа.

• План. Группы пронумерованных задач: от установки пакета до ручной проверки.
• Требования. Сюда пишем важные технические условия. Не опускайтесь до мелочей вроде имён переменных: нужно направлять агента, а не перехватывать у него руль.
• Проверка. Критерии готовности. Агент должен суметь сам убедиться, что справился.

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

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

Шаг 3. Реализуем

Перед реализацией очистите контекст командой /clear. Спека должна нести намерение, а не снимок памяти. Дальше короткий промт:

Реализуй оставшиеся группы задач.

Можно идти и по одной группе. Это разумно там, где мелкая ошибка потом разрастается: в безопасности и работе с базой данных.

Пока агент работает, смотрите на консоль. После окончания агент выдаёт сводку по каждой группе. В примере в ней видно закреплённые версии Hono, tsx и сервера, строгий режим, скрипты dev и typecheck в package.json, а также компонент главной страницы. Агент сам запустил проверку типов и curl, и обе прошли.

Запустите приложение из package.json и откройте страницу в браузере. Страница почти пустая, но видеть результат приятно.

Шаг 4. Проверяем работу сами

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

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

Ещё два правила из примера:

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

Шаг 5. Перепланируем между фичами

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

Что решили в примере:

• Тесты. Агент не знал про тестовые предпочтения, и их записали в стек: фреймворк Vitest и два скрипта, test и test:watch. Потом попросили обновить существующие спеки и написать тесты. Тесты запускаются в редакторе, при желании под отладчиком.
• Изменение продукта. Менеджер сообщил, что 40% пользователей на мобильных, и нужен адаптивный дизайн. Агента попросили обновить продуктовые и фичевые спеки и сам код. Для небольшой правки это можно сделать прямо в перепланировании. Большие работы лучше вынести в дорожную карту отдельной фазой.
• Дорожная карта. Фазы со второй по пятую решили объединить в одну и закоммитили.

Перепланирование касается и самого процесса. Если нужно, чтобы нетехнические участники следили за ходом работ, сделайте навык (skill) для журнала изменений. Навык это пакет инструкций и ресурсов, который даёт агенту новые умения. Многие агенты умеют помогать писать навыки. В примере агент создал навык в глобальной папке, поэтому он работает во всех проектах, и сразу собрал журнал изменений. Так же в навык можно упаковать этап проверки: обновить README, запустить линтер, форматирование и тесты.

Как не выгореть от ревью

Агенты порождают много кода, ревью утомляет. Что помогает по примеру:

• Чёткая граница между фичами. Перед стартом спросите себя: слита ли прошлая ветка, верна ли следующая задача, очищен ли контекст.
• Ревью на уровне требований. Выделение типов пропсов в отдельный тип попросили сделать во всём коде. Такое решение стоит записать в спеку: она растёт вместе с проектом.
• Тесты как способ понять код. Их читают и запускают под отладчиком.
• Глубокая проверка субагентами. Агенту поручили запустить несколько субагентов для разбора проекта. Они приносят замечания, а основной контекст не засоряется.

Шаг 6. Проверяем конституцию на MVP

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

Шаг 7. Подключаем метод к старому проекту

Метод работает и для уже живого кода. Конституцию агент восстанавливает по существующему коду: миссия, стек и дорожная карта собираются из репозитория и файла задач. В примере это TODO.md. Промт почти тот же, что и в шаге 1, но с указанием искать пункты дорожной карты в существующих файлах. Дальше процесс прежний: следующая фича, спека, реализация, проверка. Спека становится памятью проекта.

Шаг 8. Автоматизируем навыками

Если вы повторяете один и тот же промт для спеки фичи, оформите его как навык. Попросите агента создать навык вместе с вами, он зададит вопросы. В примере навык feature-spec лежит в .claude/skills. Навык может быть проектным или глобальным. Пишите имя навыка прямо в промте: по описанию агент выбирает навык сам, но не всегда верно, особенно при длинном контексте.

Для документации пакетов в примере поставили Context7 командой:

npx ctx7 setup

Установщик предложил выбор: MCP-сервер или CLI с навыками. Выбрали второй вариант. Считается, что CLI плюс навыки часто проще и расходуют меньше контекста, чем MCP. Для общего использования есть плагины Claude Code. Они выполняют код, поэтому доверяйте им при установке и обновлении. Готовые наборы процесса: Spec Kit от GitHub (команды constitution, plan, tasks, implement) и OpenSpec с циклом propose, explore, apply, archive.

Шаг 9. Не привязывайтесь к одному агенту

Спека работает независимо от агента. В примере навык feature-spec скопировали в папку .codex/skills и запустили в Codex. Для общения агентов и редакторов есть протокол ACP. В настройках IDE в разделе агентов есть реестр: выбираете агента и нажимаете «Install». Так в WebStorm добавили открытый OpenCode, и он работает рядом с другими агентами.

Если вы работаете из России

Сам метод это markdown-файлы и порядок работы. Он не зависит от страны и сервиса. Сложности в инструментах: Claude Code, Codex и платформы от западных компаний могут быть недоступны или требовать иностранных оплат. Проверяйте доступ заранее.

Что делать:

• Возьмите открытого агента. В реестре из примера есть OpenCode, Kilo и другие. Это агенты с открытым кодом: как подключить к ним свою модель, смотрите в документации каждого.
• Запустите открытую модель на своём сервере. Для этого метода подходит, например, связка редактора Zed с локальной моделью.
• Переносите навыки. Файлы навыков и спеки лежат в репозитории, поэтому смена агента не ломает процесс.

Если модель слабее, делайте шаги мельче и чаще проверяйте.

Что важно знать до старта

• Спека требует мыслить. Решать, что строить и какая архитектура, придётся вам. Без этого решение отдано случайности.
• Версионирование спек не устоялось. Как связывать спеки с изменениями кода, в сообществе ещё обсуждают.
• Агент делает ошибки. Он может нарушить конвенции или дописать лишнее. Ревью обязательно.
• Плагины и навыки выполняют код. Ставьте только то, чему доверяете.
• Большие рывки рискованны. Реализация остатка карты за раз оправдана только при хорошей конституции.
• Много кода быстро утомляет. Дробите работу и делайте паузы между фичами.

Что дальше

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

Мы в Агентехе учим сотрудников работать с ИИ-агентами: ставить им задачи так, чтобы результат совпадал с ожиданием, и проверять его перед внедрением. Как устроено обучение.