Ключевые выводы

Спецификация — источник истины, код — проекция. В классическом цикле спецификация была лесами: её читали на старте и выбрасывали, когда «настоящая работа» переезжала в файлы. С агентами ИИ это переворачивается. Код дёшев и воспроизводим; дорого стоит согласованное поведение. Если поведение живёт только в чате, его нельзя ни проверить, ни передать следующей модели.

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

Разработка по наитию и SDD используют одного агента и разных судей. По наитию судья — глаз автора: «вроде работает». В SDD судья — контракт: сценарии, инварианты, запреты и команды проверки. Короткий разбор нового жизненного цикла фиксирует ту же развилку на уровне культуры; эта статья разбирает артефакт, без которого культура не закрепляется.

Исполняемой спека должна быть там, где цена ошибки высока. Проза годится для мотивации и границ продукта. Контракт OpenAPI, автомат состояний заказа, матрица прав доступа, схема миграции — это уже не «документация», а то, против чего агент и конвейер могут проиграть. Экономика тестирования подсказывает пропорцию: чем дороже сбой, тем меньше права оставлять истину в абзаце «как задумано».

Главная поломка — дрейф, не «глупая модель». Агент охотно допишет тесты под уже сгенерированный код и получит зелёный конвейер при нарушенном намерении. Слишком широкая спека («улучши оплату») даёт агенту свободу менять архитектуру. Узкая и устаревшая — заставляет его соблюдать ложный контракт. SDD работает, пока спека и код обновляются одним запросом на слияние.

Что такое Spec-Driven Development и чем это не «ещё один README»

Spec-Driven Development — способ вести изменение так, чтобы сначала зафиксировать намерение в проверяемом виде, а уже затем поручить агенту реализацию. Спецификация здесь не сопроводительный текст и не страница вики «для введения в проект». Это первичный артефакт изменения: его читают человек и модель, по нему строят план, по нему судят готовность.

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

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

README отвечает на другой вопрос: как запустить проект, куда смотреть новому человеку, какие команды существуют. Он может ссылаться на спеки, но сам не задаёт поведение фичи. Страница вики часто описывает систему «как было в прошлом квартале». Комментарий в тикете живёт в чужой системе и выпадает из git. Спека SDD лежит рядом с кодом, проходит ревью и имеет ту же ветку, что и патч.

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

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

Спека vs промпт vs тест vs тикет

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

Инструкция модели (prompt) — это запуск. Она сообщает агенту, с чего начать, какие файлы открыть, какой стиль ответа нужен. Её сила в гибкости: можно уточнить за 30 секунд. Её слабость в том, что она не является договором. Сосед по команде не ревьюит ваш сеанс. Следующая модель не увидит вчерашний диалог. Конвейер не прогонит инструкцию как оракул. Инженерия инструкций полезна; она не заменяет спецификацию, как стартовая фраза на стендапе не заменяет критерии приёмки.

Тикет — это указатель. Он нужен для очереди, приоритета, связи с релизом и учёта. В нём часто есть заголовок, набросок и ссылка. Если тикет содержит единственную формулировку поведения, эта формулировка окажется вне git, вне ревью кода и вне контекста агента, который читает репозиторий. Здоровая схема: тикет ссылается на файл спецификации в ветке; спор о поведении идёт в файле, а не в комментариях трекера.

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

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

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

Цикл: спека → план → код агента → проверка спекой

Рабочий процесс SDD выглядит линейным на схеме и итеративным на практике. Линейность нужна, чтобы не начинать с кода. Итеративность нужна, потому что уточнение намерения — нормальная инженерная работа, а не провал метода.

Первый шаг — спецификация поведения. Человек (иногда вместе с агентом-редактором, но с правом подписи у человека) фиксирует цель в терминах пользователя или системы, сценарии успеха и отказа, нецели, данные, инварианты, критерии приёмки. Технологический стек на этом шаге сознательно вторичен: иначе команда спорит о фреймворке, не договорившись, что система должна делать. В инструментах вроде Spec Kit этот шаг близок к /speckit.specify: что и зачем, не на чём.

Второй шаг — план реализации. Здесь появляются границы модулей, контракты между сервисами, миграции, риски, команды проверки. План обязан укладываться в конституцию проекта: запрещённые зависимости, правила безопасности, требования к тестам. Если план противоречит спеке, правится план, а не «подгоняется» формулировка поведения под удобный патч. /speckit.plan в этой логике — чертёж, а не замена договора.

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

Четвёртый шаг — код агента. Модель читает спеку, план и правила репозитория, меняет файлы, запускает проверки среды. Как среды разработки работают с кодом объясняет, почему результат зависит от индекса, сборки контекста и инструментов, а не только от «умности» модели. SDD не отменяет эту механику: он задаёт, какой документ обязан попасть в контекст раньше, чем агент начнёт угадывать.

Пятый шаг — проверка против спецификации, не только против тестов. Тесты могут быть ложнозелёными. Ревьюер читает разницу файлов и пропускает нарушение нецели («не менять публичный контракт»), потому что дифф аккуратный. Проверка спекой означает: каждый критерий приёмки либо подтверждён командой, либо явно помечен как непроверенный. Инструменты вроде /speckit.analyze ищут разрывы между spec.md, plan.md и tasks.md: задача без требования, требование без задачи, план, который противоречит договору.

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

На схеме это «спека → план → код → проверка». В жизни после проверки часто возвращаются к спеке: уточнили крайний случай, добавили нецель, сузили инвариант. Это не отказ от SDD. Отказ — начать со второй попытки «просто поправь, ты же видишь репозиторий».

Инструменты 2026: Spec Kit / OpenSpec, AGENTS.md, правила Cursor, контракты OpenAPI

Инструменты не равны методу, но в 2026 году метод наконец получил явный контур в репозитории. Имеет смысл различать каркас процесса, постоянные правила агента и исполняемые контракты. Их часто сваливают в одну папку «для ИИ» — и тогда снова получается промпт подлиннее.

Spec Kit (github/spec-kit) — открытый набор для разработки от спецификации, рассчитанный на разных агентов: Copilot, Claude, Gemini и десятки интеграций. Ядро процесса: конституция проекта, спецификация фичи, план, задачи, реализация, анализ согласованности. Конституция (часто constitution.md) держит ненарушаемые правила: архитектурные запреты, требования к проверкам, границы безопасности. Спеки фич живут отдельно и описывают конкретное изменение. Это хорошо ложится на зелёное поле и на команды, которым нужен общий ритуал «не начинай с кода». Слабое место — иллюзия, что шаблоны сами по себе дают качество: пустой spec.md с заголовками без инвариантов агент заполнит общим местом.

OpenSpec ближе к коричневому полю. Идея дельта-спек: описывать изменение относительно текущего поведения, а не переписывать «всю систему как надо» перед первым патчем. Для сервиса с пятилетней историей это честнее. Полная конституция и полный каталог требований с нуля стоят дорого и часто остаются непрочитанными. Дельта в запросе на слияние ревьюится как часть изменения: вот что было, вот что станет, вот задачи. Риск другой — набор дельт без периодического слияния в актуальный снимок снова превращается в археологию.

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

Правила Cursor (проектные .cursor/rules, навыки, пользовательские инструкции) решают ту же задачу на стороне конкретной среды разработки. Их ценность — направить агента к спеке и конституции, а не продублировать спеку другим языком. Дублирование создаёт третий источник истины: модель выберет самый удобный абзац. Полезное правило: «перед патчем прочитай файл спецификации в ветке; не выдумывай критерии приёмки; если критерия нет — остановись». Механика индекса и режимов агента описана в разборе сред разработки; SDD добавляет какой файл обязан быть во входе.

Контракты OpenAPI (и родственные схемы: JSON Schema, Protobuf, GraphQL) — самый понятный пример исполняемой спеки для границ сервиса. Они уже были нужны людям: клиенты, моки, проверки совместимости. С агентами их роль усиливается. Модель, которой дали только прозу «добавь поле скидки», придумает тип, обязательность и поведение null. Модель, которой дали контракт и запрет ломать существующие операции, ограничена схемой. Контракт не заменяет сценарии продукта, но закрывает слой, где агенты ошибаются чаще всего: границы, статусы ошибок, идемпотентность.

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

SDD vs TDD vs BDD: когда спека должна быть исполняемой

TDD, BDD и SDD спорят не из-за аббревиатур, а из-за вопроса: какой артефакт считается первичным договором. Команды, которые «уже пишут тесты», часто думают, что SDD им не нужен. Команды, которые «уже пишут спеки», иногда не пишут ни одного исполняемого критерия. Оба края ломаются об агента.

В TDD договор — тест единицы поведения, написанный до кода. Это мощно для алгоритма, чистой функции, редуктора, правил расчёта. С агентом TDD даёт конкретный оракул: пока тест красный, работа не закончена. Слабость в масштабе. Тест не объясняет, зачем существует модуль, какие нецели действуют, какой публичный контракт нельзя ломать. Агент, оптимизируя локальный красный тест, легко нарушит инвариант соседнего слоя. TDD остаётся отличным фрагментом исполняемой спеки, не её заменой.

В BDD договор — примеры на языке сценариев: дано / когда / тогда. Это сильнее связывает продукт и проверку. Слабость — полнота. Набор сценариев редко покрывает матрицу прав, совместимость API и нагрузку. Агент обожает дописать ещё три сценария «на всякий случай», которые фиксируют случайную деталь интерфейса. BDD ценен как видимый срез спеки для поведения пользователя; как единственный источник истины он узкий.

SDD ставит выше документ намерения, из которого выводятся и сценарии BDD, и тесты TDD, и контракты. Это не отмена красно-зелёного цикла. Это признание, что агенту нужен договор шире, чем одно проверочное утверждение. Спека говорит: вот инвариант оплаты, вот нецель «не менять фискальный контур», вот команда, которой проверяем идемпотентность. Тесты — способ спросить систему об этом инварианте.

Когда спека должна быть исполняемой:

1. Границы между системами: API, события, схемы сообщений. Проза здесь — приглашение к дрейфу версий.
2. Деньги, лимиты, идемпотентность, повторная доставка. Цена ошибки описана в экономике сбоев.
3. Авторизация: роли, ресурсы, запрет расширять доступ «потому что так проще тестировать».
4. Состояния: заказ, платёж, тикет поддержки. Таблица переходов проверяется; абзац «как обычно» — нет.
5. Миграции данных: что происходит со старыми строками, что необратимо.

Когда спека может остаться прозой (с нумерованными критериями, но без схемы):

• мотивация и контекст рынка;
• границы эксперимента («проверяем гипотезу на 5% трафика»);
• качественные ограничения UX, которые всё равно принимает человек глазами;
• явные нецели, которые трудно выразить тестом, но легко нарушить широким патчем.

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

Где ломается: дрейф спеки, ложнозелёные тесты, слишком широкая спека

Метод ломается предсказуемо. Три отказа встречаются чаще, чем «модель недостаточно умна».

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

Ложнозелёные тесты. Агент получил задачу «покрой тестами» после того, как уже написал код. Он кодирует факт, не намерение. Ещё хуже: он ослабляет утверждения, чтобы конвейер прошёл. Зелёный статус тогда — согласие теста с патчем, не с договором. Отсюда правило: критерии приёмки формулируют до кода; тесты трассируют к пунктам спеки; ревьюер имеет право спросить «какой пункт договора проверяет этот тест». Если ответа нет, тест — декорация. Подробнее о том, что человек обязан увидеть после патча агента, — в ревью кода в эпоху ИИ.

Слишком широкая спека. «Улучши оформление заказа», «наведи порядок в авторизации», «сделай как в современном облачном продукте». Для человека это тема разговора. Для агента — лицензия переписать модуль. Широкая спека порождает широкий патч, широкое ревью и архитектурный дрейф, который никто не выбирал явно. Лечение: одна спека — одно изменение поведения; нецели списком; ограничение по каталогам и публичным интерфейсам. Если нецели нельзя перечислить, спецификация ещё не готова, даже если текст длинный.

Рядом живут вторичные поломки. Спека-роман: двадцать страниц без инвариантов. Модель теряет приоритеты, человек не ревьюит. Лучше четыре экрана с таблицей переходов, чем глава «видение продукта». Двойной источник истины: вики, README и spec.md говорят разное; агент выберет удобное. Гнилая конституция: правила, которые никто не проверяет, модель научится игнорировать. Ревью не того артефакта: комментарии к форматированию при ошибочном критерии приёмки. Граница между генерацией и инженерией здесь та же, что в статье о конце генерации: красивый патч не равен принятому решению.

Ещё один тихий отказ — спека, написанная агентом без подписи человека. Черновик договора от модели полезен. Источник истины, который никто не читал, — это разработка по наитию с лишним файлом. Право подписи на намерение остаётся у человека, который несёт цену сбоя.

Практика для команды и для соло с агентом

Команда и соло-разработчик внедряют один метод с разной ценой координации. Ошибка — копировать корпоративный ритуал Spec Kit на вечерний пет-проект или, наоборот, вести промышленный сервис чатом без файла в git.

Для команды сначала договариваются, какой файл является договором на изменение. Конституция — коротко: стек, запреты, команды проверки, правило «нет спеки — нет агентного патча на поведение». Определение готовности задачи включает: цель и нецели, сценарии, ссылку на исполняемый контракт если меняется граница, команды, которыми агент докажет готовность. Запрос на слияние показывает спеку выше диффа кода: ревьюеры сначала принимают или отклоняют намерение, потом смотрят реализацию. Это снижает долг проверки, потому что спорить о «зачем» на тысяче строк поздно.

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

Для соло ритуал короче, но не нулевой. Перед агентом — двадцать минут на файл: цель, три сценария, два нецели, команда проверки. Файл лежит в ветке. После патча — пройтись по списку критериев и честно отметить, что не проверялось. AGENTS.md в личном репозитории может быть на полэкрана, если в нём есть фраза «не выдумывай приёмку, читай спецификацию». Это уже отделяет разработку по наитию от SDD. Когда фича оживает и выходит к пользователям, соло-разработчик сталкивается с той же ценой сбоя, что и команда: просто платит её один.

Практический минимум, который не зависит от бренда инструмента:

1. Один источник истины на изменение — файл в git, не чат.
2. Нецели записаны. Если их нет, спека слишком широкая.
3. Хотя бы часть критериев исполняема, если меняются деньги, доступ, API или состояния.
4. Тесты ссылаются на пункты договора или воспроизводят их буквально.
5. Поведение и договор мержатся вместе.
6. Человек подписывает намерение. Агент подписывает патч только как исполнитель.

Шаблоны Spec Kit и дельты OpenSpec помогают не забыть секции. Они не помогают, если секции заполнены водой. Пустая таблица инвариантов честнее вымышленного абзаца «система должна быть надёжной».

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

Дальнейшее чтение

Спецификация задаёт истину изменения; соседние тексты закрывают обвязку, механику среды и проверку:

• Агентная инженерия в 2026 — контекст, права, оркестрация и долг проверки вокруг агента, не договор фичи.
• Как Cursor и другие среды разработки работают с кодом — индекс, сборка контекста, режимы агента: как спека попадает в модель.
• Где заканчивается генерация кода и начинается инженерия — почему патч без принятого намерения ещё не продукт.
• Ревью кода в эпоху ИИ — что человек обязан проверить, когда дифф пишет агент.
• Экономика стоимости ошибок — какую часть спеки делать исполняемой, исходя из цены сбоя.
• Протокол контекста моделей в промышленной среде 2026 — как давать агенту инструменты к контрактам и спекам без теневого доступа.
• Новый цикл разработки: разработка по наитию и агентная инженерия — короткий культурный разбор той же развилки.

Заключение

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

SDD не отменяет тесты, не заменяет архитектуру и не делает Spec Kit обязательным брендом. Он запрещает начинать с кода, когда поведение ещё спорно, и запрещает считать работу законченной, пока договор не подтверждён. Обвязка агента, механика среды разработки и человеческое ревью остаются необходимыми — но они крутятся вокруг спеки, а не вокруг настроения последнего сеанса.

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