Spec-driven разработка: почему решения теряются и как их сохранить

Что теряется при вайб-кодинге

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

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

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

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

Ключевой дефект вайб-кодинга — не в том, что код плохой, а в том, что provenance (происхождение решения) не сохранён. Решения существуют, но не там, где их можно найти, ревьюитить и переиспользовать.

Артефакт как носитель решения

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

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

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

Что меняется на практике. Решение, зафиксированное в артефакте, можно восстановить в новой сессии. Его можно отревьюить — как текст, а не как догадку о намерениях. Его можно передать другому разработчику или другому агенту. И его можно аудировать: «вот этот код получился из вот этой спецификации и вот этого плана».

Файл в корне проекта — самый простой пример примитива. В CLAUDE.md Claude Code хранит основные инструкции проекта: файл лежит в корне репозитория и подгружается в каждую сессию. Это дешёвый способ задать инструкции, которые не должны теряться между задачами. Уровень выше — артефакты, относящиеся не ко всему проекту, а к конкретному приложению, слою или API: общие для всего репозитория файлы размывают контекст, а привязанные к области — нет.

Выглядит это так — файл с правилами, который агент читает на каждой сессии:

# CLAUDE.md

## Стек
- .NET 10, C# 14, Async-first
- PostgreSQL 17, EF Core
- Логирование через Serilog, structured JSON

## Соглашения
- Имена методов — camelCase, async-методы с суффиксом Async
- Контроллеры только принимают и валидируют, вся логика — в сервисах
- DTO отдельно от моделей EF, маппинг через AutoMapper

## Чего не делаем
- Не пишем SQL руками
- Не используем string.Format
- Не добавляем пакеты без обсуждения

Обратите внимание на последний раздел. Запреты работают не хуже требований: агент, у которого нет образца «как у нас», склонен придумывать свой. Явный список запрещённого — самый дешёвый способ закрыть этот разрыв.

Два подхода: BMAD и Spec Kit

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

GitHub Spec Kit (github/spec-kit) — набор инструментов для spec-driven разработки: спецификации как версионируемые markdown-артефакты, которые может прочитать любой агент. Лицензия MIT, привязки к конкретному IDE нет — работает с разными помощниками. Устанавливается через specify init.

Ядро процесса — пять фаз, каждая из которых порождает артефакт и передаёт его следующей:

Global Rules → Requirements → Execution Plan → Discrete Tasks → Implement

Первая фаза, /speckit-constitution, задаёт ДНК проекта: версии стека, соглашения об именовании, принципы слоёв и архитектуры, разрешённые и запрещённые библиотеки, требования к авторизации, логированию и доступности. Механизм важен: он закрывает разрыв в стандартах, который AI создаёт, когда у него нет образца «как устроен наш код». Модель получает то же руководство, которое получи бы новый сильный сотрудник в первый день. В методологии Spec Kit конституция описана как набор неизменяемых принципов — её создают один раз на проект, а не на каждую фичу.

/speckit-specify фиксирует функциональный и нефункциональный замысел: требования, пользовательские истории, крайние случаи, зависимости от API, требования к доступности и производительности. /speckit-plan описывает, что именно будет изменено: сервисы, модули, потоки данных, точки интеграции. /speckit-tasks разбивает спецификацию на атомарные единицы, которые оформляются в несколько файлов. /speckit-implement — выполнение, уже в рамках зафиксированных ограничений.

Один нюанс: перечисление фаз расходится между версиями. В журнальной статье их пять, в актуальном README добавлена шестая стадия converge — она проверяет, сошлись ли реализация и спецификация, и цикл implement/converge повторяется, пока не будет вынесен вердикт. Уточнение двусмысленностей вынесено в отдельный разбор, а не в обязательный шаг конвейера.

BMAD (Breakthrough Method for Agile AI-Driven Development, bmad-code-org/BMAD-METHOD) — фреймворк, построенный на агентах. Вместо одного потока он моделирует команду: каждой роли соответствует свой агент с персоной, набором навыков, инструкциями, ограничениями и списком доступных команд. В журнальной статье показан режим «party mode» (/bmad-party-mode) — оркестратор подбирает голоса, собирает контекст, запускает агентов и показывает их ответы. В разбор решения об архитектуре игры на площадке выступили четыре: Winston (системный архитектор), Cloud Dragonborn (архитектор игрового движка), Indie (соло-разработчик) и Amelia (старший инженер). Ключевая деталь режима в том, что каждый агент работает отдельным субагентом и думает самостоятельно: если один LLM разыгрывает нескольких персонажей сразу, их мнения сходятся и выглядят наигранно.

Артефакты у BMAD свои, и они не совпадают с артефактами Spec Kit. Требования разделены на brief.md (замысел и границы) и prd.md (детальные функциональные требования). Дизайн живёт в отдельном architecture.md — с потоками системы и схемами данных, тогда как Spec Kit складывает техническую часть в сам spec.md. План в BMAD — это epics.md, agile-конструкт из групп связанных фич и историй, а не пошаговая стратегия реализации. Единица работы — файл <story_name>.md с исполняемыми инструкциями для агента-разработчика, тогда как tasks.md в Spec Kit часто остаётся чек-листом. Организация контекста тоже разная: BMAD ведёт index.md с каталогом каждого файла в директории, Spec Kit полагается на структуру папок.

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

Как выбрать свой вариант

Если команда хочет минимальный вход в процесс — Spec Kit ближе: specify init, шаблоны, привычные slash-команды. Он же даёт конституцию проекта, которая работает как постоянный слой намерений.

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

Что важно понимать про оба: это методологии, а не инструменты, привязанные к модели. Их артефакты — обычный markdown в git, поэтому они переживают смену помощника и читаются любым разработчиком, даже тем, кто никогда не работал с агентами.

И то, и другое — не серебряная пуля. Сравнительное исследование шести фреймворков (arXiv 2606.04967) выделяет ряд повторяющихся рисков, и они одинаковы для обоих подходов: расхождение между спецификацией и кодом по мере работы, чрезмерное доверие сгенерированным артефактам, хрупкость community-расширений, зависимость от платформы и отсутствие бенчмарков для процесса целиком. Там же зафиксирован структурный компромисс: ни один фреймворк не закрывает все шесть измерений процесса, а глубина процесса напрямую конкурирует с переносимостью между агентами.

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

Что это даёт на практике

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

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

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

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

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

О чём стоит помнить

• Главный дефект вайб-кодинга — потеря provenance: решения остаются в диалоге и не доезжают до кода.
• Артефакт — вход для генерации, а не отчёт о ней. Спецификация задаёт, что делать; код — следствие.
• Примитивы контекста бывают разного уровня: CLAUDE.md в корне задаёт инструкции для всего проекта, а привязанные к области файлы — для конкретного слоя.
• Spec Kit строит конвейер стадий (Constitution → Specify → Plan → Tasks → Implement, в актуальной версии добавлен converge), BMAD — командную модель из агентов с оркестратором и раздельными артефактами brief.md, prd.md, architecture.md, epics.md.
• Оба подхода не зависят от конкретного помощника: артефакты — markdown в git.
• Методология работает настолько, насколько её соблюдают: артефакт, который никто не пересматривает, превращается в формальность.

Похожие статьи

• Инженерное лидерство в AI-продуктах: оценка, роли, поставка
• Как вывести AI PoC в продакшн: 90 дней по фазам
• Agentic-пайплайны в enterprise: паттерны и антипаттерны
• Архитектура enterprise AI: четыре решения, которые всё определяют

CTA

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

Внедрить spec-driven практику в вашем процессе — напишите нам.