Spec Kit от GitHub: как превратить хаотичную работу с AI в структурированную разработку

В сентябре 2025 года GitHub представил Spec Kit — открытый инструментарий, который решает главную проблему разработки с AI: непредсказуемость результата. Если вы когда-либо получали от AI-агента код, который "вроде работает, но не совсем то", эта статья для вас.

Корень проблемы вайбкодинга

Типичный сценарий работы с AI сегодня выглядит так: разработчик бросает промпт "сделай фичу X", получает 500 строк кода, половина которых решает не ту задачу. Проблема не в способностях языковых моделей — они отлично распознают паттерны и генерируют код. Проблема в способе общения.

Когда вы говорите AI "добавь возможность делиться фотографиями", модель вынуждена догадываться о тысячах неуказанных деталей: публичный или приватный доступ, форматы файлов, ограничения размера, права пользователей, систему уведомлений. Большинство догадок окажется неверными, но вы узнаете об этом только на этапе тестирования или продакшена.

Что такое Spec-Driven Development

Spec-Driven Development (SDD) переворачивает традиционный подход. Вместо того чтобы писать спецификацию для галочки и забывать о ней, она становится исполняемым документом — единственным источником истины для всего процесса разработки.

Спецификация в SDD:

Управляет генерацией кода
Валидирует каждый этап
Содержит пользовательские сценарии и acceptance criteria
Учитывает архитектурные ограничения
Фиксирует технический долг и edge cases

GitHub создал Spec Kit как практическую реализацию этой методологии, совместимую с большинством современных AI-агентов.

Архитектура Spec Kit

Инструментарий состоит из двух компонентов:

Specify CLI — Python-инструмент для быстрой инициализации проектов. Загружает шаблоны из официального репозитория и настраивает структуру для выбранного AI-агента.

Набор шаблонов и скриптов — определяет структуру спецификаций, технических планов и разбивки на задачи. Включает bash-скрипты для Linux/macOS и PowerShell для Windows.

Никакой магии — вы можете управлять шаблонами вручную, скачав их из раздела Releases на GitHub.

Установка Spec Kit и первый запуск

Требования:

Python 3.11+
UV package manager
Git
AI-агент (Claude Code, GitHub Copilot, Cursor, Gemini CLI, Qwen, opencode, Windsurf или другие)

Установка занимает две минуты:

# Установка UV (если нет)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Установка Spec Kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Проверка
specify check

Инициализация проекта:

# Новый проект с выбором агента
specify init my-project --ai claude

# В текущей директории
specify init . --ai cursor

# С форсированием (если папка не пуста)
specify init --here --force --ai copilot

После инициализации получаете структуру:

.specify/
├── memory/ # Конституция проекта
├── scripts/ # Автоматизация
├── specs/ # Спецификации фич
└── templates/ # Шаблоны документов

Пятиэтапный процесс разработки в Spec Kit

Этап 1: /constitution — Установка правил игры

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

/constitution Проект использует минимум внешних зависимостей.
Покрытие тестами не ниже 80%. TypeScript в strict mode.
REST API соответствует OpenAPI 3.0. UI-компоненты переиспользуемые
и задокументированные. Time to Interactive не превышает 3 секунды.

AI создаёт файл .specify/memory/constitution.md, который становится фундаментом для всех последующих решений. Это решает проблему, когда модель добавляет ненужные библиотеки или нарушает архитектурные соглашения.

Этап 2: /specify — Определение цели

Описываете что вы строите и зачем, избегая технических деталей:

/specify Система управления задачами для команды из 5 человек.
Пользователи: 1 product manager + 4 разработчика (захардкожены,
без аутентификации в MVP). Три проекта с 5-15 задачами в каждом.
Kanban-доски с колонками: To Do, In Progress, In Review, Done.
Drag-and-drop задач между статусами. Комментарии к задачам
(редактирование и удаление только своих). Задачи текущего
пользователя выделены цветом.

AI генерирует:

Подробную спецификацию в Markdown
Пользовательские истории с acceptance criteria
Перечень ограничений и edge cases
Git-ветку для фичи (например, 001-task-manager)
Файл specs/001-task-manager/spec.md

Этап 3: /clarify — Уточнение требований

После создания базовой спецификации обязательно запустите команду /clarify. Это структурированная сессия вопросов-ответов, где AI выявляет неявные требования и заполняет пробелы в спецификации.

Пример вопросов, которые может задать AI:

Как система обрабатывает одновременное редактирование одной задачи двумя пользователями?
Должны ли комментарии поддерживать форматирование (Markdown)?
Есть ли лимит на количество задач в одном проекте?
Нужны ли уведомления при изменении статуса задачи?

Ответы записываются в секцию Clarifications спецификации. Этот этап критичен — пропуск приведёт к переделкам на стадии реализации.

Этап 4: /plan — Технический план

Указываете стек, архитектуру, инфраструктуру:

/plan Backend: .NET 8 + ASP.NET Core + PostgreSQL.
ORM: Entity Framework Core. Frontend: Blazor Server
с SignalR для real-time updates. Drag-and-drop через
SortableJS. Docker Compose для локальной разработки.
API соответствует REST принципам с OpenAPI документацией.

AI создаёт комплект документов:

plan.md — общий технический план
data-model.md — схема базы данных
contracts/api-spec.json — OpenAPI спецификация
contracts/signalr-spec.md — описание real-time событий
research.md — исследование специфики стека
quickstart.md — инструкция для локального запуска

Полезно попросить AI проверить актуальность выбранного стека:

Проверь research.md на соответствие локально установленным
версиям .NET. Изучи best practices для .NET Aspire,
выпущенные за последние 3 месяца.

Этап 5: /analyze — Проверка консистентности

Команда /analyze проверяет согласованность всех артефактов:

Все ли требования из spec.md покрыты в plan.md?
Нет ли противоречий между документами?
Все ли API endpoints задокументированы в контрактах?
Учтены ли edge cases из спецификации?

Запускается после /clarify и /plan, но до генерации задач.

Этап 6: /tasks — Декомпозиция на задачи

/tasks

AI разбивает технический план на атомарные задачи с зависимостями:

## Phase 1: Infrastructure
- [ ] Настроить .NET Aspire AppHost
- [ ] Создать Docker Compose с PostgreSQL
- [ ] Настроить EF Core миграции

## Phase 2: Data Layer (можно параллельно)
- [ ] Создать Entity модели: Project, Task, User, Comment
- [ ] Настроить связи через Fluent API
- [ ] Написать seed data для тестовых пользователей

## Phase 3: API (зависит от Phase 2)
- [ ] ProjectsController: GET /api/projects
- [ ] TasksController: GET /api/tasks?projectId={id}
- [ ] TasksController: PUT /api/tasks/{id}/status
- [ ] CommentsController: POST /api/tasks/{id}/comments
...

Каждая задача включает:

Acceptance criteria
Зависимости от других задач
Пометки о возможности параллельного выполнения
Ссылки на соответствующие секции в плане

Этап 7: /implement — Реализация

/implement

AI начинает последовательно выполнять задачи:

Парсит tasks.md и строит граф зависимостей
Выполняет задачи в правильном порядке
Параллелит независимые задачи (если помечены)
Запускает тесты после каждой задачи
Логирует прогресс и ошибки

Вместо ревью тысяч строк кода сразу, вы проверяете фокусные изменения под каждую конкретную задачу.

Важно: AI будет запускать CLI-команды (dotnet build, npm install, docker-compose up). Убедитесь, что все инструменты установлены.

Практические сценарии использования Spec Kit

Greenfield-проекты (0→1)

Начинаете с чистого листа. Инвестиция 30-60 минут в спецификацию и план гарантирует, что AI построит именно то, что задумано.

Пример: Разработчик создал сервис сокращения URL с нуля за один рабочий день — от /constitution до задеплоенного приложения с тестами и документацией.

Добавление фич (N→N+1)

Работаете с существующей кодовой базой. Спецификация заставляет прояснить, как новая функциональность взаимодействует с текущей системой:

Какие API endpoints затронуты?
Нужны ли миграции БД?
Влияет ли изменение на производительность?
Как обновить существующие тесты?

План кодирует архитектурные ограничения, чтобы AI не сломал работающую логику.

Совет: При работе вне Git-веток используйте переменную окружения SPECIFY_FEATURE=002-new-feature.

Модернизация Legacy

Захватываете бизнес-логику старой системы в современной спецификации, проектируете новую архитектуру, переписываете без технического долга.

Процесс:

Создаёте спецификацию, описывающую текущее поведение системы
Уточняете бизнес-правила и edge cases (часто недокументированные)
Проектируете современную архитектуру с учётом новых требований
Реализуете постепенную миграцию через feature flags

Параллельные реализации и A/B-тестирование

Одна из уникальных возможностей Spec Kit — создание нескольких технических планов для одной спецификации:

Спецификация: REST API для системы бронирования

План A: Node.js + Express + MongoDB
План B: Python + FastAPI + PostgreSQL
План C: Go + Gin + Redis + PostgreSQL

AI реализует каждый вариант в отдельной Git-ветке. Сравниваете по критериям:

Скорость разработки
Производительность под нагрузкой
Размер Docker-образа
Сложность поддержки

Выбираете лучший вариант на основе реальных метрик, а не догадок.

Корпоративное внедрение

Для крупных организаций Spec Kit решает проблему разрозненных требований. Вместо того чтобы держать в голове или Wiki-страницах:

Политики информационной безопасности
Compliance требования (GDPR, SOC2, HIPAA)
Стандарты доступности (WCAG)
Корпоративную дизайн-систему
Обязательные интеграции (SSO, логирование, мониторинг)

Всё это закладывается в constitution.md и автоматически учитывается AI на каждом этапе.

Дополнительные опции для корпораций:

# Использование корпоративного токена GitHub
specify init project --ai claude --github-token ghp_company_token

# Пропуск SSL-проверки (для корпоративных прокси)
specify init project --skip-tls

# Режим отладки для troubleshooting
specify init project --debug

Поддерживаемые AI-агенты

Spec Kit разработан агностично к платформе. Полная поддержка:

Claude Code — наиболее стабильная интеграция
GitHub Copilot — встроенная поддержка
Cursor — полная совместимость
Gemini CLI — официально поддерживается
Qwen Code — работает из коробки
opencode — протестировано
Windsurf — поддерживается
Kilo Code — совместимо
Auggie CLI — работает
Roo Code — поддерживается

Ограниченная поддержка:

Codex CLI — не поддерживает кастомные аргументы для slash-команд, некоторые функции могут работать некорректно

Сравнение Spec Kit с альтернативами

Amazon выпустила Kira — первый фреймворк, сфокусированный на spec-driven development. Spec Kit выделяется:

Преимущества перед Kira:

Открытый исходный код (MIT лицензия)
Более широкая поддержка AI-агентов
Активное сообщество (30.4k звёзд на GitHub)
Более гибкая система шаблонов
Кросс-платформенность (bash + PowerShell скрипты)

Зависимость от качества модели:
Результаты варьируются в зависимости от выбранного AI. GPT-4, Claude Sonnet 3.5 и Gemini 1.5 Pro показывают лучшие результаты при работе со Spec Kit. Более слабые модели могут пропускать детали или неверно интерпретировать спецификации.

Реальный кейс: Pokedex Team Builder

Чтобы проиллюстрировать процесс, рассмотрим реальный проект:

Задача: Создать приложение для составления команд покемонов с учётом типов, статистики и синергии.

Фаза Specify

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

Фаза Plan

Frontend: React + TypeScript + TailwindCSS. State management: Zustand.
Data source: PokeAPI. Локальное хранилище: IndexedDB через Dexie.js.
Алгоритм оптимизации команды: взвешенный граф покрытия типов.
Деплой: Vercel.

Фаза Tasks

AI разбил на 23 задачи, сгруппированные в фазы:

Настройка инфраструктуры (5 задач)
Интеграция с PokeAPI (4 задачи)
UI компоненты (8 задач)
Алгоритм оптимизации (3 задачи)
Локальное хранилище (2 задачи)
Тестирование и деплой (1 задача)

Результат

Функциональное приложение за 4 часа разработки (включая время на уточнения и тестирование). Минимум переделок, чистый код, покрытие тестами 85%.

Troubleshooting и частые проблемы

Git Credential Manager на Linux

Если возникают ошибки аутентификации Git:

wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
git config --global credential.helper manager
rm gcm-linux_amd64.2.6.1.deb

AI игнорирует конституцию

Проблема: AI добавляет библиотеки, запрещённые в constitution.md.

Решение: Явно напомните AI о конституции в промпте к /plan:

Создай план, строго следуя принципам из constitution.md.
Перед добавлением любой зависимости проверь соответствие конституции.

Задачи выполняются в неправильном порядке

Проблема: AI пытается реализовать API до создания моделей данных.

Решение: В /tasks явно укажите зависимости:

## Phase 2: API (зависит от Phase 1)
Примечание: Не начинать до завершения Phase 1

Слишком крупные задачи

Проблема: AI создаёт задачу "Реализовать весь backend".

Решение: Попросите разбить:

Разбей задачу "Реализовать backend" на атомарные подзадачи.
Каждая задача должна занимать не более 1-2 часов работы
и иметь чёткий acceptance criteria.

Текущая статистика проекта

По состоянию на октябрь 2025 года:

30,400 звёзд на GitHub
2,600 форков
212 наблюдателей
55 релизов (последний: 1 октября 2025)
35 контрибьюторов
Лицензия: MIT

Активная разработка, еженедельные релизы с улучшениями и поддержкой новых агентов.

Почему Spec Kit работает

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

JWT или сессии?
Какой провайдер (локальный, OAuth, SAML)?
Период жизни токена?
Refresh token logic?
Rate limiting?
Password policies?

Большинство решений не совпадут с вашими ожиданиями.

Spec Kit устраняет неопределённость на каждом уровне:

Конституция задаёт незыблемые правила
Спецификация детализирует бизнес-логику и UX
План фиксирует технические решения
Задачи разбивают на атомарные единицы работы

AI получает ясность и генерирует именно тот код, который нужен.

Будущее spec-driven development

Spec Kit позиционируется как стандарт индустрии для AI-assisted разработки. Методология SDD решает фундаментальную проблему: разрыв между намерениями разработчика и интерпретацией AI.

Ожидаемые тренды:

Интеграция SDD в IDE и AI-агенты по умолчанию
Появление маркетплейсов готовых спецификаций
Стандартизация форматов spec-документов
Инструменты для автоматической генерации спецификаций из существующего кода

GitHub активно развивает проект, добавляя поддержку новых агентов и расширяя функциональность CLI.