Первая сессия с агентом обычно проходит отлично: попросили — получили работающий код. Проблемы начинаются на второй неделе, когда тем же способом делают пятое изменение в той же системе. Агент не помнит прошлых решений, каждый раз выбирает по-своему, и через десяток итераций в проекте три способа обработать ошибку, два способа сходить в базу и никто не может сказать, почему.
Причина не в модели. Задача ставилась голосом и в чате — в форме, которая нигде не хранится и ни с чем не сверяется. Ответ на это придумали не вчера: записать, что должно получиться, до того, как писать код. Новое здесь то, что записанное читает не только человек, но и агент, — и потому от формы записи стало зависеть гораздо больше.
Подход, выросший вокруг этой идеи, называют spec-driven development. Разберём, из чего он состоит, что даёт и где ломается.
Цикл изменения: зачем меняем → сценарии поведения → как делаем → чеклист шагов → архив после мержа.
Что это такое
Spec-driven development — способ вести работу, при котором артефактом договорённости становится документ в репозитории, а не сообщение в чате. Код появляется из этого документа, а не наоборот.
Ключевое отличие от «написать ТЗ» — в том, что документ живёт в том же репозитории, что и код, проходит ревью как код и обновляется тем же движением, что и код. Он не «согласован и забыт»: если поведение системы изменилось, а документ нет, это такая же поломка, как красный тест.
Цикл: от предложения до архива
Инструменты отличаются деталями, но схема у них общая. Изменение проходит четыре шага, и каждый — отдельный файл.
Предложение. Зачем вообще меняем: какая проблема, у кого, что будет, если не делать. Одна страница, без решения. Этот шаг чаще всего пропускают — и зря: половина задач отваливается именно здесь, когда выясняется, что проблему решает настройка, а не новый раздел.
Требования. Что именно должно происходить, в сценариях. Формат, ставший стандартом де-факто, выглядит так:
### Требование: отмена заказа
Покупатель может отменить заказ, пока он не отправлен.
#### Сценарий: отмена оплаченного заказа
- КОГДА покупатель отменяет оплаченный заказ
- ТОГДА заказ переходит в статус «отменён»
- И деньги возвращаются на карту в течение суток
#### Сценарий: отмена отправленного заказа
- КОГДА покупатель отменяет отправленный заказ
- ТОГДА система отказывает и предлагает оформить возврат
Такой сценарий одинаково читается человеком, проверяется тестом и понимается агентом. Это его главное свойство — не красота, а то, что из него выводится и код, и проверка.
Дизайн. Как делаем технически: какие сущности трогаем, какие границы, что с обратной совместимостью, какие есть альтернативы и почему выбрали эту. Здесь же честно пишут, чего решение не делает.
Задачи. Чеклист шагов, по которому идёт работа. Обычно с отметками: сделано, проверено. Агент берёт задачи по одной, человек видит, где он находится.
После мержа изменение архивируют: файлы переезжают в каталог завершённых, а то, что они описывали, уже отражено в коде и в долгоживущей документации. Каталог изменений — это история решений: почему сделали именно так, видно без раскопок в истории коммитов.
Инструменты
Три заметных инструмента реализуют одну схему по-разному.
OpenSpec — самый лёгкий: несколько markdown-шаблонов, каталог openspec/ в репозитории и соглашение о том, как оформлять изменение. Не привязан ни к какой среде разработки и работает с любым агентом, потому что ничего не требует, кроме файлов.
Spec Kit от GitHub — жёстче по процессу: фазы идут по порядку, у каждой свой артефакт и своя команда. Даёт больше дисциплины и меньше свободы; хорошо ложится там, где над проектом работает несколько человек и порядок важнее скорости.
Kiro от AWS — тот же цикл, встроенный в собственную среду разработки: спецификация, задачи и агент живут в одном окне. Удобно, пока вы внутри этой среды.
Выбор между ними — вопрос вкуса и того, насколько формальный процесс нужен команде. Механика одна: изменение описывается до реализации и остаётся в репозитории.
Что это даёт на самом деле
Агент получает согласованные требования, а не пересказ. Разница видна сразу: «сделай отмену заказа» и файл со сценариями дают разный код. Во втором случае агент не изобретает поведение для отправленного заказа — оно уже описано.
Появляется предмет для спора до написания кода. Обсуждать сценарий на полстраницы дешевле, чем обсуждать пул-реквест на восемьсот строк. Замечание «а если заказ уже отправлен?» стоит минуту на этапе требований и полдня на этапе ревью.
У изменения появляется след. Через полгода вопрос «почему здесь так?» получает ответ из архива изменений, а не из легенд.
Чеклист задач держит длинную работу. Агент в длинной сессии теряет нить: помнит последние сообщения, забывает первые. Список задач в файле — внешняя память, к которой он возвращается.
Где этот подход ломается
Честный разбор важнее рекламы, поэтому — четыре типичных провала.
Спека расходится с кодом. Самый частый. Изменение сделали, документ поправить забыли; через три итерации документ описывает систему, которой нет. Дальше он вреден: агент читает его и уверенно делает не то. Лечится единственным способом — правка документа входит в то же изменение, что и правка кода, и ревьюер это проверяет.
Чеклист выполнен, а система не та. Задачи закрыты все до одной, а пользователь по-прежнему не может отменить заказ. Так бывает, когда задачи писали от реализации («добавить поле», «создать метод»), а не от поведения. Признак здорового чеклиста: по нему можно проверить результат, не открывая код.
Сценарии описывают поведение, но не модель. Из строк «КОГДА — ТОГДА» не видно, что «заказ» — это единое целое с правилом «сумма позиций равна итогу», что «отменён» — конечное состояние, из которого нет выхода. Когда таких правил много, они расползаются по сценариям и начинают противоречить друг другу. Это не довод против сценариев — это граница их применимости: они описывают изменение, а не систему.
Спека ради спеки. Правка текста в подсказке не заслуживает четырёх файлов. Если цикл обязателен для всего, его начинают обходить — и он перестаёт работать там, где действительно нужен. Разумное правило: полный цикл на изменение, которое трогает поведение, видимое снаружи; всё остальное — обычным пул-реквестом.
Спецификация изменения и спецификация системы
Из последнего провала растёт различие, которое стоит держать в голове.
Описанные инструменты работают со спецификацией изменения: она живёт от предложения до архива. Есть и другой вид — спецификация системы: она описывает домен целиком (сущности, их жизненный цикл, правила, команды и события) и живёт столько же, сколько сервис. На ней стоит Use Case Pattern, и она отвечает на вопрос «как устроено», а не «что мы меняем в этот заход».
Они не конкуренты. Долгоживущая спецификация даёт агенту модель мира, дельта изменения — текущую задачу и её границы. Подробное сравнение — в статье Use Case Pattern и spec-driven инструменты.
Как начать завтра
Не нужно ставить инструмент, чтобы попробовать. Возьмите ближайшее изменение и заведите для него один файл с четырьмя разделами: зачем, сценарии, как делаем, задачи. Дайте агенту этот файл целиком и попросите идти по задачам. После мержа — обновите файл под то, что получилось, и уберите в архив.
Двух-трёх таких заходов достаточно, чтобы понять, нужен ли вам формальный инструмент или хватает соглашения в команде. Начинать с выбора инструмента — обычная ошибка: он не создаёт дисциплину, а только оформляет уже существующую.
Коротко
- Spec-driven development — это про то, что договорённость живёт файлом в репозитории и проходит ревью как код, а не остаётся сообщением в чате.
- Цикл: предложение (зачем) → требования сценариями → дизайн → чеклист задач → архив после мержа.
- Сценарии «КОГДА — ТОГДА» одинаково читаются человеком, агентом и тестом — в этом их ценность.
- Инструменты — OpenSpec (легко и где угодно), Spec Kit (жёсткий процесс), Kiro (всё в своей среде); механика у всех одна.
- Главные провалы: документ разошёлся с кодом, чеклист выполнен «по реализации», сценарии не выражают модель, полный цикл ради однострочной правки.
- Спецификация изменения отвечает «что меняем сейчас», спецификация системы — «как всё устроено»; вместе они дают агенту и задачу, и модель мира.
Что почитать дальше
- Работа с агентами: базовый цикл — как вести сессию, когда задача уже описана.
- Ревью и приёмка AI-кода — что проверять в том, что агент принёс по спецификации.
- Use Case Pattern и spec-driven инструменты — чем спека изменения отличается от спеки системы.