Зачем это нужно
Урок 16.2 оставил нас с установленным CLI и инициализированным проектом. Этот урок проходит ядро Spec Kit - Spec-Driven Development - от первого промпта до состояния «Converged» на одном сквозном примере. После него вы будете знать: какую команду запускать на каждом шаге, что писать в аргументах, какой артефакт появляется на выходе и где контролировать качество.
Это та же цепочка, которую вводил урок 2.8, но теперь - с точным синтаксисом, порядком и критериями перехода между шагами. Используйте SDD, чтобы строить фичу или приложение из спецификации; для починки есть процесс багфикса (урок 16.6), для решения о вложениях - оценка идей (урок 16.7). Это независимые процессы, не пререквизиты друг друга.
Основная идея
SDD в Spec Kit - это последовательность агентных команд. Вы вызываете их по одной в чате coding-агента, проверяете результат каждой и только потом переходите к следующей. Это навыки агента (skills), а не терминальные команды; терминал нужен только для установки CLI и настройки проекта.
Сквозной пример документации - Taskify, небольшая платформа командной продуктивности: предопределенные пользователи создают проекты, назначают задачи, комментируют и двигают задачи по Kanban-колонкам (To Do, In Progress, In Review, Done). Пять пользователей (один продакт-менеджер, четыре инженера), три примерных проекта, без логина в первой фазе.
Автоматизационные скрипты проект получает в вариантах Bash (.sh), PowerShell (.ps1) и Python (.py); интерактивный specify init предложит выбрать, неинтерактивные запуски возьмут вариант по умолчанию для ОС (явно - --script sh|ps|py).
В примерах ниже используется синтаксис skills-режима GitHub Copilot по умолчанию: /speckit-*. Для других агентов и режимов написание отличается (урок 16.10), но фазы и порядок одинаковы.
Отслеживание активной фичи
Прежде чем запускать команды, важно понять, как Spec Kit знает, с какой фичей вы работаете.
Активная фича отслеживается по каталогу фичи, записанному в .specify/feature.json (переопределяется переменной окружения SPECIFY_FEATURE_DIRECTORY). Команды резолвят фичу из этого состояния, а не из проверенной Git-ветки - Git вообще не обязателен. Opt-in git-расширение добавляет нумерованные ветки фич (например, 001-feature-name) для организации работы в версионном контроле, но активная фича - по-прежнему та, на которую указывает состояние; git checkout само по себе ее не меняет. Чтобы переключить команды на другую фичу, обновите .specify/feature.json (или задайте SPECIFY_FEATURE_DIRECTORY).
Два пути процесса
После установки каждая команда ниже - шаг процесса. Распространены два пути. Конституция устанавливается один раз на проект командой /speckit-constitution до старта любого из путей.
Короткий путь - для небольших фич:
/speckit-specify -> /speckit-plan -> /speckit-tasks -> /speckit-implement -> /speckit-converge
Полный путь - для production-фич; добавляет /speckit-clarify, /speckit-checklist и /speckit-analyze как quality gates:
Шаг 0: установка и инициализация
В терминале установите CLI с PyPI (требуется uv) и инициализируйте проект:
uv tool install specify-cli
specify init taskify --integration copilot
cd taskify
init позволяет выбрать агента интерактивно или явно через --integration. Для CI и harness-ов агентов добавьте --non-interactive, чтобы неуказанные выборы получали документированные дефолты вместо зависания на пикере. Предпочитаете pipx, разовый uvx, пин релиза или offline/air-gapped - см. урок 16.2. Добавляете Spec Kit в репозиторий с существующим кодом - сначала гайд для существующих проектов (урок 16.17).
Запустите coding-агент в каталоге проекта и вызывайте навыки в его чате - по одному за раз.
Шаг 1: /speckit-constitution - установить правила игры
Устанавливает руководящие принципы проекта, против которых оценивается каждый последующий шаг. Запускается один раз в начале, принципы передаются аргументами:
/speckit-constitution Taskify is a "Security-First" application. All user inputs must be validated. We use a microservices architecture. Code must be fully documented.
Что важно: принципы формулируются в терминах ограничений и стандартов («все входные данные должны валидироваться», «код должен быть полностью документирован»), а не в терминах фич. Конституция пишется в .specify/memory/constitution.md и читается командами plan, tasks и analyze при каждом запуске (runtime resolution, урок 16.2).
Шаг 2: /speckit-specify - описать, что строим
Создает спецификацию фичи из описания на естественном языке. Фокус - на «что» и «зачем», не на технологическом стеке:
/speckit-specify Develop Taskify, a team productivity platform where predefined users create projects, assign tasks, comment, and move tasks across Kanban columns (To Do, In Progress, In Review, Done). Five users (one product manager, four engineers), three sample projects, no login for this first phase.
Обратите внимание, что содержит и что сознательно исключает промпт: пользователи и их роли, сущности (проекты, задачи, комментарии), поведение (перемещение по колонкам), границы первой фазы (без логина). Технологии не упоминаются - их время придет на шаге /speckit-plan.
Результат - spec.md в каталоге фичи (specs/001-taskify/spec.md в типичном проекте).
Шаг 3: /speckit-clarify - снять неоднозначности
Задает целевые вопросы обо всем недоопределенном и вкатывает ваши ответы обратно в спеку, чтобы вы не планировали поверх двусмысленности. Запускается до планирования, опционально с фокус-областью:
/speckit-clarify Focus on task card behavior — status changes, comment permissions, and user assignment.
Практика: фокус сужает вопросы. Без него агент спросит обо всей спеке сразу; со скопом - о конкретной области (здесь: смены статусов карточек, права на комментарии, назначение исполнителей).
Шаг 4: /speckit-plan - выбрать технический стек
Генерирует артефакты проектирования из спеки. Вот где место деталям реализации - передайте стек и архитектуру:
/speckit-plan Use .NET Aspire with Postgres. The frontend is Blazor Server with drag-and-drop boards and real-time updates. Expose REST APIs for projects, tasks, and notifications.
Результат - plan.md: технический подход, компоненты, API, решения по данным. Секция Constitution Check в плане заполняется из живой конституции при каждом запуске.
Шаг 5: /speckit-checklist - проверить спеку
Генерирует кастомный чек-лист качества - «юнит-тесты для ваших требований» - чтобы подтвердить, что спека полна, ясна и консистентна до разбивки работы:
/speckit-checklist
Семантика чек-листов важна. Кастомные чек-листы - артефакты ревью качества требований, принадлежащие ревьюеру: пункт отмечается [x] только когда ревьюер решил, что критерий качества требования выполнен. Отмеченные кастомные пункты не означают, что работа по реализации завершена.
Шаг 6: /speckit-tasks - разбить работу
Генерирует выполнимый tasks.md с учетом зависимостей из артефактов проектирования:
/speckit-tasks
Задачи упорядочены по зависимостям - то, что нужно другим задачам, стоит раньше. Этот порядок затем использует /speckit-implement.
Шаг 7: /speckit-analyze - проверить консистентность
Отчитывается о конфликтах, пробелах и неоднозначностях между spec.md, plan.md и tasks.md. Команда read-only: если она нашла проблемы - исправьте их в источнике и перезапустите до начала реализации:
/speckit-analyze
Это третья контрольная точка качества полного пути: конституция задала принципы, checklist проверил требования, analyze сверил артефакты друг с другом.
Шаг 8: /speckit-implement - построить
Выполняет задачи из tasks.md в порядке зависимостей:
/speckit-implement
Нюансы поведения. Перед реализацией команда читает состояние чекбоксов чек-листов как ворота и спрашивает подтверждение, если какие-то пункты не отмечены; сами файлы чек-листов и маркеры она не меняет. Встроенный чек-лист checklists/requirements.md ведется командами /speckit-specify и /speckit-clarify, кастомные чек-листы остаются за ревьюером. Для больших фич можно запускать команду пофазно, а не один раз на все.
Шаг 9: /speckit-converge - проверить полноту
Сверяет кодовую базу со спекой, планом и задачами. Если найдены пробелы - дописывает новые задачи в tasks.md; тогда запустите /speckit-implement и снова converge, пока не получите статус Converged:
/speckit-implement
/speckit-converge
Если отчет сходится - вы закончили: переходите к ревью или открывайте PR. Конвергенция закрывает цикл: спецификация, с которой начинали, и код, который получился, сверены друг с другом.
Ключевые принципы
Документация закапсулировала дух процесса в пяти правилах:
- Будьте точны в том, что строите и зачем;
- Не фокусируйтесь на стеке в фазе спецификации;
- Итерируйте и уточняйте спецификации до реализации;
- Валидируйте требования и планы до начала кодинга;
- Позвольте агенту заниматься деталями реализации.
Типичная ошибка новичка - нарушить второе правило: вписать фреймворки в /speckit-specify. Тогда спека смешивает требования с решениями, и /speckit-plan не остается пространства для проектирования; шаблоны и guardrails ядра специально разводят эти слои.
Куда двигаться дальше
Полный справочник по каждой команде - аргументы, вывод, пофазная реализация, взаимодействие - в уроке 16.5. Кастомизация процесса расширениями, пресетами, workflows и бандлами - урок 16.11. Полная методология - в документе spec-driven.md репозитория; сравнение core-шаблонов с community-walkthrough-ами показывает, как SDD применяется в реальных проектах (урок 16.19).
Практика
- Пройдите полный путь на примере Taskify или собственной маленькой фичи: от
/speckit-constitutionдо первого/speckit-converge. После каждого шага открывайте артефакт (spec.md,plan.md,tasks.md) и читайте его до перехода дальше. - Сравните два запуска
/speckit-clarify: без аргументов и с фокус-областью. Чем отличаются заданные вопросы? - После
/speckit-analyzeвнесите вtasks.mdзадачу, противоречащуюspec.md, и перезапустите analyze - посмотрите, как выглядит отчет о конфликте.
Краткое резюме
SDD-quickstart - это девять агентных команд, вызываемых по одной с ревью результата каждой. Короткий путь (specify -> plan -> tasks -> implement -> converge) годится для малых фич; полный добавляет три quality gates: clarify до планирования, checklist после плана, analyze перед реализацией. Активная фича tracked-ится в .specify/feature.json, а не в Git-ветке. Цикл завершается, когда /speckit-converge сообщает Converged: код сверен со всеми артефактами.
Главное из урока:
- спецификация - про «что и зачем», план - про «как»; не смешивайте их в промптах;
- чек-листы - артефакты ревьюера:
[x]означает качество требования, а не завершение работы; /speckit-analyzeread-only: чините источники, а не отчет;- converge-цикл (
implement -> converge -> implement) - норма, а не ошибка: новые задачи вtasks.mdозначают, что процесс работает.
Вопросы для самопроверки
- Чем короткий путь SDD отличается от полного? Для каких фич документация рекомендует полный путь?
- Почему не стоит указывать технический стек в
/speckit-specify? В какой команде его место? - Как Spec Kit определяет активную фичу? Что нужно сделать, чтобы переключить команды на другую фичу?
- Что означает отметка
[x]в кастомном чек-листе? Кто владелец этого решения? /speckit-analyzeнашла конфликт междуspec.mdиtasks.md. Опишите правильную последовательность действий.- Что делает
/speckit-converge, когда находит пробелы? Когда цикл считается завершенным?
Что дальше
Быстрый старт показывает механику, но не то, как процесс живет в реальной разработке. Урок 16.4 разбирает agentic SDLC - как сам проект Spec Kit использует собственные процессы для оценки, строительства, тестирования и починки изменений.