Spec-driven development

Когда код пишет агент, самым ценным артефактом становится не код, а описание того, что он должен делать. Отсюда интерес к spec-driven development (SDD) — разработке от спецификации. Вокруг термина много шума и несколько тяжёлых инструментов. В уроке разберёмся, что в SDD работает, что нет, и как встроить спецификации в harness без бюрократии.

Спецификация, план, постоянный контекст

Биргитта Бёкелер в статье «Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl» (октябрь 2025) разводит два понятия:

• Спецификация (spec) — структурированное описание поведения на естественном языке. Относится только к задачам, которые создают или меняют конкретную функциональность.
• Постоянный контекст (memory bank) — общие знания о кодовой базе: файлы правил, описание продукта и архитектуры. Действует во всех сессиях.

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

Три уровня SDD

Бёкелер выделяет три уровня:

Любой SDD начинается как spec-first, но не каждый стремится дальше. Из разобранных инструментов Kiro и spec-kit, по оценке автора, — в основном spec-first, а Tessl явно целится в spec-anchored и экспериментирует со spec-as-source. При повторной генерации из одной спецификации Tessl давал разный код.

Что не так с тяжёлым SDD

Критика из той же статьи полезна любому, кто внедряет процессы:

• Один процесс на все размеры. Мелкий баг в Kiro превратился в четыре пользовательские истории с шестнадцатью критериями приёмки, а spec-kit для небольшой фичи оказался избыточным.
• Ревью markdown. Многочисленные однообразные файлы спецификаций утомительнее ревьюить, чем код.
• Ложное чувство контроля. Агенты всё равно иногда игнорировали инструкции — например, дублировали классы, которые шаг исследования уже описал.
• Параллели с MDD. Спецификации напоминают модели из model-driven development с их накладными расходами и негибкостью, а LLM добавляют недетерминированность.

Отдельно Бёкелер предупреждает, что термин уже размыт и иногда означает просто «подробный промпт».

Что работает: два примера

Symphony. В статье OpenAI о Symphony (апрель 2026) продукт по сути и есть SPEC.md — спецификация оркестратора. Эталонную реализацию на Elixir Codex написал с одной попытки. А чтобы найти неоднозначности в самой спецификации, её реализовали ещё на TypeScript, Go, Rust, Java и Python. Рабочий процесс команды, раньше нигде не записанный, теперь лежит в WORKFLOW.md. Это использование агентов как теста спецификации: расхождения между реализациями показывают места, где текст допускает разные прочтения.

Sprint contracts. Anthropic в материале о harness для длинной разработки (март 2026) описывает «контракты спринта»: до начала работы генератор и оценщик договариваются, что значит «готово» и как это проверить. С более новой моделью конструкцию упростили и оценщик стал запускаться один раз в конце. Урок тот же, что и везде в курсе: форма процесса зависит от модели, а определение «готово» до начала работы остаётся полезным.

Наш вариант: лёгкий spec-anchored

Наша рекомендация для агентства — спецификации уровня spec-anchored, но лёгкие и встроенные в репозиторий:

1. Спецификация лежит рядом с кодом — в docs/product-specs/<фича>.md, а не в трекере или документе у аналитика.
2. Поведение — сценариями с наблюдаемым результатом. Каждый сценарий приёмки становится автоматической проверкой: юнит-тестом, e2e на Playwright, проверкой на стенде.
3. Изменение поведения — сначала в спецификации, в том же MR, что и код. Ревьюер видит дифф спецификации и дифф кода рядом.
4. Размер спецификации растёт с размером задачи. Для бага — три строки в задаче. Для фичи — страница. Для новой интеграции — отдельный файл со сценариями ошибок.

Структура опирается на четыре части промпта из best practices Codex — цель, контекст, ограничения, критерий готовности — и добавляет сценарии:

---
status: active
owner: analyst
verified: 2026-10-22
---

# Форма «Обсудить проект»

## Цель
Заявка с сайта попадает в CRM без ручного переноса.

## Вне рамок
Редизайн формы, антиспам (отдельная задача).

## Сценарии
1. Дано: CRM доступна. Когда: пользователь отправляет форму с валидными данными.
   Тогда: видит «Спасибо», в CRM карточка с source=site и UTM-метками.
2. Дано: CRM недоступна. Когда: форма отправлена.
   Тогда: пользователь видит «Спасибо», заявка доставляется после восстановления CRM.
3. Дано: телефон уже есть в CRM. Тогда: новая карточка не создаётся, к существующей
   добавляется комментарий.

## Ограничения
- Ответ формы не дольше 1 с независимо от CRM.
- Персональные данные не пишутся в логи.

## Проверка
- Сценарии 1–3 — e2e в tests/e2e/lead-form.spec.ts против тестовой воронки.

## Открытые вопросы
- Что делать с заявками без телефона? (ждём ответа клиента)

Раздел «Открытые вопросы» важнее, чем кажется. Агент склонен молча закрывать неоднозначность своим предположением. Явный список вопросов — способ вынести эти предположения на свет до кода, а не после.

Поиск неоднозначностей

Приём Symphony — несколько реализаций ради поиска расхождений — в полном виде дорог. Дешёвые версии:

• попросить агента до реализации выписать все места, где спецификация допускает разные прочтения;
• запустить двух агентов в отдельных worktree на одну спецификацию и сравнить, где их решения разошлись (про worktree — урок «Несколько задач параллельно»);
• попросить агента написать по спецификации только тесты приёмки, без кода, и показать их аналитику.

Насколько можно доверять тестам, которые агент написал по спецификации, — открытый вопрос, которому посвящён урок о проверке поведения.

Кто пишет спецификации

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

Прочитай docs/product-specs/<фича>.md. Не пиши код.
Выпиши все места, где спецификацию можно понять двумя способами,
и для каждого — два варианта реализации и чем они отличаются для пользователя.