Как настроить Spec Kit в Claude Code в 2026: спецификации вместо промптов

Каждый день в Telegram-канале - что нового в вайб-кодинге: инструменты, истории, ошибки. Подпишись, чтобы быть в курсе.

Что случилось с вайб-кодингом в мае 2026?

В феврале 2025 года Карпатый написал в X пост, который сделал из «vibe coding» культурный термин: тип кодинга, где ты «отдаёшься вайбу, принимаешь экспоненту и забываешь, что код вообще существует, потому что LLM становятся слишком хороши». За год это стало синонимом любой работы с ИИ-агентом без структуры.

Через год, 4 февраля 2026, он опубликовал ретро-тред:

В докладе на Sequoia Ascent 2026 он сформулировал ещё точнее: «Вайб-кодинг поднимает пол - сколько каждый может сделать в софте. Agentic engineering сохраняет потолок - качественную планку профессиональной разработки». На той же сцене он бросил фразу, которая вошла в индустриальный лексикон: «Тебе не разрешается заносить уязвимости из-за вайб-кодинга. Ты всё так же отвечаешь за свой софт, как и раньше».

Параллельно случилось три вещи. В сентябре 2025 GitHub опубликовал инструмент Spec Kit - за 8 месяцев он собрал 107 000 звёзд. DeepLearning.AI с JetBrains выпустили программу Spec-Driven Development with Coding Agents. AWS в феврале 2026 показал подробный разбор на drug discovery с цифрой «95% бизнес-логики сгенерировано из спецификации, экономия 80+ часов».

К концу мая 2026 в англоязычном инфополе сформировался консенсус: вайб-кодинг как метод работы - это начальный уровень. Дальше идёт Spec-Driven Development. На русском про это ещё ничего нет - этот гайд закрывает дыру.

Что такое Spec Kit и Spec-Driven Development?

Главная мысль методологии - в одной строчке из официальной документации GitHub:

На практике это разворачивается в 4 фазы (Spec Kit добавляет ещё одну, нулевую - constitution, про неё ниже):

1. Specify - пишешь спецификацию того, что хочешь, на естественном языке. ЧТО делать и ЗАЧЕМ. Без КАК.
2. Plan - агент берёт спецификацию и собирает технический план: какие технологии, какая архитектура, какие куски.
3. Tasks - агент режет план на конкретные проверяемые задачи с зависимостями.
4. Implement - агент (или его субагенты) идёт по задачам и пишет код.

Каждая фаза - отдельный markdown-файл в репо. Каждая фаза - отдельный slash-вызов в Claude Code: /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement. Если на любом шаге что-то пошло не так, ты редактируешь markdown-файл и запускаешь следующую фазу заново.

Spec Kit - это конкретная реализация SDD. В мае 2026 у него уже более 30 интеграций с разными ИИ-агентами. Внутри одного репо Spec Kit одинаково работает с Claude Code, Cursor, GitHub Copilot, Codex CLI, Windsurf, Qwen, Tabnine, Amazon Q, Gemini, Goose и ещё дюжиной.

То есть после прогона у тебя в репо лежит не только код, но и его спецификация, план и задачи. Через месяц ты вернёшься в проект, прочитаешь spec.md - и поймёшь, что и зачем там делалось. Это уже не «вайб-кодинг забыл, что код существует» - это рабочая память проекта.

Зачем это вайб-кодеру, который не пишет код?

Кто был на практикуме по смысло-кодингу - в SDD увидит мою методологию с апреля 2026 года. В эфире третьего потока я формулирую это так:

То, что Артемий делал руками (4 чата вместо одного), Spec Kit формализует через 4 slash-команды. Логика та же: разделить «продумывание» и «реализацию» так, чтобы они шли в разных контекстных окнах. Каждый этап получает чистый контекст, не загаженный предыдущей фазой.

Три конкретные выгоды для вайб-кодера:

• Предсказуемость. Когда ты задаёшь агенту «сделай форму регистрации с подтверждением по почте», он угадывает 10 деталей сам - и три из них угадает не так, как у тебя в голове. Когда у тебя spec.md с User Stories, Acceptance Scenarios и пометками [NEEDS CLARIFICATION] на каждом сомнительном месте, угадывать нечего.
• Память проекта. Через месяц ты не вспомнишь, что обсуждал с агентом в чате. А spec.md, plan.md и tasks.md лежат в репо в папке specs/###-feature/ рядом с кодом. Тебе показывают не только что сделано, но и зачем.
• Масштаб. На фичу из 1-2 файлов разница незаметна. На фиче, где задействовано 20 файлов и 5 сущностей данных, разница - между «через 4 часа всё переписывать» и «через 4 часа всё уехало в основную ветку». AWS Kiro в проекте TargetID показал 95% автоматизации бизнес-логики из спецификации.

Главный обман вайб-кодинга в том, что он выглядит быстрее на старте. Полчаса - и есть прототип. Но к недельной отметке прототип ломается, и его проще выбросить. Spec-Driven Development на старте чуть дольше (час вместо получаса), а через неделю ты всё ещё работаешь в том же репо.

Как установить Spec Kit в Claude Code (4 шага)

Шаг 1. Поставить uv. Это нужно один раз, потом он живёт у тебя в системе.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Проверь, что uv установился:

uv --version

Шаг 2. Установить Spec Kit. Одна команда:

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

Проверь:

specify --version

Шаг 3. Инициализировать репо. Заходи в папку своего проекта (или создай новый) и запусти:

specify init

Тебе зададут 2-3 вопроса:

• Какой ИИ-агент будешь использовать? - выбирай Claude Code.
• Куда положить шаблоны? - оставляй дефолт (./templates).
• Использовать ли встроенный Constitution? - отвечай Yes (это твой проектный CLAUDE.md в терминах Spec Kit).

После этого в репо появятся:

.specify/
  templates/
    spec-template.md
    plan-template.md
    tasks-template.md
    CLAUDE-template.md
.claude/
  commands/
    speckit.constitution.md
    speckit.specify.md
    speckit.plan.md
    speckit.tasks.md
    speckit.implement.md
    speckit.clarify.md
    speckit.analyze.md
memory/
  constitution.md

Шаг 4. Открыть Claude Code и проверить slash-команды. Запусти в той же папке:

claude

Внутри сессии набери / - в подсказках должны появиться speckit.* команды. Если не появились, перезапусти Claude Code, чтобы он перечитал .claude/commands/. Если у тебя уже есть CLAUDE.md в корне проекта, Spec Kit его не трогает - он работает рядом, в memory/constitution.md.

Spec Kit без Claude Code тоже работает (он поддерживает 30+ агентов), но в этом гайде я разбираю связку именно с Claude. Если хочешь сразу поставить два инструмента, посмотри отдельные гайды по настройке CLAUDE.md и Plan Mode в Claude Code.

Spec Kit - это первый кирпичик «трудового договора агента». На моём практикуме по вайб-кодингу мы собираем все три: ИИ-клон (твоя методология в виде Skills и subagents), Второй мозг (структура business/, к которой агент возвращается каждый раз), и контекст-инжиниринг (Spec Kit, Plan Mode, /compact). Три кита, без которых ИИ галлюцинирует.

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

+Твой второй мозг

3 вечера - стек, метод, первый проект

Старт 9–11 июня  ·  2 000 ₽

Записаться →

Как написать первую спецификацию (Specify)

В Claude Code набираешь:

/speckit.specify

Дальше агент попросит описание фичи. На этом шаге - простыми словами, без технического жаргона:

Я хочу форму регистрации в моём приложении. Пользователь вводит email
и пароль, получает письмо с подтверждением, после подтверждения
попадает на дашборд. Если письмо не подтверждено за 48 часов,
аккаунт удаляется.

Агент сам соберёт specs/001-registration/spec.md. Открой его - увидишь структуру:

# Feature Specification: User Registration

**Feature Branch**: `001-registration`
**Created**: 2026-05-31
**Status**: Draft
**Input**: User Description: "Я хочу форму регистрации..."

## User Scenarios & Testing *(mandatory)*

### Primary User Story
As a new user, I want to register an account with email confirmation,
so that I can access the dashboard with a verified identity.

### Acceptance Scenarios
1. **Given** I am on the registration page,
   **When** I submit valid email and password,
   **Then** I receive a confirmation email within 1 minute.
2. **Given** I clicked the confirmation link within 48 hours,
   **When** I land on the dashboard,
   **Then** I see my email confirmed in profile.
3. **Given** I have not confirmed within 48 hours,
   **When** the cron job runs,
   **Then** my account is deleted and email is freed for re-registration.

## Requirements *(mandatory)*

### Functional Requirements
- **FR-001**: System MUST accept registration via [NEEDS CLARIFICATION:
  email/password only, or also SSO/OAuth?]
- **FR-002**: System MUST send confirmation email within 60 seconds
- **FR-003**: System MUST delete unconfirmed accounts after 48 hours
- **FR-004**: System MUST log all registration attempts for [NEEDS
  CLARIFICATION: how long do we retain logs - 30 days, 90 days, forever?]

### Key Entities
- User: email, password_hash, email_verified_at, created_at, deleted_at
- ConfirmationToken: token, user_id, expires_at, used_at

## Success Criteria *(mandatory)*
- **SC-001**: 95% of confirmation emails delivered within 60 seconds (p95)
- **SC-002**: 0 accidental deletions of confirmed accounts
- **SC-003**: Registration completion rate > 60% (from form open to dashboard)

Внимание на маркеры [NEEDS CLARIFICATION: ...]. Spec Kit намеренно их вставляет везде, где агент не получил однозначного ответа из твоего текста. До перехода в Plan-фазу ты должен либо ответить на них вручную в spec.md, либо запустить /speckit.clarify - и агент сам пройдётся по неясным местам и задаст вопросы в диалоге.

Этот ход - формализация того, что я делаю в эфире:

В Spec Kit вместо устного «задай мне вопросы» - встроенная команда /speckit.clarify. Suffix-эффект тот же: ты не идёшь в Plan, пока в spec.md не осталось ни одного [NEEDS CLARIFICATION].

Что в spec.md НЕ должно быть - это технологии. Никаких упоминаний React, Postgres, Prisma, Redis. Спецификация говорит о том, что система делает с точки зрения пользователя и бизнеса. Технологический стек придёт в следующей фазе.

Что Claude делает в фазе Plan?

Когда spec.md готов, запускаешь:

/speckit.plan

Опционально передаёшь технологические подсказки прямо в команде:

/speckit.plan Next.js App Router, Prisma, PostgreSQL, Resend для писем

Claude читает три источника: твой spec.md, твой CLAUDE.md (или memory/constitution.md) и существующий код в репо. На выходе ты получаешь plan.md примерно такой структуры:

# Implementation Plan: User Registration

## Technical Context
- Framework: Next.js 14 App Router
- Database: PostgreSQL via Prisma
- Email: Resend (single transport)
- Validation: Zod schema in shared lib
- Auth: NextAuth.js with credentials provider

## Architecture Decisions

### 1. Token storage
Tokens stored in DB (table ConfirmationToken), not in JWT.
Reason: need server-side revoke on email re-register.

### 2. Email delivery
Async via cron `/api/cron/send-confirmation` triggered immediately
after registration. Retries handled by Resend.

### 3. Auto-delete cron
Daily cron `/api/cron/cleanup-unconfirmed` deletes rows where
created_at < NOW() - INTERVAL '48 hours' AND email_verified_at IS NULL.

## Data Model
See data-model.md

## API Contracts
See contracts/
- POST /api/auth/register
- POST /api/auth/confirm
- GET /api/auth/resend-confirmation

## Implementation Phases
1. Database migration (Prisma schema + migration file)
2. API routes (3 endpoints)
3. UI: registration form + confirmation success page
4. Cron jobs (send + cleanup)
5. Email template
6. Integration tests

В data-model.md будет описание сущностей со связями. В contracts/ - заглушки API-контрактов (либо OpenAPI YAML, либо TypeScript-типы запросов/ответов). Это не код - это намерения, которые Claude потом превратит в реальные роуты.

Главное преимущество фазы Plan - чистый контекст. Claude не пытается одновременно держать в голове и спецификацию, и реализацию. Он сначала продумывает, потом фиксирует решение в файле, потом идёт дальше.

Здесь же работает и опциональная команда /speckit.analyze - она прогоняет связку spec.md + plan.md через ревью: нет ли противоречий, все ли требования из спека покрыты планом, все ли архитектурные решения мотивированы. По сути - формальный sanity-check перед фазой Tasks.

Как разделить на задачи (Tasks)

После того как у тебя есть spec.md и plan.md, запускаешь:

/speckit.tasks

Claude разворачивает план в tasks.md:

# Tasks: User Registration

## Phase 1: Database (no dependencies)
- [ ] T-001: Add User model to prisma/schema.prisma (parallel-safe)
- [ ] T-002: Add ConfirmationToken model to prisma/schema.prisma (after T-001)
- [ ] T-003: Generate migration `add-user-registration` (after T-002)

## Phase 2: API contracts (no dependencies)
- [ ] T-004: Create Zod schemas in shared/validation/auth.ts
- [ ] T-005: Define TypeScript types in shared/types/auth.ts (after T-004)

## Phase 3: Routes (depends on Phase 1+2)
- [ ] T-006: Implement POST /api/auth/register
- [ ] T-007: Implement POST /api/auth/confirm
- [ ] T-008: Implement GET /api/auth/resend-confirmation

## Phase 4: UI (parallel with Phase 3)
- [ ] T-009: Build /register page with form
- [ ] T-010: Build /register/confirm/[token] page
- [ ] T-011: Build /register/success page

## Phase 5: Cron + integration (depends on Phase 3+4)
- [ ] T-012: Cron /api/cron/send-confirmation
- [ ] T-013: Cron /api/cron/cleanup-unconfirmed
- [ ] T-014: Email template registration-confirmation.tsx
- [ ] T-015: Integration tests (Playwright)

## Notes
- T-001, T-004, T-009-T-011 are parallel-safe (different files)
- T-002 conflicts with T-001 (same file: schema.prisma) - run sequentially
- T-006 needs T-003 (migration applied) and T-005 (types)

Обрати внимание на пометки parallel-safe и after T-NNN. Это и есть граф зависимостей, который позволяет потом запустить несколько фаз параллельно. На этой механике стоит весь Spec Kit-подход к ускорению: какие-то задачи можно отдать пяти разным сессиям Claude Code одновременно, какие-то - строго последовательно.

То же я говорю в эфире первого потока, когда показываю свой подход:

Spec Kit делает это автоматически в одной команде - сразу из коробки.

Опциональная команда /speckit.taskstoissues берёт tasks.md и создаёт GitHub Issues по списку - каждая с ссылкой обратно на spec.md. Удобно, если ты работаешь в команде или хочешь смотреть прогресс через GitHub Projects.

Как реализовать через subagent'ов (Implement)

/speckit.implement

Claude начинает с первой задачи в tasks.md. Каждая задача проходит маленький цикл: прочитать relevant-файлы, написать диф, прогнать тесты, отметить [x]. Subagent'ы вызываются автоматически там, где это нужно: для кодревью отдельный, для запуска линтера отдельный, для проверки на регресс - отдельный.

Boris Cherny, создатель Claude Code в Anthropic, описывает тот же подход короче:

И отдельно про правила:

В Spec Kit этот цикл формализован. У тебя есть spec.md как источник правды, plan.md как технические решения, tasks.md как чек-лист. Если на каком-то шаге Claude уходит в сторону, ты возвращаешься к спецификации и говоришь: «Не совпадает с FR-003, переделай». Никаких длинных промптов «помнишь, мы обсуждали...» - вся история есть в файлах.

Если ты подключил Dynamic Workflows из Opus 4.8, Spec Kit можно отдать на полный авто-режим: одна команда /speckit.implement и Claude сам параллелит, сводит результаты, проверяет. Лимит - 1000 субагентов одновременно. Для большинства фич хватает 10-30.

После того как все [x] отмечены, ты ревьюишь PR (или серию PR, если задач много) и мерджишь. Артефакты - spec.md, plan.md, tasks.md - остаются в репо как документация фичи. Через год тебе не придётся реверс-инжинирить логику из кода.

Чем Spec Kit отличается от CLAUDE.md и Plan Mode?

Сравни их по 5 признакам:

Артемий формулирует роль CLAUDE.md как «трудовой договор»:

В терминах Spec Kit это memory/constitution.md. Spec Kit при инициализации может либо взять твой существующий CLAUDE.md за основу для constitution, либо создать рядом отдельный файл. Я обычно держу CLAUDE.md как глобальный «контракт» (стек, словарь, deploy-протокол), а constitution Spec Kit использую для специфичных под фичу правил - например, «все формы валидируются через Zod, никаких ручных проверок».

С Plan Mode связь ещё проще. Plan Mode - это быстрый режим «спланируй прежде чем писать код» внутри одной сессии. Он отлично работает для маленьких изменений (поправь баг, отрефакторь функцию). Для большой фичи Plan Mode проигрывает, потому что контекстное окно одной сессии слишком мало для плана на 3000 строк - я в эфире прямо про это рассказываю:

Spec Kit - это и есть конкретный инструмент контекст-инжиниринга. Он переносит «скатерть архитектуры» из чата в файлы. Spec.md лежит в репо постоянно, и каждая новая сессия Claude её перечитывает - не приходится повторять.

Связка для большого проекта:

1. CLAUDE.md - стек, словарь, что нельзя делать. Лежит в корне.
2. memory/constitution.md Spec Kit - правила специфичные под этот workflow.
3. specs/001-feature-A/spec.md, plan.md, tasks.md - первая фича.
4. specs/002-feature-B/spec.md, plan.md, tasks.md - вторая фича.
5. На каждый день работы - либо /speckit.implement (по готовым задачам), либо /plan (быстрая перепроверка перед изменением).

Какие истории реально работают?

Конкретные истории:

• AWS Kiro - drug discovery agent. В блоге AWS Industries от 18 февраля 2026 команда описывает проект TargetID. Три разработчика, три недели, агент для drug discovery. Цифры из материала: Kiro сгенерировал больше 95% кода бизнес-логики, сэкономив больше 80 часов разработки. Параллельно: «README documentation written by Kiro saved us an estimated 8 hours» и «40% fewer iterative prompt-and-fix cycles».
• Rackspace Technology. В том же блоге AWS приводит цифры Rackspace: «completed 52 weeks of estimated work in just 3 weeks», «90% increase in efficiency». Это уже не маленькая фича - это полный корпоративный проект.
• Фитнес-приложение от Mariya Mansurova (Towards Data Science). В её статье 12 мая 2026 разработчица описывает, как собрала фитнес-приложение от концепта до рабочей версии за 4 часа 30 минут с помощью SDD-подхода. Она цитирует Карпатого как точное описание сдвига: «Programming via LLM agents is increasingly becoming a default workflow for professionals, except with more oversight and scrutiny» - программирование через LLM-агентов стало рабочим стандартом для профессионалов, просто с большим контролем.
• GitHub Spec Kit рост. На 7 мая 2026 у репо было 93 000 звёзд (по данным MarkTechPost), на 31 мая - 107 000. То есть +14 000 звёзд за три недели. Эта скорость роста - явный сигнал, что подход забирает рынок.
• Boris Cherny (Claude Code). Сам создатель Claude Code использует похожий 3-фазный подход: research → plan (пишутся spec.md, design.md, tasks.md) → implementation в новом окне с чистым контекстом. По его словам, он держит 5 терминальных экземпляров Claude Code одновременно плюс ещё 5-10 веб-сессий на claude.ai/code.

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

Когда Spec Kit НЕ подходит?

Не подходит #1 - маленькие правки. Если задача «переименуй переменную», «исправь typo в копирайте», «добавь log», прогон через Specify → Plan → Tasks займёт больше времени, чем сама правка. Birgitta Böckeler из Thoughtworks пишет об этом прямо: «Я предпочту прочитать код, чем все эти markdown-файлы». Для маленьких правок Plan Mode или просто прямой промпт в Claude Code работают быстрее.

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

Не подходит #3 - легаси с сложным состоянием. Команда Isoform в материале от 25 ноября 2025 даёт сильный контр-аргумент: «Реальность меняется быстрее, чем спецификации». Они приводят пример с биллингом подписок: команда описала billing cycles и tax rules, через неделю финансы попросили European VAT - спека устарела до релиза. Когда бизнес-логика быстро эволюционирует, поддержка спеков превращается в долг.

Дополнительный риск - ложное чувство контроля. Материал Martin Fowler разбирает это: структуры элегантны, но агенты часто игнорируют инструкции или, наоборот, слишком буквально следуют шаблонам. На выходе ты получаешь код, который по структуре правильный, но к твоему конкретному репо не подходит - спека не гарантирует, что агент её понял так, как ты задумал.

Thoughtworks Radar в апреле 2026 предупреждал про waterfall: писать большую спецификацию перед кодом - это путь, который уже один раз погубил индустрию во времена 200-страничных требований. Инженеры с того времени относятся к подходу осторожно, и эта осторожность обоснована.

Что с этим делать. Я предлагаю простое правило: размер фичи vs время на спецификацию. Если фича займёт меньше 2 часов реализации, не пиши спеку - быстрее через Plan Mode. Если фича займёт неделю - обязательно через Spec Kit, экономия времени окупит часовую спецификацию пятикратно. Между 2 часами и неделей - на твоё усмотрение, но я лично пишу спеку даже на полдневные фичи, потому что артефакт в репо стоит дороже сэкономленных 30 минут.

Что дальше: как встроить Spec Kit в свой проект?

Конкретный план на ближайшие 7 дней:

• День 1. Установи uv и Spec Kit (5-10 минут). Проверь, что /speckit.* команды появились в твоём Claude Code. Не пытайся применять на существующем проекте - возьми новый.
• День 2. Возьми реальную фичу, которую планируешь делать. Прогон /speckit.specify с описанием в свободной форме. Открой spec.md, прочитай, ответь на все [NEEDS CLARIFICATION]. Не торопись с переходом к Plan.
• День 3. Прогон /speckit.plan с подсказками твоего стека. Прочитай plan.md, особенно секцию Architecture Decisions. Если что-то не нравится - редактируй вручную, потом запусти /speckit.analyze для перепроверки.
• День 4-5. Прогон /speckit.tasks и /speckit.implement. Смотри, как Claude отмечает [x] в tasks.md. Где-то он застрянет - это нормально. Возвращайся к spec.md, уточняй требование, перезапускай /speckit.implement с конкретной задачей.
• День 6-7. Сделай ревью PR (или серии PR). Смерджи. Прочитай свои spec.md и plan.md - это твоя документация фичи на ближайший год.

Что я бы предложил почитать параллельно:

• Как настроить CLAUDE.md в 2026 - основа констуции Spec Kit.
• Plan Mode в Claude Code - быстрая альтернатива для маленьких задач.
• Контекст-инжиниринг в 2026 - почему Spec Kit вообще работает.
• Skills, Subagents, MCP или Plugins - чем дополнить Spec Kit для своего рабочего потока.
• Dynamic Workflows в Claude Code - как запустить много субагентов сразу для фазы Implement.

Полная схема по вайб-кодингу за вечер: ИИ-клон + Второй мозг + Контекст-инжиниринг. Три эфира, две тысячи рублей. Записи остаются у тебя.

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

+Твой второй мозг

3 вечера - стек, метод, первый проект

Старт 9–11 июня  ·  2 000 ₽

Записаться →