Урок 16.5. Справочник агентных команд `/speckit.*`

Зачем это нужно

Уроки 16.3 и 16.4 показали процесс на примерах. Этот урок - настольный справочник команд ядра SDD: назначение, аргументы, артефакты, выход и правила взаимодействия. Сюда возвращаются при работе: «что вернет /speckit.analyze?», «обязательна ли /speckit.clarify?», «как скопировать /speckit.implement на большую фичу?»

Параллельно урок фиксирует карту раздела Reference всей документации: где лежат справочники по CLI-примитивам (управляет терминальный specify) и где - по агентным процессам (запускает coding-агент). Первые разобраны в уроках 16.9-16.16, вторые - здесь и в уроках 16.6-16.7.

Основная идея

Команды /speckit.* ведут ядро Spec-Driven Development - агентный процесс, который coding-агент выполняет шаг за шагом. Команды спроектированы для запуска по порядку, но строго обязательна только /speckit.specify перед /speckit.plan. Команды clarify, checklist и analyze - quality gates, добавляемые для всего, где есть значимая неоднозначность.

/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan
-> /speckit.checklist -> /speckit.tasks -> /speckit.analyze
-> /speckit.implement -> /speckit.converge

Соглашение о написании: страница использует форму /speckit.*. Skills-режим GitHub Copilot по умолчанию пишет /speckit-*; некоторые агенты - $speckit-* (Codex, ZCode) или /skill:speckit-* (Kimi). Фазы не зависят от синтаксиса; полный разбор вариаций - в уроке 16.10.

Для оценки идеи до обязательства спецификацией существует отдельный процесс Agentic Idea Assessment (урок 16.7): опциональный и независимый от SDD.

Карта раздела Reference

Раздел Reference документации устроен так: сначала примитивы, управляемые CLI specify (core-команды, MCP-сервер, интеграции, расширения, пресеты, артефакты, workflows, бандлы - уроки 16.9-16.16), затем - агентные процессы, которые запускает не терминал, а ваш coding-агент:

• Agentic SDD - слэш-команды ядра SDD: constitution, specify, clarify, plan, checklist, tasks, analyze, implement, converge (этот урок);
• Agentic Bug Fix - bundled-расширение bug: триаж бага assess -> fix -> validate (урок 16.6);
• Agentic Idea Assessment - bundled-расширение assess: intake -> research -> definition -> shaping -> решение go / needs-clarification / kill (урок 16.7).

Обзор команд

После specify init команды доступны в выбранной интеграции. Интеграции с опциональным skills-режимом включают его флагом --integration-options="--skills"; некоторые, включая Copilot, используют skills по умолчанию.

/speckit.constitution

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

/speckit.constitution This project follows a "Library-First" approach. All features must be implemented as standalone libraries first. We use TDD strictly. We prefer functional programming patterns.

Более общий старт - попросить принципы по категориям:

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements.

/speckit.specify

Создает или обновляет спецификацию фичи из описания на естественном языке. Фокус - «что» и «зачем»: пользовательское поведение и цели. Технологический стек сюда не входит - его место в /speckit.plan.

Workflow может также поддерживать checklists/requirements.md - встроенный чек-лист качества спеки, который создает /speckit.specify и переоценивает /speckit.clarify. Этот жизненный цикл отделен от кастомных чек-листов команды /speckit.checklist.

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

/speckit.clarify

Задает до пяти целевых вопросов о недоопределенных областях текущей спеки и вкатывает ответы обратно в spec.md. Запускается сколько нужно раз до планирования - каждый раз по своей области. Опционально - фокус аргументом:

/speckit.clarify Focus on the task card behavior: status changes, comment limits, and who can be assigned.

Clarify до планирования не дает проектировать поверх двусмысленности. Если позже /speckit.analyze вскроет пробелы в требованиях - вернитесь и запустите /speckit.clarify (или /speckit.specify) снова.

Когда существует checklists/requirements.md, команда может обновить его оцененное состояние как часть ужесточения спеки. Исключение действует только для встроенного чек-листа требований, не для кастомных ревью-чек-листов.

/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.

Для примера с фотоальбомами выше:

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

/speckit.checklist

Генерирует чек-лист качества для фичи - «юнит-тесты для ваших требований». Он проверяет не код, а саму спеку: полна ли, ясна ли, однозначна ли, консистентна ли (например: «определены ли правила drag-and-drop для каждой колонки?», «специфицировано ли поведение при удалении назначенного пользователя?»).

Кастомные чек-листы этой команды - артефакты ревью качества требований, принадлежащие ревьюеру. Агент может помочь оценить их по явной просьбе, но реализация не должна молча самоутверждать пункты. В кастомном чек-листе [x] означает: ревьюер счел критерий качества требования выполненным; это не означает завершения работы по реализации.

Запуск без аргументов - широкий проход; с фокусом - прицельно:

/speckit.checklist

/speckit.checklist Focus on the Kanban board interactions and comment permissions.

Прочитайте сгенерированный чек-лист. Если вскрылись пробелы - вернитесь к /speckit.clarify или /speckit.specify, ужесточите спеку до разбивки работы, и отмечайте [x] только после ревью и выполнения критерия.

/speckit.tasks

Генерирует выполнимый tasks.md с учетом зависимостей из артефактов проектирования. Задачи организованы в фазы: Setup, Foundational (блокирующие пререквизиты), затем по одной фазе на user story в порядке приоритета, и финальная фаза Polish для сквозных забот. Тесты генерируются внутри фазы user story по запросу, а не отдельной фазой; задачи помечаются для параллельного исполнения, где возможно.

/speckit.tasks

/speckit.analyze

Выполняет read-only кросс-артефактный анализ консистентности и качества по spec.md, plan.md и tasks.md: конфликты, пробелы, неоднозначности (задача без соответствующего требования; решение в плане, противоречащее спеке). Файлы не редактирует - выдает отчет и может опционально предложить remediation на ваше утверждение.

/speckit.analyze

Запускайте до реализации, пока артефакты еще дешево менять. Если найдены проблемы - вернитесь на шаг, который ими владеет, и чините в источнике: /speckit.specify или /speckit.clarify для проблем требований, /speckit.plan для дизайна, /speckit.tasks для перегенерации списка задач. Повторяйте analyze, пока не станет чисто. Дополнительный запуск после реализации - как экстра-ревью.

/speckit.implement

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

Перед выполнением команда читает состояние чекбоксов чек-листов как ворота. Маркеры для нее read-only: /speckit.implement считает отмеченные и неотмеченные пункты и спрашивает подтверждение при непустом неотмеченном остатке, но не меняет маркеры. В кастомных чек-листах отмеченный пункт - одобрение ревьюером качества требований, а не завершенная реализация.

Малая фича - один запуск на все:

/speckit.implement

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

/speckit.implement Implement only the Setup and Foundational phases: project scaffolding and the project/task data model with basic CRUD. Stop before the user-story features.

/speckit.implement Now implement the Kanban board user story: drag-and-drop between columns.

Проверяйте каждую стадию до перехода к следующей.

/speckit.converge

Сверяет кодовую базу со спекой, планом и задачами фичи, чтобы подтвердить, что ничего не пропущено. Режим append-only: код не редактирует и не удаляет; единственная возможная запись - добавление задач в tasks.md. Запускать только после того, как /speckit.implement отработал на текущем tasks.md.

/speckit.converge

Сначала печатает сводку находок с градацией по серьезности, затем разрешается в один из двух исходов:

• Converged - пробелов нет. tasks.md остается байт-в-байт неизменным; вы увидите чистый результат вида ✅ Converged — the implementation satisfies the spec, plan, and tasks. Готово - переходите к ревью или открывайте PR.
• Tasks appended - найдены пробелы. Converge дописывает их новыми задачами в секцию Convergence в tasks.md и сообщает количество. Снова запустите /speckit.implement, затем /speckit.converge. Каждый проход находит меньше; повторяйте до Converged.

/speckit.taskstoissues

Опционально конвертирует существующий tasks.md в GitHub issues. Запускается после генерации задач, когда хотите вести исполнение в GitHub:

/speckit.taskstoissues

Требует GitHub-remote origin и доступа к GitHub MCP-инструментам (листинг и создание issues). Создает issues только в репозитории этого remote и проверяет существующие ID задач, чтобы избежать дубликатов. Для реализации задач и конвергенции команда не нужна.

GitHub-трекинг задач мигрирует из ядра в bundled, opt-in расширение github: /speckit.taskstoissues продолжает работать без изменений; namespaced-замена ставится командой specify extension add github (подробности установки и миграции - в README расширения).

Сводная таблица артефактов

Практика

1. Пройдите цепочку команд на своей фиче и после каждой зафиксируйте в таблице: какой артефакт создан/изменен, что вы проверили вручную. Сравните с таблицей артефактов этого урока.
2. Намеренно оставьте в спеке двусмысленность и проверьте: сколько вопросов задаст /speckit.clarify, что найдет /speckit.analyze, допишет ли что-то /speckit.converge.
3. Разбейте запуск /speckit.implement на две стадии аргументами и убедитесь, что гейт чек-листов срабатывает при неотмеченных пунктах.

Краткое резюме

Ядро SDD - десять агентных команд: обязательная пара specify -> plan, генераторы задач и чек-листов, три quality gates (clarify, checklist, analyze) и исполнительный контур implement -> converge. Ответственность распределена четко: analyze только читает, implement не трогает чек-листы, converge только дописывает задачи, ревьюер владеет отметками кастомных чек-листов.

Главное из урока:

• строго обязательна только /speckit.specify перед /speckit.plan; gates добавляются по неоднозначности;
• встроенный чек-лист checklists/requirements.md ведется specify/clarify; кастомные чек-листы - ревьюером, [x] не значит «реализовано»;
• при проблемах из analyze чинится источник: спека, план или задачи - не отчет;
• converge append-only и сходится за несколько проходов implement -> converge;
• /speckit.taskstoissues мигрирует в расширение github (specify extension add github).

Вопросы для самопроверки

1. Какая пара команд - единственная строго обязательная связка? Что делают quality gates и когда их добавлять?
2. Кто владелец отметок в кастомном чек-листе? Как /speckit.implement использует состояние чекбоксов?
3. Опишите два исхода /speckit.converge. Что команда может и чего не может записать на диск?
4. /speckit.analyze сообщила: задача в tasks.md не соответствует ни одному требованию. В каком порядке действовать?
5. Как устроена фазовая структура tasks.md (Setup, Foundational, user stories, Polish)? Где оказываются тесты?
6. Какие требования предъявляет /speckit.taskstoissues к окружению и куда мигрирует команда?

Что дальше

Ядро SDD закрывает создание фич. Следующий урок разбирает вторую точку входа - процесс исправления багов: расширение bug с триажем assess -> fix -> validate и каталогом .specify/bugs/.

Источники

• https://github.com/github/spec-kit/blob/main/docs/reference/overview.md
• https://github.com/github/spec-kit/blob/main/docs/reference/agentic-sdd.md