Разработка на основе спецификации с Claude Code: пошаговый туториал

Что такое разработка на основе спецификации?

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

Три точки контроля, через которые проходит фича при разработке на основе спецификации.

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

• Поддерживаемые форматы файлов
• Способ доставки
• Поведение при незавершённом экспорте
• Части фичи, которые намеренно исключены

Ниже — реальное начало спецификации, которую Claude Code написал для изменения workout-shape-verification в моём Telegram-приложении для учёта тренировок. Изменение заменяет хрупкий порог ЧСС проверкой формы кривой ЧСС во времени:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

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

Код идёт последним и пишется по плану, задача за задачей.

Три документа. Между каждой парой — ручная проверка. Вы проверяете спецификацию перед тем, как она станет планом. Проверяете план перед написанием кода. Проверяете код перед мержем.

Чем разработка на основе спецификации отличается от план-режима

Возможно, вы использовали встроенный план-режим Claude Code (нажмите Shift+Tab дважды) и задумались, чем это отличается. План-режим создаёт план в одном ходе чата. План живёт в памяти, без сохранённой спецификации и без шага ревью между фазами.

Разработка на основе спецификации сохраняет и спецификацию, и план как файлы на диске. Каждый проходит ручную проверку перед началом следующей фазы, и артефакты переживают отдельные сессии. План-режим сжимает две фазы разработки в один ход чата. Это работает для мелких задач и ломается, как только кодовая база растёт и обслуживает реальных пользователей.

Почему вайб-кодинг упирается в стену

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

Причина сбоев очевидна. Расплывчатый промпт вроде «добавь фотошеринг в моё приложение» заставляет модель угадывать тысячи неявных требований.

Возьмём одно из таких требований: настройки уведомлений. Продакт-менеджер предполагает тумблеры по каналам. Бэкенд делает общий выключатель. Фронтенд рассчитывает на интеграцию с ОС. Четыре разумных прочтения трёх слов — четыре разных продукта.

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

Выигрыш реален и накапливается постепенно. Фаза спецификации стоит часов письма до запуска кода, и первые несколько фич кажутся медленнее вайб-кодинга. У меня точка безубыточности наступила на четвёртой или пятой фиче. К тому моменту спецификации начали ловить проектные ошибки, которые иначе я бы отправил в прод и переписал через неделю.

В следующих трёх разделах — три опенсорсных подхода, которые запускают этот процесс внутри Claude Code. Они расположены от наименее до наиболее строгого по навязываемой структуре.

Superpowers

Superpowers — самый «лёгкий» из трёх. Это мой повседневный выбор, и его мы разберём подробнее всего.

Что такое Superpowers?

Superpowers — это плагин для Claude Code от Jesse Vincent (obra/superpowers, лицензия MIT), с примерно 194 тыс. звёзд на GitHub. 

Он поставляется набором skills. Навык Claude в Claude Code — это именованный файл инструкций, который агент загружает по запросу для следования конкретному рабочему процессу. Superpowers поставляет навыки, которые удерживают Claude Code в петле разработки по спецификации, а не позволяют ему сразу прыгать к коду.

Страница проекта Superpowers на GitHub.

Как установить Superpowers

Установите его через официальный маркетплейс плагинов Claude Code:

/plugin install superpowers@claude-plugins-official

Хук SessionStart автоматически загружает навык using-superpowers, поэтому рабочий процесс активен с того момента, как вы начинаете печатать. (Хуки Claude Code — это скрипты, которые агент запускает в определённой точке жизненного цикла.) Ничего настраивать под проект не нужно.

Рабочий процесс Superpowers

Дальше четыре навыка управляют вашей повседневной работой:

Подагент — это отдельный экземпляр Claude Code, который родитель запускает для фокусной работы в собственном контекстном окне. Ревьюеры из таблицы выше работают как подагенты, поэтому они читают код «с нуля», без фрейминга родителя.

Как пользоваться Superpowers

Вы вызываете четыре навыка, описывая желаемое простым языком. Навык brainstorming реагирует на «давайте обсудим новую фичу» и сам запускает разговор о спецификации. Остальные срабатывают аналогично.

Четыре навыка Superpowers по порядку, с двумя точками ручного ревью между brainstorming и writing-plans.

Ниже — пошаговый разбор на примере фичи workout-shape-verification из отрывка спецификации выше.

Этап 1: от брейнсторма к спецификации

Я открываю Claude Code и пишу:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

Навык brainstorming перехватывает и задаёт десяток вопросов, среди них:

• Что считать правильной «формой»
• Какие потоки данных объединять
• Что делать с сессиями, которые по форме подходят, но не проходят старый порог
• Распространяется ли изменение на Run и Ride

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

Этап 2: от спецификации к плану

Я запускаю навык writing-plans. Он читает утверждённую спецификацию и пишет файл плана с четырьмя частями:

• Определение «Готово»
• Карта файлов с перечнем затронутых файлов
• Пользовательское путешествие по демо-сценарию
• Пронумерованный список задач с чекбокс-подзадачами. 

Я просматриваю план, указываю на задачи, которые выглядят не в том порядке или слишком крупными, и утверждаю.

Этап 3: от плана к коду

Я запускаю subagent-driven-development. С этого момента цикл идёт без меня. Для каждой задачи из плана навык:

1. Пишет падающий тест
2. Пишет код, чтобы его пройти
3. Рефакторит
4. Запускает подагента код-ревью, который читает дифф «вслепую»

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

Этап 4: ревью полного диффа

Когда план выполнен, я запускаю requesting-code-review. Свежий подагент читает весь дифф относительно спецификации и плана и оставляет ревью. Я принимаю предложения перед мержем.

Если задача из плана выявляет противоречие со спецификацией, цикл останавливается и спрашивает. Я могу отредактировать спецификацию (или поручить это Claude) и сгенерировать заново затронутые задачи. Есть и другой вариант — разовая правка в самой задаче. Superpowers не обходит молча ошибки в спецификации.

Реальные спецификации и планы на диске

Вот спецификация для фичи workout-shape-verification, открытая в редакторе:

Файл спецификации после записи его на диск навыком brainstorming.

Шапка содержит поля Created, Status и Supersedes, которые навык brainstorming пишет по умолчанию. Затем идёт раздел Problem. Это не код. Дальше файл продолжается разделами с предложенным решением и ограничениями на то, что изменение должно и не должно затрагивать.

Соответствующий план открывается разделом User Journey:

Файл плана, который навык writing-plans генерирует из утверждённой спецификации.

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

Два документа соотносятся так:

Спецификация и план рядом. Спецификация отвечает, что и почему меняется. План отвечает, в каких шагах.

Для крупных спецификаций и планов я добавляю шаг, которого нет в официальной петле: red-team-проверку. Перед финальным утверждением один или несколько подагентов Opus читают спецификацию «с нуля», ищут дыры под разными углами. Это моя привычка, а не функция Superpowers. Она не раз ловила неверные предположения — поэтому я её сохраняю.

Когда Superpowers — не тот выбор

Superpowers подходит для сольной работы в одном репозитории. Лучше всего он работает, когда весь код помещается в одну сессию Claude Code и вы действительно прочтёте 2‑страничную спецификацию. Детальное сравнение — в разделе Как выбирать между ними ниже. Коротко: Superpowers тяжело даётся для фич в нескольких репозиториях и задач с чётким разделением ролей.

Один разработчик отметил четвёртый режим сбоя в публичной жалобе на плагин: «Даже самая мелкая задача длится вечность: Claude поднимает подагентов и пишет совершенно избыточные планы. Исправление CSS теперь занимает вечность».

Решение — пропускать Superpowers для крошечных правок. Навыки активируются только по триггеру брейнсторма. Однострочное изменение CSS может пройти через Claude Code, так ни разу не задействовав цикл спецификации. Реальный сбой здесь — чрезмерное применение рабочего процесса там, где спецификация не нужна.

GitHub Spec Kit

Spec Kit — выбор, когда спецификация должна пережить любую отдельную сессию Claude Code. Это также правильный вариант, когда спецификацию должны читать люди, которые никогда не открывают Claude Code.

Что такое GitHub spec-kit?

Spec Kit — это проект GitHub (github/spec-kit, лицензия MIT), поддерживаемый самим GitHub, с более чем 100 тыс. звёзд. Он поставляет CLI и рабочий процесс, который одинаково запускается у всех крупных AI-агентов для кода. Поддерживаются Claude Code, Cursor, Aider, Cline и Roo Code. Агент-независимый дизайн позволяет спецификации жить вне Claude Code.

Страница проекта Spec Kit на GitHub.

Как установить GitHub spec-kit

Официального пакета в PyPI пока нет, поэтому установите CLI с Git-тега с помощью uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Замените vX.Y.Z на актуальный релизный тег. Пакет — specify-cli, а регистрируемая команда — specify.

Рабочий процесс GitHub spec-kit

Процесс строится на девяти slash-командах, которые CLI добавляет в список команд вашего агента. Шесть — ядро цикла, три — опциональные для случаев за пределами ядра.

Разделитель между группой команд и глаголом — точка, не двоеточие: /speckit.specify, а не /speckit:specify. 

Девять slash-команд Spec Kit: шесть основных на конвейере и три опциональные рядом.

Артефакты, которые создают эти команды, — та же спецификация и план из раздела про Superpowers, также пишутся на диск и отслеживаются Git. Разница — в переносимости: артефакты Spec Kit рассчитаны на работу с любым AI-агентом для кода, а рабочий процесс ориентирован на ревью заинтересованных сторон через пул-реквесты GitHub, а не как побочный продукт цикла одного инструмента.

Когда использовать GitHub spec-kit

В одиночном проекте Spec Kit, скорее всего, не нужен. Обращайтесь к нему, когда:

• Проект вырос больше одного человека
• Спецификацию должны ревьюить люди, которые не открывают Claude Code
• Часть работ выполняется агентом, отличным от Claude Code
• Нужен формат спецификации, живущий вне конкретного инструмента и читаемый через месяцы

Метод BMAD

Если Spec Kit организует артефакты, то BMAD организует людей. Он делит путь от спецификации к коду на четыре фазы, каждую ведёт агент определённой роли.

Что такое BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, лицензия MIT, около 47 тыс. звёзд) сейчас в версии 6. Аббревиатура в документации проекта расшифровывается как «Breakthrough Method for Agile AI-Driven Development». Он работает поверх Claude Code и других агентов и устанавливается как экосистема модулей. По умолчанию вы получаете базовый модуль с шестью агентами-ролями, четырьмя фазами и 34+ именованными рабочими процессами.

Страница проекта BMAD-METHOD на GitHub.

Как установить BMAD

Установите BMAD с помощью Node:

npx bmad-method install

Шесть агентов-ролей — это персоны подсказок, которые пользователь активирует по имени внутри хоста агента. В Claude Code это означает ввод команды активации, устанавливаемой BMAD. Синтаксис смотрите в README — он меняется между релизами. 

Агенты-сотрудники BMAD и артефакты

После активации агент принимает инструкции, голос и выходные данные этой роли, пока вы не переключите персону. Шесть ролей:

• Mary, аналитик
• Paige, технический писатель
• John, продакт-менеджер
• Sally, UX-дизайнер
• Winston, архитектор
• Amelia, разработчик

Двух ожидаемых ролей в v6 нет: нет агента скрам-мастера и отдельного QA-агента. Планирование спринта и подготовка историй лежат на агенте-разработчике, а генерация QA-тестов — это workflow, который запускает разработчик.

Набор артефактов тяжелее, чем одна спецификация. Вы получаете:

• краткое описание продукта (product brief)
• PRD (Product Requirements Document)
• UX-спецификацию
• архитектурный документ
• эпики, разбитые на пользовательские истории (что сможет делать пользователь после релиза)

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

Рабочий процесс BMAD

Процесс v6 идёт в четыре фазы.

Четыре фазы BMAD и агент роли на каждой. Трек Quick Flow пропускает первые три для небольших задач.

Фаза 1, анализ, опциональна. Mary (аналитик) и Paige (технический писатель) проводят исследование и готовят product brief. Пропустите фазу, если вы уже понимаете, что строите.

Фаза 2, планирование, обязательна. John (PM) пишет PRD. Sally (UX-дизайнер) добавляет UX-спецификацию, если у фичи есть интерфейс.

Фаза 3, проработка решения (solutioning), — зона Winston. Архитектор сначала формирует архитектуру, затем John дробит требования на эпики и истории. Размещение историй после архитектуры — особенность v6, чтобы соотнести их с реальными границами реализации. Затем Winston проводит проверку готовности к реализации с вердиктом PASS, CONCERNS или FAIL.

Фаза 4, реализация — Amelia (разработчик) работает история за историей: создать историю, реализовать её и провести код-ревью. После завершения эпика она запускает workflow генерации QA-тестов по всему эпику. Здесь Claude Code пишет собственно код, действуя как Amelia.

Для небольшой, чётко очерченной работы BMAD предлагает трек «Quick Flow», который активирует Amelia напрямую и пропускает первые три фазы. Команда активации — в README BMAD (синтаксис меняется между релизами). Quick Flow не создаёт PRD и архитектуру — только короткую историю и код, закрывающий её. Это ответ на возражение «это избыточно для правки кнопки».

Если спецификация оказывается неверной в процессе реализации, BMAD возвращается к вердикту фазы 3 от Winston. FAIL отправляет назад к фазе 2 переписывать PRD. CONCERNS позволяет продолжить с отмеченными рисками. Такой разбор позволяет двигаться при мелких несоответствиях и останавливать работу при крупных.

Когда сложность окупается

BMAD окупается на длинных проектах с реальными пользователями. Он также подходит для команды из нескольких разработчиков с передачей задач между людьми. Разделение на фазы и роли должно экономить больше времени, чем стоит.

Для одиночного сайд-проекта это не лучший выбор. В сольной работе разделение на четыре фазы и шесть агентов — в основном оверхед. Нет второго человека в команде, чтобы разделение ролей имело значение.

Как выбрать между фреймворками

Три правила определяют выбор.

• Используйте Spec Kit, если спецификацию должны читать люди, не открывающие Claude Code, или если она должна жить в Git как долговечный артефакт.
• Если несколько людей работают в разных ролях или есть реальный PM-стейкхолдер, используйте BMAD.
• В остальных случаях используйте Superpowers.

Три вопроса о вашем проекте — четыре варианта фреймворка на выходе.

Есть и четвёртый вариант, который показывает дерево решений: объединить Spec Kit и Superpowers. Используйте Spec Kit на этапе спецификации, чтобы артефакты жили в Git для кросс-командного ревью. Затем направьте навык subagent-driven-development из Superpowers на файл плана Spec Kit одной строкой конфигурации. Вы получите долговечную спецификацию из Spec Kit и плотный цикл реализации из Superpowers.

Заключение

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

Пройдите дерево решений выше, чтобы выбрать фреймворк — для большинства читателей это будет Superpowers. Установите его и возьмите одну фичу, которую вы бы иначе делали вайб-кодингом, — ту, что затрагивает 3–5 файлов. Пропустите её от начала до конца: брейншторм, спецификация, план, реализация. Один реальный прогон учит процессу лучше любого описания.

Если вы хотите освежить базовые знания Claude Code, у DataCamp есть практический туториал по Claude Code, гид по лучшим практикам с план-режимом, CLAUDE.md и TDD и углублённый разбор самого план-режима.