Spec-Kit: Полное руководство для начинающих
Пошаговое объяснение Spec-Driven Development — от «что это» до работающего проекта. Никаких предварительных знаний о SDD не требуется.
1 Что такое SDD?
Spec-Driven Development (SDD) — это методология разработки, в которой вы сначала пишете подробную спецификацию (описание того, что должна делать программа), а потом AI-агент автоматически генерирует из неё рабочий код.
В обычной разработке спецификация — это черновик, который забрасывают, когда начинают писать код. В SDD спецификация — это главный источник правды, из которого код генерируется и перегенерируется.
Пять принципов SDD
- Намерение важнее кода — сначала описываете что и зачем, а не как
- Спецификация — артефакт — это не записка на салфетке, а структурированный документ, который живёт весь проект
- Итеративное уточнение — цикл: описать → уточнить → спланировать → сгенерировать задачи → проверить → реализовать
- AI выполняет работу — вы мыслите, AI кодит. Поддерживается 30+ агентов
- Не привязан к стеку — один и тот же процесс работает для Python, Go, React, .NET, Java и любых других технологий
Представьте, что вы заказываете дом. Вы не берёте молоток — вы создаёте подробный чертёж (спецификацию), а строитель (AI-агент) строит по нему. Если хотите изменить планировку — меняете чертёж, а не ломаете стены.
2 Сравнение подходов
Чтобы лучше понять, чем SDD отличается от привычной работы:
Обычная разработка
- × Написали примерную спецификацию (или вообще пропустили)
- × Сразу начали писать код, по ходу выясняя детали
- × Спецификация устарела на второй день
- × Каждый разработчик понимает задачу по-своему
- × Рефакторинг = переписывание кода
SDD со Spec-Kit
- ✓ Подробная, структурированная спецификация
- ✓ AI генерирует код из спецификации
- ✓ Изменили спецификацию → перегенерировали код
- ✓ Единый источник правды для всей команды
- ✓ Конституция проекта не даёт AI нарушать стандарты
3 Что нужно для начала
Перед установкой убедитесь, что у вас есть:
| Компонент | Требование | Как проверить |
|---|---|---|
| Python | Версия 3.11 или выше | python3 --version |
| uv (рекомендуется) | Менеджер пакетов | uv --version |
| Git | Любая актуальная версия | git --version |
| AI-агент | Любой из 30+ поддерживаемых | Например: claude --version |
Установите через: curl -LsSf https://astral.sh/uv/install.sh | sh
Или используйте pipx как альтернативу.
4 Установка
Шаг 1: Установить specify-cli
$ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Если не хотите устанавливать глобально:uvx --from git+https://github.com/github/spec-kit.git specify init my-project
Шаг 2: Проверить установку
$ specify version # Должно показать версию, например: specify-cli v0.8.2 $ specify check # Проверит все зависимости
5 Первый проект
Давайте создадим проект с нуля. Допустим, мы хотим сделать приложение-список задач (todo-app) и используем Claude Code как AI-агент.
1. Инициализация
$ specify init todo-app --integration claude # Создаст папку todo-app/ со структурой .specify/ # и настроит интеграцию с Claude Code $ cd todo-app
claude, copilot, cursor, windsurf, gemini, codebuddy, pi, generic и другие. Полный список: specify integration list
2. Запускаем рабочий процесс
Теперь откройте свой AI-агент (например, Claude Code) в папке проекта и последовательно выполняйте слэш-команды:
# 1. Определяем «конституцию» проекта — правила и стандарты /speckit.constitution # 2. Описываем, что должно делать приложение /speckit.specify # 3. Планируем техническую реализацию /speckit.plan # 4. Генерируем конкретные задачи /speckit.tasks # 5. AI реализует код /speckit.implement
На каждом шаге AI-агент будет задавать вам вопросы и показывать результат. Не торопитесь — проверяйте и корректируйте сгенерированные документы перед переходом к следующему шагу. В этом и заключается контроль SDD.
3. Что происходит на каждом шаге
Каждая команда создаёт файл-артефакт в папке .specify/. Следующая команда использует артефакты предыдущих шагов. Подробнее — в разделе «7 шагов SDD».
6 7 шагов SDD
Кликните на каждый шаг, чтобы увидеть подробности. Шаги выполняются последовательно — каждый опирается на результаты предыдущих.
Что делает: Устанавливает «законы» проекта — архитектурные принципы, стандарты интерфейсов, методологию разработки, требования к качеству.
Зачем: Все последующие шаги (и сам AI-агент при написании кода) обязаны соблюдать конституцию. Это предотвращает ситуации, когда AI принимает решения, противоречащие вашим стандартам.
Пример: «Архитектура — REST API + SPA. Тесты обязательны для каждой фичи. Максимальный размер функции — 50 строк.»
Что делает: Описывает функциональные требования без технических деталей. Формулирует пользовательские сценарии с приоритетами P1 (критично), P2 (важно), P3 (желательно).
Зачем: Это этап «что», а не «как». Вы описываете поведение с точки зрения пользователя.
Пример: «P1: Пользователь может создавать задачи и перетаскивать их между колонками. P2: Поддержка совместной работы в реальном времени.»
Что делает: AI находит неоднозначности и пробелы в спецификации и задаёт уточняющие вопросы. Пункты, помеченные [NEEDS CLARIFICATION], прорабатываются здесь.
Зачем: Лучше потратить 5 минут на уточнение, чем 2 часа на переделку кода. Можно также запустить /speckit.checklist для проверки полноты.
Что делает: Выбирает технический стек, определяет архитектуру, описывает структуру проекта, проверяет соответствие конституции.
Зачем: Именно здесь принимаются технические решения: язык, фреймворк, база данных, стратегия тестирования. Всё это основано на спецификации, а не придумано «на ходу».
Пример решений: «React 18 + Express + PostgreSQL + Jest. Docker для деплоя.»
Что делает: Разбивает план на конкретные задачи, сгруппированные по фазам: Настройка → Фундамент → Пользовательские истории (P1, P2, P3) → Полировка.
Особенности: Задачи помеченные [P] можно выполнять параллельно. Каждая задача привязана к конкретной пользовательской истории из спецификации.
Что делает: Перекрёстная проверка всех артефактов: нет ли противоречий между спецификацией, планом и задачами.
Зачем: Ловит несоответствия до того, как начнётся написание кода. Необязательный, но полезный шаг — особенно для больших проектов.
Что делает: AI-агент берёт все подготовленные артефакты (конституцию, спецификацию, план, задачи) и генерирует рабочий код.
Важно: Для сложных проектов лучше реализовывать фазами, чтобы не перегружать контекст AI. Конституция проекта соблюдается на протяжении всего процесса.
7 Демо: как это выглядит
Выберите сценарий и посмотрите, как выглядит типичная сессия в терминале:
8 Структура файлов
После specify init в вашем проекте появится папка .specify/ со следующей структурой:
Папку .specify/ стоит коммитить в Git — это позволяет всей команде использовать одни и те же спецификации и настройки.
9 Поддерживаемые AI-агенты
Spec-Kit не привязан к конкретному AI-инструменту. Вы выбираете того, который вам удобен:
Claude Code
CLI от Anthropic. Глубокая интеграция.
GitHub Copilot
В VS Code или через CLI.
Cursor
AI-first IDE.
Windsurf
IDE от Codeium.
Gemini CLI
Google AI в терминале.
Generic
Для любого другого агента.
Несколько агентов в одном проекте
Разные члены команды могут использовать разные агенты. Интеграции хранятся в изолированных папках и не конфликтуют:
# Добавить несколько агентов в один проект: $ specify integration install claude $ specify integration install copilot # Переключиться: $ specify integration switch claude # Посмотреть все доступные: $ specify integration list
10 Справочник команд
Здесь собраны все команды. Слэш-команды выполняются внутри AI-агента, CLI-команды — в обычном терминале.
| Команда | Описание |
|---|---|
/speckit.constitution | Определить принципы и стандарты проекта |
/speckit.specify | Описать требования и пользовательские сценарии |
/speckit.clarify | Уточнить неоднозначности в спецификации |
/speckit.checklist | Проверить полноту спецификации |
/speckit.plan | Создать техническую стратегию реализации |
/speckit.tasks | Сгенерировать список задач из плана |
/speckit.analyze | Перекрёстная проверка всех артефактов |
/speckit.implement | Запустить генерацию кода |
| Команда | Описание |
|---|---|
specify init <name> | Создать новый SDD-проект |
specify init <name> --integration <agent> | Создать проект с конкретным агентом |
specify check | Проверить, что все зависимости установлены |
specify version | Показать версию |
specify integration install <key> | Добавить интеграцию с агентом |
specify integration switch <key> | Переключить агент по умолчанию |
specify integration list | Список всех доступных агентов |
specify workflow run speckit -i spec="..." | Запустить весь цикл одной командой |
| Команда | Описание |
|---|---|
specify preset add [id] | Установить пресет (например, lean, scaffold) |
specify preset set-priority | Задать порядок приоритетов пресетов |
specify preset enable <name> | Активировать установленный пресет |
specify preset disable <name> | Деактивировать без удаления |
| Команда | Описание |
|---|---|
specify extension search [query] | Найти расширения в каталоге |
specify extension add <name> | Установить расширение |
specify extension list | Показать установленные расширения |
specify extension update [name] | Обновить расширение(я) |
specify extension info <name> | Информация о расширении |
specify extension catalog add <url> | Добавить свой каталог |
11 Сценарии использования
Сценарий A: Новый проект с нуля (Greenfield)
Вы начинаете с пустой папки. Описываете, что хотите — Spec-Kit проводит вас через весь цикл от идеи до работающего приложения.
$ specify init kanban-app --integration claude $ cd kanban-app # Далее в Claude Code: /speckit.constitution → /speckit.specify → ...
Сценарий B: Добавление фичи в существующий проект (Brownfield)
У вас уже есть кодовая база. Spec-Kit встраивается в неё, анализирует существующую архитектуру и генерирует код, который ей соответствует.
$ cd my-existing-project $ specify init . --integration copilot # Spec-Kit создаст .specify/ рядом с вашим кодом # Существующий код не затрагивается
SDD успешно применялся на кодовых базах с 300K+ строк кода (.NET, Java, Go).
Сценарий C: Сравнение технических стеков (Creative Exploration)
Одна и та же спецификация, разные реализации. Создайте два проекта, скопируйте spec.md в оба и запланируйте их с разными стеками:
$ specify init chat-react --integration claude $ specify init chat-svelte --integration gemini # Скопируйте spec.md из одного в другой # Запустите /speckit.plan в каждом — получите разные решения
12 Настройка и расширения
Spec-Kit можно настраивать на нескольких уровнях. Более высокий уровень перекрывает более низкий:
| Приоритет | Уровень | Где хранится | Для чего |
|---|---|---|---|
| #1 (высший) | Ваши переопределения | .specify/templates/overrides/ | Ваши уникальные шаблоны для этого проекта |
| #2 | Пресеты | Устанавливаются через CLI | Готовые наборы настроек (lean, scaffold и др.) |
| #3 | Расширения | .specify/extensions/ | Новые возможности и команды (91+ в каталоге) |
| #4 (низший) | Встроенные шаблоны | Внутри Spec-Kit | Значения по умолчанию |
Что такое пресеты?
Пресеты меняют как работают существующие шаги. Они могут переопределять шаблоны, терминологию и стандарты. Например, пресет lean упрощает процесс, а кастомный пресет может переименовать «спецификацию» в «манифест путешествия».
Что такое расширения?
Расширения добавляют совершенно новые возможности: новые команды, доменные процессы, интеграции с внешними системами. В каталоге сообщества 91+ расширений.
На старте вам не нужны ни пресеты, ни расширения. Начните с базового рабочего процесса и добавляйте кастомизацию, когда поймёте, что именно хотите изменить.
13 Частые вопросы
specify init . --integration <agent> в папке проекта. Spec-Kit создаст .specify/ рядом с вашим кодом, не затрагивая существующие файлы. Протестировано на проектах с 300K+ строк.generic: specify init my-project --integration generic. Она создаёт настраиваемую конфигурацию, которая работает с любым агентом, способным читать контекстные файлы..claude/skills, Copilot — свои контекстные файлы. Конфликтов нет.14 Глоссарий
| Термин | Что означает |
|---|---|
| SDD | Spec-Driven Development — разработка, управляемая спецификациями |
| Конституция | Набор правил и стандартов проекта, которые AI обязан соблюдать |
| Спецификация (spec) | Описание того, что должна делать система, с точки зрения пользователя |
| Артефакт | Файл-результат каждого шага (constitution.md, spec.md, plan.md, tasks.md) |
| AI-агент | Инструмент с AI, который выполняет генерацию кода (Claude Code, Copilot и др.) |
| Слэш-команда | Команда вида /speckit.xxx, которую вы набираете внутри AI-агента |
| Пресет | Набор настроек, меняющий поведение существующих шагов |
| Расширение | Плагин, добавляющий новые возможности в Spec-Kit |
| Greenfield | Новый проект с нуля |
| Brownfield | Добавление функциональности в существующий проект |
| P1 / P2 / P3 | Уровни приоритета: P1 = критично, P2 = важно, P3 = желательно |
| [P] | Метка задач, которые можно выполнять параллельно |