Поток spec-kit: /specify → /plan → /implement

Когда разработчики впервые слышат про spec-kit, они ждут чего-то сложного — отдельный инструмент, DSL, конфигурация. На деле это пять слэш-команд в Claude Code, выстроенных в конвейер: идея входит на одном конце, работающий PR выходит на другом. Разберём, как этот поток устроен и почему такой порядок не случаен.

Почему порядок команд важен

Каждый шаг spec-kit отвечает за один вид работы и намеренно не лезет в следующий.

• /specify — формализует идею в требования: что и зачем. Никакого «как».
• /clarify — закрывает все неоднозначности до того, как агент пойдёт писать код.
• /plan — переводит «что» в «как»: стек, модель данных, API, Constitution Check.
• /tasks — режет план на атомарные задачи с привязкой к требованиям.
• /implement — пишет код по задачам, отмечает прогресс.

Смешать порядок — потерять главную ценность: спека защищает от галлюцинаций, план защищает от архитектурных сюрпризов, задачи дают прослеживаемость. Если прыгнуть сразу в /implement с идеей в голове, вы получите vibe-coding с дорогостоящими откатами.

Подробнее о разнице подходов — в статье spec-driven development vs vibe-coding.

Шаг 1. /specify — структура без выдумки

Запускаете /speckit.specify и передаёте идею свободным текстом. Команда возвращает spec.md со структурой: user stories, функциональные требования (FR), критерии успеха (SC), edge cases, ключевые сущности.

На примере CoffeeCRM — сквозного проекта курса (Next.js + NestJS + PostgreSQL). Идея: программа лояльности, клиенты копят бонусные баллы за заказы.

/speckit.specify Программа лояльности для CoffeeCRM. Клиент (сущность Client из
модуля 4) копит бонусные баллы за заказы и может тратить их на оплату следующих
заказов. Нужно показывать баланс баллов в карточке клиента. Бонусы — часть
существующего Client, новую сущность не вводим.

Важно: в описании — поведение и ценность, не схема БД. «Новую сущность не вводим» — это осознанное ограничение, которое вы задаёте сами.

Самое ценное, что делает /specify, — он не выдумывает то, чего вы не сказали. Вместо тихой галлюцинации он ставит маркер [NEEDS CLARIFICATION: <вопрос>]. Это честный «я тут не знаю».

После первого прогона в спеке лояльности появятся такие теги:

- FR-002: Система начисляет бонусные баллы за заказ [NEEDS CLARIFICATION:
  процент от суммы? фиксировано? округление?]
- FR-004: Клиент списывает баллы при оплате [NEEDS CLARIFICATION: можно ли
  частичную оплату баллами? допустим ли отрицательный баланс?]
- FR-005: [NEEDS CLARIFICATION: сгорают ли баллы со временем?]

Это не ошибка — это карта мест, где агент иначе бы угадал (и угадал бы неправильно).

Шаг 2. /clarify — ноль открытых вопросов

Писать код по спеке с открытыми [NEEDS CLARIFICATION] — рано. Код по неоднозначной спеке — прямой путь обратно к vibe-coding: проблемы всплывут в проде, не в ревью.

/speckit.clarify ведёт интерактивный диалог: задаёт по одному вопросу из открытых неясностей, вы отвечаете — он вписывает решение в спеку и снимает тег.

/speckit.clarify

Критерий готовности: ноль [NEEDS CLARIFICATION] в spec.md. Не «почти ноль» — ноль.

Ответы должны быть конкретными и проверяемыми. «Нормально начислять» — плохо. «5% от суммы заказа, округление вниз до целого балла» — хорошо. Каждое такое решение вы принимаете текстом за пять минут — вместо того чтобы поймать его как баг через неделю.

Когда /clarify закончил, проверьте: каждое FR в спеке должно быть проверяемо. Можно написать тест «да/нет». Описано поведение и ценность, без деталей реализации. Два инженера прочитают и реализуют одинаково.

Шаг 3. /plan — «как» и Constitution Check

Однозначная спека готова. Теперь /speckit.plan переводит «что» в «как».

/speckit.plan

Здесь — и только здесь — появляются технические детали: колонка bonus_points в таблице clients, сервис LoyaltyService с методами accrue() и redeem(), эндпоинты NestJS, компонент Next.js. На уровне спеки их быть не должно было.

Главный гейт шага — Constitution Check. В plan.md это таблица «принцип → как соблюдается → статус ✅/❌». Если ❌ — либо чинить план, либо письменно обосновать отступление. Для фичи лояльности в CoffeeCRM это выглядит так:

Принцип конституции	Как соблюдается	Статус
Единый сквозной проект	Расширяет Client из предыдущего модуля, не плодит сущности	✅ PASS
Прогрессивная сложность	Поле bonusPoints заложено в data-model для этого модуля	✅ PASS
Низкий порог входа	Postgres локально/Docker, без платных API	✅ PASS

Если бы план потянул платный внешний сервис для начисления бонусов — был бы ❌, и вы увидите это до единой строчки кода. Вот зачем нужна конституция.

Шаг 4. /tasks — прослеживаемость от требования до задачи

/speckit.tasks режет план на атомарные задачи по фазам (Setup → Foundational → по user stories → Polish).

/speckit.tasks

Каждая задача привязана к требованию (FR/SC) и помечена зависимостями. [P] означает, что задачу можно выполнить параллельно — это важно, если вы работаете с несколькими агентами одновременно.

## Phase 3: User Story — Начисление бонусов
- [ ] [US] Миграция: добавить bonus_points в clients (FR-002)
- [ ] [US] LoyaltyService.accrue(): 5% от суммы completed-заказа (FR-002)
- [ ] [P] [US] Юнит-тест округления баллов вниз (FR-002)
## Phase 4: User Story — Списание бонусов
- [ ] [US] LoyaltyService.redeem(): запрет отрицательного баланса (FR-004)
- [ ] [US] Эндпоинт POST /clients/:id/redeem (FR-004)
- [ ] [P] [US] UI: баланс баллов в карточке клиента (FR-003)

Ни одной задачи «из воздуха», ни одного требования без задачи.

Перед запуском /implement есть опциональный, но полезный шаг: /speckit.analyze сверяет согласованность spec↔plan↔tasks — нет ли требований без задач, противоречий между артефактами. Дёшево поймать рассинхрон здесь, а не в середине реализации.

Шаг 5. /implement — код по задачам, дыра → назад к спеке

/speckit.implement

Агент идёт по tasks.md сверху вниз, уважает зависимости, пишет код, отмечает сделанное. Вы — в роли ревьюера: смотрите diff, гоняете тесты.

Главный учебный момент этого шага: если /implement упирается в пробел, которого нет в спеке, — правильная реакция не «ай, пусть сам решит», а остановиться.

Например: агент дошёл до отмены заказа и не знает, откатывать ли начисленные баллы — в спеке этого нет. Возвращаетесь к spec.md, добавляете правило («при отмене completed-заказа начисленные за него баллы списываются»), при необходимости прогоняете /clarify, и только потом продолжаете. Дыру закрываете в контракте, а не в коде наспех.

Когда тесты зелёные, оформляете PR со ссылками на spec.md, plan.md, tasks.md:

git commit -m "feat(loyalty): начисление и списание бонусов клиента"
git push -u origin module-5
gh pr create --fill

Ревьюер открывает PR и видит не только код, но и почему он такой.

Когда spec-kit нужен, а когда нет

Spec-kit — не религия. Применять его ко всему — карго-культ и потеря времени.

Берите spec-kit, если: фича средняя или крупная, затрагивает данные или деньги, несколько продуктовых решений ещё не приняты, код останется надолго или с ним будет работать команда.

Оставляйте vibe-coding, если: мелкая правка (поменять цвет кнопки, текст лейбла), прототип на выброс, всё очевидно, цена ошибки нулевая.

Три конкретных кейса из практики курса:

1. «Поменять цвет кнопки и текст лейбла» — vibe-coding. Спека была бы бюрократией.
2. «Программа лояльности с начислением/списанием бонусов» — spec-driven. Данные, деньги, куча неизвестных, фича на годы.
3. «Накидать за вечер демку графика выручки для заказчика, скорее всего на выброс» — vibe-coding. Скорость важнее контракта. Если решат довести до прода — тогда переписываем через spec-driven.

О том, как сам выбор между этими подходами устроен концептуально, читайте в spec-driven development vs vibe-coding. А о базовой модели работы агента — в статье что такое Claude Code.

Итог

Поток spec-kit — это инженерный конвейер: каждый шаг решает один класс проблем и защищает следующий. /specify фиксирует дыры честно, /clarify закрывает их до кода, /plan строит «как» с проверкой на принципы, /tasks дают прослеживаемость, /implement пишет код по контракту.

Важная оговорка: конкретный синтаксис команд и их поведение обновляются — перед работой сверяйтесь с актуальной документацией spec-kit.

Если хотите пройти этот поток на реальном fullstack-проекте от первого коммита до PR — с CoffeeCRM, конституцией и всеми пятью командами — посмотрите полный курс по Claude Code.