Между разработчиками, которые получают надёжный результат от Claude Code, и теми, кто тратит полдня на откат того, что агент только что построил, растёт разрыв. Разница не в таланте, опыте или каком-то секретном трюке prompt engineering. Это вопрос методологии. Разработчики, которые выпускают продакшн-софт с ИИ-агентами, сошлись на одном паттерне, как бы они его ни называли: определи, что тебе нужно, прежде чем агент начнёт писать код.
Эта статья даёт этому паттерну имя. Spec-first разработка — это методология для ИИ-ассистированной разработки ПО. Не расплывчатая «лучшая практика». Структурированный, воспроизводимый жизненный цикл с определёнными фазами, чёткими контрольными точками и конкретными артефактами на каждом шаге. Если вы искали способ сделать вывод Claude Code достаточно предсказуемым, чтобы можно было полагаться на него в графике релизов, — это тот фреймворк.
Потолок Vibe Coding
«Vibe coding» вошёл в лексикон в начале 2025 года. Идея: опишите, что хотите, на естественном языке, пусть ИИ напишет, итерируйте, пока не будет выглядеть правильно. Для прототипов, проектов выходного дня и одноразовых скриптов vibe coding работает. Быстро получаешь что-то функциональное, а если сломается потом — ставки невелики.
Продакшн-софт работает в других условиях. Код должен интегрироваться с существующей кодовой базой, удовлетворять конкретным требованиям и выдерживать контакт с другими людьми, которые будут его поддерживать. Когда vibe coding сталкивается с этими ограничениями, режимы отказа предсказуемы.
Первый отказ — дрейф. Вы описываете фичу расплывчато, агент реализует свою интерпретацию, вы корректируете, агент переделывает скорректированную интерпретацию. Три итерации спустя у вас есть рабочий код, который не удовлетворяет ни одному из ваших исходных требований, потому что каждая итерация сдвигала цель. Вы сходитесь к тому, что агент думает, что вы хотите, а не к тому, что вам действительно нужно.
Второй отказ — невидимые решения. Каждый пробел в вашем описании — это решение, которое агент принимает молча. Схема базы данных, стратегия обработки ошибок, форма API, правила валидации, выбор библиотек. Вы обнаруживаете эти решения на code review или, что хуже, в продакшне. Агент не принял плохих решений. Он принял неинструктированные решения, и у вас не было механизма их отловить до того, как они были вшиты в реализацию.
Третий отказ — паралич ревью. Diff на 600 строк, где агент выбрал архитектуру, модель данных, коды ошибок и обработку крайних случаев, — не ревьюируем в традиционном смысле. Вы не ревьюируете код против спеки. Вы реконструируете спеку из кода, а потом решаете, согласны ли вы. Это занимает больше времени, чем заняло бы написание спеки.
Vibe coding упирается в потолок, потому что смешивает две разные активности: решать, что строить, и строить это. Spec-first разработка их разделяет.
Spec-First как методология
Spec-first разработка — это четырёхфазный жизненный цикл. Каждая фаза производит конкретный артефакт. Каждый переход имеет чёткое условие прохождения. Методология работает с любым ИИ-агентом для кодирования, но примеры в этой статье используют Claude Code, потому что именно там сообщество итерирует быстрее всего.
Фаза 1: Мозговой штурм
Вы и агент (или только вы) исследуете пространство задачи. Какие ограничения? Какие подходы существуют? Каковы компромиссы? Это разговорный формат. Вы ни к чему не обязываетесь. Вы картографируете территорию.
Условие прохождения: у вас есть предпочтительный подход, и вы можете объяснить, почему именно он, а не альтернативы.
Мозговой штурм с Claude Code ценен, потому что агент обладает широкими знаниями о паттернах и библиотеках. Ошибка — прыгать от мозгового штурма прямо к коду. Мозговой штурм выявляет варианты. Он не выбирает между ними. Это делаете вы.
Фаза 2: Спека
Вы записываете решение. Это контракт, по которому агент будет реализовывать. Спека — это не user story, не тикет в Jira, не абзац прозы. Это структурированный документ с:
- Описание проблемы: что сломано или отсутствует, в конкретных терминах
- Предлагаемый подход: выбранное решение из фазы мозгового штурма
- Затрагиваемые файлы: какие файлы агент должен трогать (и неявно — какие не должен)
- Критерии приёмки: тестируемые условия, определяющие «готово»
- Вне скоупа: что агент должен явно избегать
Критерии приёмки — самый важный элемент. Каждый должен быть конкретным действием с наблюдаемым результатом. «Аутентификация должна работать» — не критерий. «Отправка валидных учётных данных возвращает 200 с токеном сессии; отправка невалидных возвращает 401 без токена» — критерий.
Секция «вне скоупа» предотвращает gold-plating. Без неё агенты будут «улучшать» соседний код, рефакторить файлы, которые показались им беспорядочными, или добавлять фичи, которые кажутся связанными. Каждая минута, которую агент тратит на незапрошенную работу, — это минута, которую вы тратите на ревью незапрошенной работы.
Условие прохождения: тот, кто не участвовал в мозговом штурме, мог бы прочитать эту спеку и построить правильную вещь.
Фаза 3: Реализация
Агент выполняет по спеке. Не по разговору. Не по памяти о том, что вы обсуждали. По конкретному документу с тестируемыми критериями.
Перед написанием кода агент создаёт план: нумерованный список изменений, которые он намерен сделать, какие файлы изменит и как проверит результат. Этот план — двухминутный чекпоинт. Вы читаете его, подтверждаете, что он соответствует вашему намерению, и даёте зелёный свет на реализацию. Или ловите недопонимание и исправляете его. В любом случае, вы потратили две минуты вместо двадцати.
Паттерн plan-before-code — не бюрократия. Это единственное вмешательство с наибольшим рычагом во всём воркфлоу. Большинство ошибок реализации — не ошибки кодирования. Это ошибки понимания: агент неправильно понял спеку. Поймать ошибку понимания в плане стоит две минуты. В diff-е на 400 строк — двадцать. В продакшне — день.
Условие прохождения: агент опубликовал отчёт о завершении с конкретными утверждениями о том, что было построено и как было проверено.
Фаза 4: Верификация
Вы или QA-процесс подтверждаете реализацию по спеке. Не «выглядит ли правильно?», а «удовлетворяет ли каждый критерий приёмки?»
Верификация механическая. Вы берёте каждый критерий из спеки, выполняете тест (запускаете команду, открываете браузер, триггерите событие) и записываете результат: прошёл или нет. Критерии, которые не прошли, возвращаются в Фазу 3. Верификация документируется вместе с реализацией, чтобы любой, кто прочитает задачу через шесть месяцев, мог увидеть, что именно было протестировано.
Условие прохождения: каждый критерий приёмки имеет записанный результат — прошёл/не прошёл.
Это полный жизненный цикл. Четыре фазы, четыре артефакта (обоснование подхода, спека, план реализации, запись верификации), четыре условия прохождения. Фазы последовательные, но лёгкие. Для фичи среднего размера фазы 1 и 2 занимают 15-20 минут. Фаза 3 занимает столько, сколько занимает реализация. Фаза 4 — 5-10 минут.
Почему с агентами это важнее, чем с людьми
Каждый аргумент за написание спек существовал до ИИ. «Пишите требования до кода» — это совет, который существует с тех пор, как большинство из нас ещё не родилось. Тогда зачем подавать это как что-то специфичное для ИИ-ассистированной разработки?
Потому что агенты меняют функцию стоимости.
Человек-разработчик, получивший расплывчатое требование, остановится и задаст вопросы. «Ты имел в виду аутентификацию по паролю или SSO?» «Это должно работать на мобильных?» «Что происходит, когда токен истекает?» Каждый вопрос — мини-чекпоинт, который толкает реализацию к правильной цели. Стоимость расплывчатой спеки с человеком-разработчиком — несколько тредов в Slack и, может быть, полдня переделки.
Агент, получивший расплывчатое требование, не остановится. Он примет каждое неоднозначное решение молча, зафиксирует подход и представит вам готовую реализацию. Стоимость расплывчатой спеки с агентом — готовая реализация, которая может быть полностью неправильной, плюс время на обнаружение того, что она неправильная, плюс время на переделку.
Асимметрия очевидна. Агенты быстрее в исполнении и хуже в суждении, чем люди-разработчики. Каждая неоднозначность в спеке — это суждение, и каждое суждение, которое агент делает без руководства, — подбрасывание монетки, совпадёт ли результат с вашим намерением. Спека устраняет подбрасывания монетки.
Есть вторая, более тонкая причина. Агенты не возражают. Старший инженер, получивший плохую спеку, скажет «это не имеет смысла из-за X». Агент верно реализует плохую спеку и произведёт верно ошибочный результат. Spec-first разработка заставляет вас протестировать собственное мышление до передачи его сущности, которая выполнит его без вопросов. Спека не только для агента. Она для вас.
Чекпоинт plan-before-code
Если вы возьмёте одну практику из этой статьи и проигнорируете остальное, возьмите эту.
Прежде чем агент напишет код, потребуйте, чтобы он опубликовал план реализации. Не код. Не diff. Структурированный план того, что он намерен сделать.
План выглядит так: нумерованные шаги в порядке выполнения, файлы для изменения, изменения логики в каждом файле и подход к верификации. Агент создаёт это примерно за тридцать секунд. Вы читаете примерно за две минуты. За эти две минуты вы можете поймать:
- Нарушения скоупа: агент планирует изменять файлы, не указанные в спеке
- Архитектурные несоответствия: агент выбрал подход, конфликтующий с существующими паттернами
- Пропущенные шаги: план не покрывает критерий приёмки
- Переусложнение: агент планирует строить абстракции, которые не оправданы
Двухминутный обзор плана заменяет двадцатиминутный обзор diff-а, где вы обнаруживаете эти проблемы после того, как они уже построены. Это самый дешёвый quality gate в разработке ПО.
Я написал подробное руководство по паттерну plan-before-code в Spec-driven разработка с Claude Code, включая шаблоны спек и форматы отчётов о завершении. Эта статья фокусируется на том, почему паттерн работает; та — на том, как его реализовать.
Верификация как полноценный шаг
Самая недоинвестированная фаза в воркфлоу большинства разработчиков — верификация. Агент говорит «готово». Разработчик бегло смотрит diff. Мерж происходит. Баг всплывает два дня спустя, когда пользователь натыкается на крайний случай номер три из критериев приёмки.
Spec-first разработка рассматривает верификацию как формальный шаг с собственными артефактами. Отчёт о завершении сопоставляет каждый критерий приёмки с конкретной проверкой:
- Критерий: «Переключение workspace восстанавливает сохранённое состояние фильтров.»
- Проверка: Открыть приложение, установить фильтры в workspace A, переключиться на workspace B, вернуться в workspace A, убедиться, что фильтры восстановлены.
- Результат: Пройдено.
Это не накладные расходы. Это шаг, который определяет, действительно ли реализация удовлетворяет спеке. Без него спека — список желаний, а критерии приёмки — устремления.
Запись верификации также решает нижестоящую проблему: code review. Когда ревьюер открывает pull request, он читает спеку, запись верификации и ревьюирует diff с полным контекстом. Время ревью сокращается, потому что ревьюер подтверждает верифицированное утверждение, а не проводит расследование.
Когда вы запускаете несколько агентов параллельно, каждый реализует свою спеку, дисциплина верификации — это разница между контролируемым пайплайном и кучей кода, который «наверное, работает». У каждой спеки есть критерии. У каждой реализации есть отчёт о завершении. Каждый отчёт сопоставляет критерии с проверками. Ничто не выпускается без записанной верификации.
Возражения и честные компромиссы
Spec-first разработка не бесплатна. Возражения реальны и заслуживают прямого ответа.
«Написание спек замедляет меня.» Изолированно — да. Написание спеки для фичи занимает 15-20 минут. Но вы возвращаете это время (и больше) на фазах реализации и ревью. Агент с чёткой спекой чаще производит правильную реализацию, чем агент с расплывчатым промптом. Меньше итераций, меньше переделки, короче ревью. Суммарный эффект для фич любой сложности — более быстрая поставка, не более медленная.
Для тривиальных изменений (переименовать переменную, исправить опечатку, поднять версию) спеки — ненужные накладные расходы. Spec-first — для работы, где реализация требует решений. Если изменение механическое и однозначное, пропустите спеку.
«Мой агент достаточно хорош без спек.» Для некоторых задач — вероятно, да. Claude Code замечательно способен выводить намерение из кратких описаний. Вопрос не в том, может ли агент произвести хороший результат из расплывчатых инструкций. А в том, делает ли он это надёжно. Если вас устраивает случайная переделка и непредсказуемое время ревью, vibe coding может быть достаточен для вашего случая. Spec-first окупается, когда важны консистентность и предсказуемость: когда фича сложная, когда код идёт в продакшн, когда кто-то другой будет его поддерживать.
«Спеки устаревают.» Обоснованное беспокойство. Спека, написанная во время мозгового штурма, может не пережить контакт с реальностью. Решение — не пропускать спеки. А обновлять спеку, когда план выявляет новую информацию. Если план агента показывает, что подход в спеке не сработает, пересмотрите спеку перед продолжением. Спека — живой документ на время реализации. Она становится историческим документом после верификации.
«Это просто водопад.» Нет. Провал водопада — большие спеки для больших проектов с длинными циклами обратной связи. Spec-first разработка работает на уровне задач: одна спека на фичу или фикс, написанная за 15-20 минут, реализованная за часы, верифицированная в тот же день. Петля обратной связи короткая. Инвестиция на спеку маленькая. Если спека неправильная, вы узнаёте это во время обзора плана, а не через шесть месяцев.
Инструменты для жизненного цикла Spec-First
Методология работает с любой системой задач: GitHub Issues, Linear, Notion, простые текстовые файлы. Важно, чтобы спека, план, заметки о реализации и результаты верификации жили в одном месте, привязанные к одной задаче.
Если вы ищете систему, спроектированную для этого воркфлоу, beads — это open-source, Git-нативный трекер задач, который содержит полный жизненный цикл. Каждый «bead» несёт описание (вашу спеку), тред комментариев (планы и отчёты о завершении), статус (open, in_progress, ready_for_qa, done) и метаданные — зависимости и приоритеты. CLI bd работает из терминала, что означает — агенты могут читать спеки, публиковать планы и докладывать о завершении, не покидая рабочую среду.
bd create --title "Persist filter state across workspaces" \
--description "## Problem ..." --type feature --priority p2
bd update bb-a1b2 --claim --actor eng1
bd comments add bb-a1b2 --author eng1 "PLAN: ..."
# After implementation:
bd comments add bb-a1b2 --author eng1 "DONE: ... Commit: a1b2c3d"
bd update bb-a1b2 --status ready_for_qa
Весь жизненный цикл происходит в CLI. Через шесть месяцев bd show bb-a1b2 возвращает полную историю того, что было специфицировано, спланировано, построено и верифицировано.
Когда вы ведёте одного агента через этот жизненный цикл, CLI достаточно. Когда пять или десять работают параллельно, каждый на своей стадии пайплайна spec-implement-verify, вам нужно видеть состояние пайплайна с одного взгляда. Beadbox — это дашборд реального времени, который показывает, какие спеки открыты, у каких есть планы, ожидающие ревью, что в работе, что заблокировано и что готово к верификации. Он мониторит ту же базу данных beads, в которую пишут агенты, обновляясь в реальном времени при изменении статусов.
Вам не нужен Beadbox, чтобы практиковать spec-first разработку. Методология инструмент-агностична. Но когда параллельные потоки работы превращают ваш пайплайн в очередь задач, которую невозможно отслеживать по памяти, визуальный слой меняет скорость, с которой вы можете ревьюировать, разблокировать и выпускать.
Более широкий сдвиг
Spec-first разработка — не реакция на то, что ИИ-агенты для кодирования плохи. Это признание того, что без руководства они хороши не в том. Агенты — чрезвычайно способные исполнители. Они пишут корректный синтаксис, следуют паттернам, обрабатывают шаблонный код и производят объём, который ни один человек не может сравнить. Чего им не хватает — контекста для принятия хороших решений о том, что строить. Этот контекст приходит от вас, и спека — это средство доставки.
Разработчики, которые будут процветать в ИИ-ассистированной инженерии, — не те, кто пишет лучшие промпты. Это те, кто пишет лучшие спеки. Промпты эфемерны. Спеки долговечны. Промпты оптимизируют для одного взаимодействия. Спеки оптимизируют для жизненного цикла: мозговой штурм, определение, реализация, верификация.
Это не временный обходной путь, пока агенты не станут умнее. Даже с улучшением моделей фундаментальная асимметрия остаётся: человек знает, что нужно бизнесу; агент знает, как писать код. Спека связывает их. Лучшие модели будут выполнять спеки быстрее, но потребность в самой спеке не исчезнет. Она становится важнее с масштабированием, потому что больше агентов, работающих по расплывчатым инструкциям, производят более расходящийся результат.
Если вы запускали агентов Claude Code и находили результаты непоследовательными, или тратили слишком много времени на ревью, или боролись с координацией параллельных потоков работы, попробуйте это: перед следующей фичей потратьте 15 минут на написание спеки с тестируемыми критериями приёмки, потребуйте от агента опубликовать план перед написанием кода и проверьте результат по каждому критерию. Один цикл покажет вам разницу.
Если вы строите такие воркфлоу, поставьте звезду Beadbox на GitHub.
